Terraform Registry Guide: Tips, Examples and Best Practices

The Terraform registry is an essential asset for every Terraform user. In this blog, I’ll provide a practical guide for how it can be best used and explore ways you can leverage it to streamline and standardize cloud infrastructure provisioning.

What is Terraform Registry?

The Terraform registry is an official repository for Terraform modules and providers hosted by HashiCorp. 

The registry serves as a central hub for individuals and organizations looking to publish, discover, and use Terraform modules and providers to automate the setup and management of cloud infrastructure. 

Modules in the Terraform registry function similarly to libraries in a programming language, allowing reuse instead of requiring you to build your own from scratch. 

Providers are basically plugins for Terraform to communicate with cloud providers like AWS, Azure, Google Cloud, etc., to provision or manage your infrastructure.

The benefits of using the Terraform registry include:

1. Efficiency: You can utilize the registry to save time by using pre-existing modules instead of starting from scratch. 
   For example, you can import a pre-built Terraform EKS module from the registry, saving the time and effort of writing the EKS config.

2. Simplicity: Using the registry abstracts complex resource details simplifies your configuration.
   For instance, deploying a VPC manually requires configuring numerous components, including subnets, gateways, etc. However, utilizing a VPC module smooths the experience by abstracting the intricate configurations.

3. Peace of mind: The Terraform registry classifies modules and providers with badges (official, partner, community) to denote their source and level of verification. Moreover, the registry holds information about downloads, as an indication of usage and trustworthiness. 

Having this information available will help you identify popular, verified, and community-vetted assets and help improve your IaC quality, reliability, and security. 

Terraform Public vs. TFC Private Registry

The official Terraform registry is public, and should not be confused with the private self-hosted registry offered by TFC, env0, and other IaC management platforms, or OSS modules like Citizen, Terrareg, etc.

The use cases for using a private registry include:

• Customization: Organizations can create and manage modules that are tailored to their internal use, specific infrastructure requirements and policies, etc.
• Security: Security and compliance requirements can necessitate some organizations to self-host their registry or/and some of its modules.
• Centralized Governance: A private registry can be used for management and versioning of modules specific to the organization, to support internal guidelines and processes.
  

Example: Using Terraform AWS S3 Module

To show how the Terraform registry works (and how you should be working with it), here is a hands-on example of how we can provision an S3 bucket with Server Side Encryption (SSE) and versioning - all enabled through the use of an S3 module in the Terraform Registry.

Generally speaking, there are four steps you should take to use providers and modules from the registry to spin up an infrastructure:

1. Search and Discover

Since we want to import Terraform S3 code, our initial step would be to find an AWS S3 module with the necessary parameters (SSE and versioning). First, click on Browse Modules to find a range of different modules in the registry.

In our case, we filter the results to the AWS provider, since we want to provision an AWS S3 bucket.

2. Review and Select

Once we have found a module that meets our requirements, it is important to review its documentation, usage examples, and version information. 

In our case, we can see that the module is published by terraform-aws-modules, which is supported by the HashiCorp community. To further examine our parameters, we need to check the Inputs section.

Scroll down to check whether the module allows us to define the SSE and versioning input variables so that we can add these parameters to our S3 module block configuration. We see that it allows us to define these parameters.

3. Import Module into Terraform Code

Use the module in your Terraform configuration by referencing it in your .tf files. Specify the source of the module (its URL in the Terraform Registry). The basic syntax looks like this:

module "module_name" {
  source  = "namespace/module/provider"
  version = "version"
  # Additional required variables
}

In our case, we have defined the S3 bucket module in our main.tf file.

module "s3-bucket" {
  source  = "terraform-aws-modules/s3-bucket/aws"
  version = "4.1.0"
  bucket = "env0"
  versioning = {
    enabled = true
  }
  server_side_encryption_configuration = {
    rule = {
      apply_server_side_encryption_by_default = {
        sse_algorithm = "AES256"
      }
    }
  }
}

4. Run Terraform workflow

Run [.code]terraform init[.code] to initialize the Terraform project, which will download and install the specified S3 module and AWS provider it depends on. 

Run the [.code]terraform plan[.code] command to review the changes Terraform will make to your infrastructure based on the S3 module we included. 

Then, use [.code]terraform apply[.code] to spin up the S3 bucket, confirming the changes with a ‘yes’. 

After running [.code]terraform apply[.code], we have successfully provisioned our S3 bucket (env0).

Note: Understanding Verified Modules
----
‍By default, only verified modules are shown in search results.
HashiCorp reviews the modules, ensuring they meet their standards for quality and reliability.
‍
Three major benefits of verified modules:

- Reviewed by HashiCorp: Closely examined by HashiCorp to ensure they follow best practices in code quality, documentation, and module design. The verified badge appears next to modules that are published by a verified source, like HashiCorp.
- Actively Maintained: Contributors typically actively maintain verified modules, ensuring that they stay up to date with the latest Terraform versions and features.
- Trust and Reliability: Choosing a verified module means you're using a trusted component that is more likely to be reliable and secure for your infrastructure.

Example: Publishing Modules to the Terraform Public Registry

The next example I want to share will focus on adding your own module to the public registry.
To do that, imagine you've written Terraform code for an S3 bucket and you want to transform this code into a module, to enhance its reusability inside and outside your organization.

First and foremost, create a repository in your public Github account with an appropriate naming convention. The naming convention for repositories should be [.code]terraform-<provider-name>-<module-name>[.code]. 

Therefore, with respect to the naming convention, the given name of the module is kept as [.code]terraform-aws-s3-sse-versioning[.code].

After pushing the source code, the next important step is to tag our repository. To do that, head on to the Releases section and create a tag. We have created the tag 1.0.0. Select Publish Release after creating the tag.

To begin publishing your modules, navigate to the Terraform Registry and click on Publish Modules under the Publish dropdown. You will then be prompted to Sign In with GitHub. This step allows the Terraform registry to access and identify the repository where your module source code is located.

After authorizing your own registry with Github, (selecting Publish dropdown > Module), you’ll be prompted to select the repository for hosting the module. Choose the repo and select Publish Module.

Bingo! Within a few minutes, we can see that our module has been successfully published, which means you can pick up your existing terraform code and package it into a module.

env0 Private Registry

env0 offers two types of registries for your organization: Provider Registry and Module Registry.

Provider Registry

env0 Provider Registry is a feature that allows you to privately share and reuse Terraform providers within your organization. 

You can easily switch between different versions of the code with minimal changes. Moreover, within env0, authentication is seamlessly managed for you, requiring no extra steps or configurations.

It also enforces the use of RBAC policies to control access to the Provider Registry. For instance, users with “View Providers” have the privilege to only view the providers. As an administrator, you always have “Create and Edit” access.

Check out the Provider registry for more detailed information.

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.

Creating and using a module with the env0 module registry is seamless.

1. In your env0 account, go to [.code]Registry > Modules section > Create a Module[.code].
2. Give a suitable name for your module and the provider name.

3. I’m leaving the tag prefix (env0 auto-detected repo tag, in our case) and module folder (as the module resides in the root folder) empty.

4. The private module has now been created, and the team in your organization can import the module using the appropriate format.

env0 has also rolled out its new CI Testing feature. This feature was specifically designed by env0 to incorporate the OpenTofu testing capabilities into their platform.

The OpenTofu testing feature ([.code]tofu test[.code]), validates your OpenTofu configuration (including modules) by creating real infrastructure and checking if the conditions (or assertions) for that provisioned infrastructure are met.

Tests suite is defined in *.tftest.hcl files and the run blocks should be where the test conditions are defined.

Each test run validates the following:

• All assertions pass
• None of the checks are failing
• The tofu plan/apply has finished successfully

For more information on how this feature works, check out the [.code]tofu test[.code] command.

Coming back to CI testing, this feature effortlessly integrates OpenTofu testing capabilities into your private module registry, acting as a health monitor for your modules and initiating tests with every change. Information is conveniently available in env0 and your VCS for a clear overview of your module status. This facilitates the mitigation of issues early on, improving user experience.

Frequently Asked Questions/FAQs

Q. Is the Terraform registry free?

Yes, Terraform's public registry is freely accessible to the general public, offering a wide range of providers and modules. 

Q. Is the Terraform registry open-sourced?‍

No. Terraform Registry is the property of HashiCorp. In 2023, following the license change of HashiCorp’s product, the company also updated the registry’s terms of service (TOS) for the Terraform Registry to limit its community usage, stating that: “You may download or copy the Content (and other items displayed on the Services for download) for personal non-commercial use only, provided that you maintain all copyright and other notices contained in such content.”‍

Q.  What registry is used by OpenTofu? 

OpenTofu, Linux-foundation’s backed open-source Terraform alternative,  maintains its own registry, offering access to a comprehensive set of providers and modules, including all the providers and modules currently available in the Terraform registry. 

Q. How do I publish a module to a private registry?

As discussed in this blog, publishing a module to a private registry is similar to publishing a module to the public registry. The process involves writing your own module, pushing it to your VCS (Version Control System) with semantic version tags, and then integrating your VCS with the private registry (e.g., Terraform Cloud, env0, etc.) to select and publish the module.

Q. Can I use multiple providers in Terraform, and where are providers stored?

Yes, you can use multiple providers in Terraform for provisioning infrastructure in different cloud environments. After you define the provider within the terraform block and run terraform init, Terraform downloads the respective provider plugin and stores it in the .terraform/providers folder in your local environment.

Q. What is the difference between Terraform providers and modules?

Providers in Terraform are plugins that interface with the API of a service provider (such as AWS, Google Cloud Platform, Azure, etc.) to manage resources. For example, the AWS provider can manage resources like virtual machines, databases, networks, etc., on AWS.

Modules, on the other hand,  can be used to create reusable templates for common infrastructure setups, like setting up a VPC network architecture on AWS.