Module Registry

env0 Module Registry

The env0 Module Registry is a private registry for sharing and reusing OpenTofu/Terraform modules, within your organization. You can access your organization’s module registry through the Registry tab in the Organization Menu.

Using env0’s private registry enhances security by ensuring that only authorized users have access to approved infrastructure modules, reducing the risk of deploying unverified code. It also offers improved version control, customization, and compliance, helping teams maintain consistency and enforce governance across different environments.

By centralizing the management of Terraform modules, teams can ensure they are using standardized, reliable code while retaining flexibility to adapt to specific needs.

Adding a module to the registry

In order to add a module to your registry, go to the Module Registry screen and click on “CREATE NEW MODULE” in the top right. Only organization administrators are authorized to create new modules.

First, you must enter the general details for your module:

• A name for your module - This can be any string of your choice.
• The provider the module belongs to - This too can be any string of your choice.

These two choices will affect how your module is used (see 'Using a module in your code'). The combination of name and provider must be unique within your organization’s modules.

The description will be shown to members of your team when they browse the module registry. It is a useful way of summarizing what the module does and when it should be used.

Next, you must connect to the VCS provider, where your module’s source code is stored.

Click on the VCS provider you’d like to use. After you’ve authorized env0 to access your repositories, select a repository from the dropdown menu and enter the folder where module files are stored (defaults to root folder).

That’s it! Click “Create” to save your work and create the new module.

Module versioning

In order to use a module, it must be versioned using a SemVer format (e.g. 1.0.0). The versions must be applied to your source repository as Git tags.

Versioning modules for mono-repo

When using a mono-repo for managing several modules, a team might come across the need to tag and manage versions for each module individually.

In order to do that, you have to assign a tag prefix to identify a specific module's version in env0.

For example, to tag a module named module1, we may assign the prefix m1.
When we'd use the tags m1/1.0.0, m1/1.2.4, the versions for the module in env0 will be 1.0.0 and 1.2.4

The delimiter is a single dash / and there is no need to write it in the Tag Prefix input.

📘

Terraform restrictions on tags

Terraform enforces using a valid SemVer string as a version. Tagging with a prefix will only allow you to use the SemVer part and not the tag directly when using a module from env0's private registry that is configured to use the tag prefix.

Using a module in your code

In order to use a module from the env0 Module Registry in your Terraform code, you must reference it like this:

module "my-module" {
  source = "api.env0.com/{organization-id}/{module-name}/{module-provider}"
  version = "1.0.0"
}

You can find this exact snippet, pre-filled with your values, in the Instructions tab of your module page.

🚧

Using a module from Gitlab Enterprise Edition or BitBucket Server

In order to enable Gitlab Enterprise or Bitbucket Server as a module registry you are required to set an env0 custom flow that will run the following command on after setup variables.

git config --global url.https://$ENV0_VCS_ACCESS_TOKEN@$GIT_ADDR/.insteadOf https://$GIT_ADDR/

This command will instruct git CLI to use the authorized URL for checking out the code, where ENV0_VCS_ACCESS_TOKEN is an environment variable populated by env0 with the access token for the VCS system and GIT_ADDR is the domain of your VCS.

env0.yml

version: 2
 
deploy:
  steps:  
    setupVariables:  
      after:  
        - export GIT_ADDR="mygleeserver.example"  
        - git config --global url.https://$ENV0_VCS_ACCESS_TOKEN@$GIT_ADDR/.insteadOf https://$GIT_ADDR/

Using a module locally (or from a different env0 Organization)

When you deploy your Terraform code through env0, login to the env0 Module Registry is handled for you. If you’d like to run the same code locally, in a CI environment, or in a different env0 Organization, you will need to supply the authentication details to Terraform. Follow the guide on how to authorize when using a private registry for more info.

The Modules List

The Modules List page is available to every user in the organization by clicking on “Module Registry” in the organization’s menu (bottom left of the screen).

On this page you can see which modules have been set up for your organization. You can use the search box to locate specific modules by name, provider, description, or the users who created them.

The Module Page

You can get to the Module page by clicking on a module from the Modules List.

Here you can see the details of your Module.

The Versions dropdown menu at the top right allows you to switch between the different versions of your module. Versions are linked to Git tags in your repository, which match the semantic versioning schema.

The Readme tab will show the contents of the README.md in your repository.

The Instructions tab will include instructions on how the module can be used in your Terraform code.

Submodules

Rather than creating a dedicated repository for each module, you can create a single repository and place submodules within this larger repository. Using the submodules in code is achieved in the same way as referencing submodules within Git – by using the double slash; "//" and then folder location.

module "my-module" {
  source = "api.env0.com/{organization-id}/{module-name}/{module-provider}//submodule"
  version = "1.0.0"
}

Finding My Module ID

Sometimes you may need your module ID for our terraform provider or for some API calls.

You can find it in the Module card in the Modules tab under the Registry page.

✏️ Suggested Blog Content

Terraform Modules Guide

Terraform Plan Examples

Managing Terraform Variable Hierarchy

Manage Terraform Remote State with a Remote Backend