How to share a Terraform module with the community (GitHub, Terraform Registry)

Overview

Sharing your Terraform module with the broader community is a critical step in contributing back to the open-source world and enhancing infrastructure as code practices. By making your module available, you help others benefit from your work, and simultaneously, receive valuable feedback and contributions. This guide will walk you through sharing your module on GitHub, and subsequently on the Terraform Registry, with clear examples.

Getting Started with GitHub

Before sharing your module on the Terraform Registry, it’s a prerequisite to host it on GitHub. Let’s start with the basics.

1. Create a GitHub Repository

1. Log into your GitHub account.
2. Click on the '+' icon at the top right corner and select 'New repository'.
3. Name your repository meaningfully, e.g., terraform-aws-s3-module.
4. Write a concise description of what your module does.
5. Choose whether the repository will be public or private.
6. Click 'Create repository'.

2. Structure Your Module

For Terraform modules, a standard structure is recommended. A basic structure might look something like this:

.
├── README.md
├── main.tf
├── variables.tf
└── outputs.tf

The README.md should contain clear documentation about how to use the module, what it does, its inputs, and outputs.
Other files might include examples, a license file, and any CI/CD configuration.

3. Document Your Module

Writing thorough documentation is crucial for your module’s adoption. Be clear about prerequisites, usage examples, input and output variables, and any dependencies.
A well-documented module increases user trust and ease of use.

Publishing to the Terraform Registry

With your module hosted on GitHub, you’re now ready to publish it on the Terraform Registry. This section shows the necessary steps.

1. Prepare your Module

Your module must adhere to specific criteria to be eligible for publishing on the Terraform Registry:

• Your module must be on GitHub.
• It should be Terraform 0.12 or newer.
• The repository is named following the terraform-<PROVIDER>-<NAME> pattern.
• It contains a valid README.md.
• A version tag is used to release versions following semantic versioning.

2. Release a Version

Before publishing, you need to release a version of your module. Use Git tags to create a new release following semantic versioning. For your initial release, you might tag it as v1.0.0:

git tag -a v1.0.0 -m "Initial release"
git push origin --tags

3. Publish to Terraform Registry

With a released version of your module, go to the Terraform Registry and sign in. Navigate to the ‘Publish’ section and select ‘Module’. Follow the steps to link your GitHub account and select the repository containing your module. Terraform Registry will automatically import the module and its versions based on the Git tags. After a brief review, your module will be publicly available on the Terraform Registry.

Advanced Sharing Techniques

As your module gains popularity, you might want to incorporate advanced features such as automated testing, versioning, and documentation.

Automated Testing

Incorporating automated testing ensures your module is robust and behaves as expected. Tools like Terratest can be used for writing unit tests. A sample Terratest test case might look like this:

package test

import (
    "testing"
    "github.com/gruntwork-io/terratest/modules/terraform"
)

func TestMyModule(t *testing.T) {
    terraformOptions := &terraform.Options{
        TerraformDir: "../examples/",
    }
    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)
}

Automated testing not only streamlines the development process but also builds confidence among users.

CI/CD Integration

Continuous integration and deployment can be setup using GitHub Actions or other CI/CD platforms. A CI/CD pipeline might automate testing, tag new versions, and publish documentation updates.

Conclusion

Sharing your Terraform module on GitHub and the Terraform Registry broadens its reach and impact, supporting the community and your personal or organization’s visibility. Following best practices regarding structure, documentation, versioning, and testing ensures your module provides value and enjoys wide adoption.