Module Registry

What is Module Registry?

The Module Registry is Firefly's Terraform Private Registry feature that allows you to centrally store, manage, and share Terraform modules across your organization. It provides a secure, private repository where your team can publish reusable infrastructure code modules and consume them directly in your Terraform configurations. This enables better collaboration, standardization, and governance of your infrastructure as code across all your projects.

Importing a Module

Follow these steps to import a module into your private registry:

Navigate to the Import Module feature

1. Click IaC Explorer in the left sidebar.

2. Click the Modules tab.

3. Click the Import Module button.

Configure the module import

The import modal opens with the following fields:

• Module name: Enter the name under which the module will be stored in your registry

• Provider type: Select the cloud provider this module is associated with (e.g., AWS, Azure, GCP)

• Version: Enter the module version (e.g., 1.0.0)

• VCS integration: Select your version control system integration

• Repository: Select the repository that contains the module

• Branch: Select the branch to import from

• Working directory (optional): Specify the path within the repository where the module lives; defaults to / if left blank. You must choose the base module directory—if the module is nested under another directory layer, it will not work.

Import the module

Once all values are valid, click the "Import" button.

Verify the import

After clicking import, the modal will close and the module will appear in the modules table. Note that this action might take a few minutes to complete.

Access the module call block

Click the + button next to your module in the table to reveal the module call block that you can use in your main.tf file.

Credentials Setup

To import modules from Firefly's Terraform Private Registry, you'll need to configure authentication for your environment.

Generate a JWT for the Module Registry

Before configuring your local or CI/CD environment, you need to create a JWT (JSON Web Token) that will be used to authenticate with the Terraform Private Registry.

Create an API key pair

1. In the Firefly web console, go to Settings and click Access Management.

2. Create an API key pair using either:

   • Users tab — Create a user API key (each user does this for their own access).

   • Service Account tab — Generate a key for the service account (recommended; assign only the permissions required for the registry).

Generate the JWT

Use your API key pair (Access Key and Secret Key) to generate a JWT via the Firefly API. For the request body and full details, see the Authentication section.

When calling the login endpoint, you can optionally set a duration field to define how long the token is valid. If duration is omitted, the token does not expire.

You can use the Module Registry from Firefly in three ways: integrated CI (e.g., GitHub Actions) Firefly runners. Choose the setup below that matches your workflow. locally (on your machine)

GitHub Actions Setup

When using Firefly's Module Registry in GitHub Actions workflows, you need to provide the authentication token during the Terraform initialization stage. This token allows Terraform to authenticate with the private registry and download the required modules.

Add the following step to your GitHub Actions workflow:

- name: Terraform Init
  env:
    TF_TOKEN_api_firefly_ai: ${{ secrets.TF_CLOUD_TOKEN }}
  run: terraform init

Make sure to store your Firefly authentication token (generated in the previous step) as a GitHub secret (e.g., TF_CLOUD_TOKEN) in your repository settings.

Firefly Runners

When running Terraform from a Firefly workspace (Firefly runners), provide the registry token as a workspace variable so that terraform init can authenticate with the private registry.

1. Open your workspace and go to Variables Configuration (in the workspace setup or Edit Workspace Variables).

2. Under Variables, add a new variable:

   • Variable name: TF_TOKEN_api_firefly_ai

   • Variable value: with the JWT generated in the Generate a JWT for the Module Registry section above.

3. Enable Sensitive value and Environment variable so the token is available to Terraform and not displayed in logs.

Local Setup

Configure Terraform credentials

In your ~/.terraform.d/credentials.tfrc.json file, add the following configuration:

{
 "credentials": {
  "api.firefly.ai": {
    "token": "<your-generated-token>"
  }
 }
}

Replace <your-generated-token> with the JWT generated in the Generate a JWT for the Module Registry section above.

Use the module in your Terraform configuration

Once the setup is complete, you can reference modules from the registry using the standard module block syntax:

module "example-module" {
  source  = "api.firefly.ai/firefly-authority/example-module/aws"
  version = "8.2.0"
}