Get Your Code Out There: A Practical Guide to Publishing on the Terraform Registry

Want to share your Terraform modules, providers, and, in the future, functions with the world? This guide provides a clear, step-by-step process for publishing your code on the public Terraform Registry (registry.terraform.io). Let's get your Terraform projects discovered!

Why Publish to the Terraform Registry?

• Boost Discoverability: Make your modules and providers easily accessible to the Terraform community.
• Streamline Collaboration: Facilitate collaboration by providing reusable infrastructure components.
• Enhance Credibility: Showcase your expertise and contribute to the Terraform ecosystem.
• Automated Distribution: Once set up correctly, new versions of your modules and providers will become available as soon as you create a new tag on your repository.

See It in Action: A Real-World Terraform Registry Example

Check out this complete example to see the process in action:

• GitHub Source: tfstack/terraform-aws-s3-static-website (A simple static website module)
• Published Module: Terraform Registry Module: tfstack/s3-static-website/aws

This example uses a GitHub Actions workflow to automatically handle release tagging, making the publishing process effortless.

Step 1: Understand the Prerequisites for Terraform Registry Publishing

Before you begin, ensure you have the following:

• GitHub Account: A GitHub.com account is a must, as only public GitHub repositories are supported.
• Public Repository: Your code needs to reside in a public GitHub repository. Private repositories aren't compatible with the public Terraform Registry.
• Naming Convention Adherence: Use these specific naming conventions:
  • Modules: terraform-<PROVIDER>-<NAME> (e.g., terraform-aws-vpc)
  • Providers: terraform-provider-<NAME> (e.g., terraform-provider-example)
  • Functions: terraform-function-<NAME> (future support)
• Semantic Versioning Tag: Create at least one semantic version tag (e.g., v1.0.0).
• Essential Files: Include these files in your repository:
  • LICENSE
  • README.md
  • Source code (main.tf for modules, provider.go for providers, or function files)
  • versions.tf (for modules)
  • examples/ folder (highly recommended)

Step 2: Prepare Your GitHub Repository for Terraform

Follow these steps to prepare your repository:

1. Make the repository public. Double-check your repository settings to confirm it's publicly accessible.

2. Use the right naming style. Consistent naming is key for the Terraform Registry to correctly identify and categorize your work.

3. Ensure all required files are present. The Terraform Registry validates the presence of these files during the publishing process.

4. Create a release tag. Use the following commands to create and push a tag:

   git tag v1.0.0
   git push origin v1.0.0
   

   Copy

Step 3: Authorize the Terraform Registry GitHub App

The Terraform Registry needs access to your GitHub repository:

For Personal Repositories

If you've already authorized the Terraform Registry GitHub App, you're all set.

For Organization Repositories

1. Go to GitHub Applications Connections.
2. Locate "Terraform Registry".
3. Under "Organization access," click "Grant" for your organization (e.g., "tfstack").
4. Optionally, configure access for specific repositories.

Step 4: Publish Your Terraform Module or Provider

Ready to launch your project?

1. Go to the Terraform Registry Publish Page.
2. Sign in with your GitHub account.
3. Choose the type of project you're publishing: Module, Provider, or Function (when available).
4. Select your repository from the list.
5. Follow the on-screen prompts to complete the publishing process.

The Terraform Registry will automatically validate your repository's structure and release tags.

Step 5: Check and Update Your Terraform Content

After publishing:

• Modules: The URL format is https://registry.terraform.io/modules/<NAMESPACE>/<NAME>/<PROVIDER>
• Providers: The URL format is https://registry.terraform.io/providers/<NAMESPACE>/<NAME>
• Functions: (URL format coming soon)

Good to know:

• Automatic Tag Detection: The Terraform Registry automatically detects new tags within minutes of pushing them.
• No Manual Publishing (After Setup): The Registry syncs automatically after the initial setup. Subsequent updates are seamless.
• Automated Release Tags: Use GitHub Actions to automate release tag creation when you push to the main branch.

Simply commit, push, and your new version will appear live on the Terraform Registry.

Step 6: Troubleshooting Common Terraform Registry Issues

Problem	Solution
Repo not visible	Ensure the repository is public, named correctly, and has a release tag.
Authorization errors	Grant the Terraform Registry GitHub App access to your organization.
Validation errors	Ensure all required files (LICENSE, README.md, etc.) are present.
Naming errors	Verify that you're adhering to the required naming patterns precisely.
Tag format issues	Use full Semantic Versioning tags (e.g., v1.0.0). Tags like v1 are not allowed.

References for Further Publishing Information

• Terraform Registry: Publishing Modules
• Terraform Registry: Publishing Providers
• GitHub App Access Settings

Congratulations! Your Terraform module or provider is now published on the public Terraform Registry. Start sharing your infrastructure code with the world!