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.
Now clone this repository locally on your development workstation and open it in Visual Studio Code.
Next, start to put the basic module together. Populate the main.tf, variables.tf and outputs.tf 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 tf_azure_rg.tf 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.
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.
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.
Click Publish once logged in.
Since we followed the module prerequisites to name the GitHub repository, the module repository is discoverable. Select the repository and hit Publish Module.
Once the module is published, we will automatically be taken to the module page in the Terraform Registry.
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 tf_azure_rg.tf file we authored initially. The instructions are available on the module's landing page on the Terraform Registry as well.
Modify the source to use the public Terraform Registry module and specify the version to use.
Run the terraform init command again, since the source reference has changed. This downloads the referenced module.
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.
