Private Module Registry

One of the biggest advantages of Infrastructure as Code (IaC) is the ability to create reusable, versioned components for common infrastructure patterns. Terraform supports this through providers, modules, and policies. While the public Terraform Registry enables anyone to share, Terraform Cloud offers a private registry scoped to your organization. In this guide, we’ll cover what the private registry is, why to use it, and how to publish, manage, and consume modules and providers within it.

Key Features

Terraform Cloud’s private registry helps you centrally store, version, and share approved modules and providers. With it, you can:

• Enforce standardized infrastructure patterns
• Control which providers and modules your teams can use
• Track and roll out new versions without disrupting existing users

Providers and Modules in Terraform

Terraform components fall into two categories:

• Providers: Plugins that manage infrastructure resources (e.g., AWS, Azure).
• Modules: Reusable collections of Terraform code packaged together.

Both public and private registries make it simple to discover and integrate providers and modules into your configurations.

Providers

In your private registry, you can:

• Recommend or pin specific public providers.
• Automatically sync updates from the public Terraform Registry.
• Publish custom, organization-specific providers.

Modules

Modules abstract complexity into reusable patterns. For example, the “S3 bucket” module on the public registry looks like this:

module "s3-bucket" {
  source  = "terraform-aws-modules/s3-bucket"
  version = "3.4.0"

  # custom inputs...
}

You can also publish organization-specific modules. Here’s a sample by Bryan Krausen that provisions HCP HashiCorp Vault with a transit gateway:

module "vault-aws-tgw" {
  source  = "bkrausen/vault-aws-tgw"
  version = "1.0.0"

  # insert the 7 required variables
}

Managing Modules at Scale

When you have dozens of modules with multiple versions, file shares and manual versioning become error-prone. Terraform Cloud’s private registry integrates with version control systems (VCS) to help you:

• Migrate modules into Git repositories
• Publish and version for discoverability
• Support new releases while retaining older versions

You can also enforce policy-based controls with Sentinel, ensuring that all modules and providers come from your private registry and preventing unapproved sources.

Publishing Modules

Publishing to the private registry follows public registry guidelines—except that your Git repositories can stay private. Public registry rules include:

• Host code on GitHub (public for public registry).
• Name your repo as terraform-<PROVIDER>-<NAME>.
• Include a clear repository description.
• Follow the standard module structure (variables.tf, outputs.tf, README.md, etc.).
• Tag releases with semantic versioning (e.g., v1.0.0, v3.2.5).

Consuming Modules

Once published, reference private modules and providers just as you would public ones. The only difference is the source:

module "security-group" {
  source  = "app.terraform.io/<ORG>/aws-ec2-vpc-security-group/aws"
  version = "2.1.0"
}

Terraform Cloud provides a copy/paste code block to ensure you use the correct source and version.

Versioning Modules

Terraform Cloud watches for new tags that follow MAJOR.MINOR.PATCH. To release a new version:

1. Create a Git tag (e.g., v1.2.0).
2. Push it to your repository.
3. Terraform Cloud automatically registers the new version in your private registry.

Terraform Cloud’s private registry centralizes your approved modules and providers, enforces organizational policies, and simplifies version management—empowering your teams to build and scale infrastructure consistently and securely.