Module Registry
The Facets Module Registry is a searchable catalogue of system and custom modules in a control plane, with metadata, preview/published states, and usage maps.
The Module Registry is a centralized, searchable catalogue of every infrastructure module in a Control Plane (CP), giving teams a single source of truth for discovering and managing reusable building blocks across environments and projects.
A new control plane's registry is empty. Modules arrive when you import a project type, which loads the official set for your cloud, and when your organisation publishes its own.
In Facets, a module is defined by a unique combination of intent, flavor, and version.
Build your module on this page opens the Praxis module-building experience. See the Praxis documentation for how that experience works.
The Registry Table
Modules are listed with their source, status, stage, supported clouds, version, and last-modified time.
Source and stage answer different questions. Source tells you where a module came from: a System module, shipped by Facets, or a Custom module your organisation authored. Stage tells you where it sits in its lifecycle, preview or published. A module can be Custom and published, Custom and preview, or System.
Each module offers three actions. View Details opens its full metadata, Publish Module promotes a preview module to published, and Delete Module removes it from the control plane.
Deleting a module is permanent. Check its usage map first — deleting a module that projects or environments still reference will break them.
What the Registry Includes
Every module entry carries the following metadata:
| Field | Description |
|---|---|
| Intent | The core capability offered by the module (e.g., redis, vpc) |
| Flavor | The specific implementation of the intent (e.g., memorystore, terraform-aws) |
| Version | The semantic version of the module (e.g., 1.0, 2.0) |
| Description | A short summary of what the module provisions |
| Spec | The developer-facing configuration schema (drives UI form) |
| Sample | An example configuration (helps drive JSON form rendering) |
| Inputs | Cross-module typed inputs (e.g., dependencies on @facets/kubernetes-details) |
| Outputs | Declared module outputs that can be consumed by other modules |
| ReadMe | Module-level documentation for usage, behavior, and examples |
| Clouds Supported | Cloud providers (e.g., AWS, GCP, Azure) the module supports |
| Usage Map | Projects and environments where the module is currently used in the control plane |
Custom Module-Specific Metadata
Custom modules carry extra metadata to support governance and lifecycle workflows:
| Field | Description |
|---|---|
| Last Modified By | The user who last updated the module |
| Last Modified At | Timestamp of the most recent modification |
| GitHub Repo Link | Points to the source repository of the module, if linked |
The GitHub repo link is the module's recorded provenance. When you upload a module from a git work tree, Facets captures the source repository URL and the commit SHA. If your organisation has connected a modules repo, provenance enforcement compares those values against that repository on every publish. See Modules Repo for the enforcement modes and their behaviour on a mismatch.
Module State
Custom modules exist in one of two states:
- Preview: Modules in active development or validation. Use them in test projects to experiment and verify behavior. This is the default state when a module is first registered locally via the CLI.
- Published: Modules reviewed and considered production-ready. These are available across all projects in the Control Plane and visible to all users.
Permissions and organizational policy govern promotion from preview to published.
Two behaviours matter before you rely on preview modules:
- A preview module takes precedence over its published sibling. Wherever preview modules are permitted, Facets resolves the preview version first. That lets you exercise a branch build without disturbing anyone else. Everywhere preview is not permitted, Facets returns only the published version.
- A module built from a feature branch cannot be published from the UI. Publishing is also disabled for a module that is already published and has no newer preview.
Modules Repo
This page is also where you connect the git repository your custom modules are published from. When nothing is attached yet, choose Connect repo; afterwards the registry shows the repository's status and lets you manage it.
Connecting a modules repo lets your team publish from reviewed git history, and lets Facets check each publish against that repository.
See Modules Repo for the two connect routes, what migration writes into your repository, provenance enforcement, and CI token rotation.
Output Types
Output Types opens the registry's view of the @facets/* and @custom/* type schemas that modules declare and consume. These schemas define the shape of the values one module hands to another, and module inputs and outputs reference them by name.
Permissions
Viewing the registry requires MODULE_READ, publishing and building modules MODULE_WRITE, deleting MODULE_DELETE, and managing the modules repo MODULE_REPO_MANAGE. Without MODULE_READ, the page shows an Access Forbidden message asking you to contact your admin. Without MODULE_REPO_MANAGE, the modules repo controls are disabled. Modules Repo covers modules repo permissions in full.
Using the Registry
Related
- Modules Repo - Connect a git repository and govern where modules are published from
- Continuous Integration - How CI validates modules on a pull request and publishes them on merge
- Versioning Strategy - How to version modules and when to cut a new one
- Building a Facets Module - The module authoring contract
- API Reference - Programmatic access to modules and the modules repo
Versioning Strategy
How Facets modules version safely: major versions in facets.yaml for breaking changes, soft versioning for compatible updates, and per-version directories.
AWS IAM in modules
Declaratively manage AWS IAM roles and policies in Facets service modules, attaching policies from managed resources and custom policies for unmanaged ones.