Module Registry

env0 Module Registry

The env0 Module Registry is a private registry for Terraform modules, allowing you to privately share and reuse Terraform modules within your organization.

Your organization’s module registry is available through the Organization Menu (in the bottom-left of the screen).

Adding a module to the registry

In order to add a module to your registry, enter the Module Registry screen and click on “Create New Module” in the top right. Only organization administrators are permitted to create new modules.

In the first step, you must enter the general details of your module.

• A Name for your module - This can be any string of your choice.
• The Provider the module belongs to - This can also 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, and is a useful way of summarizing what the module does and when it should be used.

In the second step, 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, and after you’ve authorized env0 to access your repositories, select a repository from the dropdown 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.

🚧

Version Prefixing

Terraform allows using version prefixing, i.e. adding a v before the version. However, when using the Terraform CLI, when running terraform init the v is omitted and the tag that is looked for doesn't contain it. Therefore using a module with a prefixed version won't work within env0.

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 locally

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 (or in a CI environment), you will need to supply the authentication details to Terraform.

These must be supplied in a file called terraform.rc (for windows) or ~/.terraformrc (other systems).

To authenticate with the registry, use an API Key (obtained from your organization’s Settings page). The API key must be entered into the terraform rc file like this -

credentials "api.env0.com" {
  # A valid Basic authentication header value, using your env0 API Key ID and Secret
  token = "Basic base64-encoded(api-key-id:api-key-secret)"
}

Here's an example of how to generate your token (in a Mac terminal)

export ENV0_API_KEY={replace with your key}
export ENV0_API_SECRET={replace with your secret}
echo -n $ENV0_API_KEY:$ENV0_API_SECRET | base64 

Your ~/.terraformrc should look something like this

> cat ~/.terraformrc
credentials "api.env0.com" {
  # A valid Basic authentication header value, using your env0 API Key ID and Secret
  token = "Basic dzltWermZ2...rjdeWERr=="
}

These instructions are also available in the Instructions tab of the module page.

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

The Module By clicking on a module from the Modules List, you will get to the Module page.

On this page you can see the details of your Module.

The Versions dropdown 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"
}