agsandrew - Fotolia

A Terraform Registry tutorial to build and share modules

Before IT teams share Terraform modules through the tool's public registry, they must familiarize themselves with these prerequisites and technical steps.

Software development encourages code reuse through reusable artifacts, such as libraries, packages and modules. Most programming languages enable developers to package and publish these reusable components and make them available on a registry or feed. For example, Python has Python Package Index and PowerShell has PowerShell Gallery.

For Terraform users, the Terraform Registry enables the distribution of Terraform modules, which are reusable configurations. The Terraform Registry acts as a centralized repository for module sharing, making modules easier to discover and reuse.

The Registry is available in two variants:

  • Public Registry houses official Terraform providers -- which are services that interact with an API to expose and manage a specific resource -- and community-contributed modules.
  • Private Registry is available as part of the Terraform Cloud, and can host modules internally within an organization.

This tutorial will walk through the process to set up a module repository on GitHub, and then publish it to the public Terraform Registry.

Module prerequisites

As Terraform documentation outlines, a module must meet the following requirements to publish to the Terraform Registry:

  • Version control. The module must live as a public repository in the supported version control system.
  • Naming structure. The module's repository name should follow the format terraform-<PROVIDER>-<NAME>. The <NAME> segment can contain multiple hyphens -- for example, terraform-azurerm-resource-group.
  • Repository description. This must be populated with the simple description found on the public repository page.
  • Standard module structure. The module should follow the standard structure, allowing the registry to inspect the module, track resource consumption and perform other tasks.
  • Tags for releases. The registry relies on Git tags, which follow semantic versioning, to track module releases. At least one tag must be present.

Create a Terraform module

Let's create a GitHub repository to house our module, which enables us to create an Azure resource group. (This Terraform Registry tutorial features this sample public GitHub repository.)

Ensure the public repository meets the above prerequisites. For example, the repository name should follow the specified convention, and appear as terraform-azurerm-rg. Choose to initialize the repo with a README.gitignore file and a MIT License. Hit create repository.

sample new repository

Now clone this repository locally on your development workstation and open it in Visual Studio Code.

local repository

Next, start to put the basic module together. Populate the, and files as per the content in the referenced repository.

Now, test this module locally by referencing it in a Terraform configuration. Create a sample Terraform configuration named under any other directory than where you cloned the module. Here, we place the configuration one level up in the parent directory from the Terraform module repository.

Initialize the Terraform configuration and run the terraform plan or terraform apply command. This validates that the module works as it should.

sample Terraform config

Save all files under the Terraform module repository path, commit them and push to the remote GitHub repository. Also, add a Git tag to the repository using the version naming convention v<major>.<minor>.<patch> -- for example, v0.0.1.

save, commit, push files

Steps to publish a module

The steps in this section only need to be followed once per repository to publish a module to the public Terraform Registry.

This Terraform Registry tutorial features a simple module. To build a more complex abstraction to deploy a blueprint for an internal application, refer to Terraform's module composition documentation to structure the module properly.

First, visit the registry and log in using your GitHub account.

Terraform registry

Click Publish once logged in.

publish Terraform module

Since we followed the module prerequisites to name the GitHub repository, the module repository is discoverable. Select the repository and hit Publish Module.

Select Terraform registry

Once the module is published, we will automatically be taken to the module page in the Terraform Registry.

Terraform Registry module page

At this point, we've published a module from the GitHub repository to the public Terraform Registry. Next, we can use the module in Terraform configurations.

Reference a published module

Open the old Terraform configuration file -- the file we authored initially. The instructions are available on the module's landing page on the Terraform Registry as well.

Terraform provision instructions

Modify the source to use the public Terraform Registry module and specify the version to use.

TF registry source and version

Run the terraform init command again, since the source reference has changed. This downloads the referenced module.

Run terraform init command

To finish this Terraform Registry tutorial, run either the terraform plan or terraform apply command to confirm that referencing a public module in the Terraform configuration works.

confirm public module reference

Dig Deeper on Systems automation and orchestration

Software Quality
App Architecture
Cloud Computing
Data Center