Skip to main content
In this lesson we continue our HCP Terraform journey and cover the HCP Terraform Private Registry: what it is, why it matters, and how to publish and consume private modules and providers within your organization.

​
Why modules matter

Modules let your organization capture repeatable infrastructure patterns as reusable, tested components. Instead of reimplementing common infrastructure for every project, you publish modules for things like TLS certificates, load balancers, message queues, Kubernetes clusters, and database clusters. Teams then compose these building blocks by referencing module blocks and supplying only the application-specific inputs. This model reduces duplication, improves security and compliance by centralizing approved patterns, and accelerates delivery: write the module once, reuse it everywhere.
A purple-themed diagram titled "Modules for Repeatability" showing three columns: Marketing Application on the left, shared Modules in the center (TLS Certificate, Load Balancer, Message Queuing, Kubernetes Cluster, Database Cluster), and GenAI Service on the right. Arrows show module blocks from each application connecting to the central shared modules.

​
Versioning modules

Modules change over time. A module might start at v5.10.0, gain features in v5.11.0 and v5.12.0, and later require breaking updates in v5.14.0 due to provider API changes. When many teams consume the same module, semantic versioning and the ability to pin module versions are essential to avoid unexpected breakages. The public Terraform Registry provides browsable versions, version constraints, and docs for community modules. For company-specific modules that capture internal patterns, security controls, and compliance requirements, you typically want to keep them private.
An infographic titled "Module Versions" showing an Application Module with a vertical list of versions (v5.10.0 to v5.14.0) and arrows pointing to colored diagram blocks labeled "Baseline Configuration," "Added New Functionality," and "Provider API Changed." The slide has a purple background with a logo in the top-right.

​
What the private registry provides

The HCP Terraform Private Registry lets you host a private catalog of modules and providers that only members of your HCP Terraform organization can see and consume. Key benefits include:
  • Share modules privately: Published modules and providers are visible only to organization members.
  • Version controlled: Supports semantic versioning and version constraints so teams can pin versions and upgrade on their own schedule.
  • Enforce standardization: Publish vetted, tested modules to ensure teams consume secure and compliant building blocks.
A purple-themed infographic titled "Private Registry" showing three panels. The panels are labeled "Share Modules Privately," "Version Controlled," and "Enforce Standardization," each with a matching icon and brief explanatory text.

​
Public vs Private Registry — side-by-side

The private registry intentionally mirrors the public registry experience (browsable, searchable, versioned) while restricting publishing control and audience. Use the table below to compare the two.
A presentation slide titled "Wait...This Looks Like the Public Registry" showing a purple comparison table that contrasts Public Registry vs Private Registry details for Terraform (hosted locations, visibility, who publishes content, and source formats).

​
What lives inside a private registry

Two primary categories appear in a private registry:
  • Private modules and providers: Published from your organization’s connected VCS repositories and accessible only to members of the organization. These are your internal infrastructure patterns and policies.
  • Curated public modules: Pointers to vetted modules and providers from the public Terraform Registry. These are not copies; they are links that let teams view approved public modules alongside your private catalog, creating a single source of truth.
An infographic titled "What's Inside the Private Registry?" showing two labeled sections: a purple puzzle-piece icon for "Private Modules & Providers" and a cloud icon for "Curated Public Modules." Each section has short explanatory text about module sources, layered over a stylized cityscape background.

​
How modules get into the private registry

Publishing to the private registry follows a simple three-step workflow:
  1. Keep your module code in a connected VCS repository (GitHub, GitLab, Bitbucket, Azure DevOps, etc.). Follow Terraform’s module structure and best practices.
  2. Connect that repository to your HCP Terraform private registry. HCP Terraform imports the module metadata and generates docs.
  3. Create new versions by pushing git tags that follow semantic versioning (for example v1.0.0). The registry automatically creates versioned releases that organization members can browse and consume.
An infographic titled "Publishing Private Modules" showing a three-step workflow: 01 VCS repo, 02 HCP Terraform (private registry), and 03 org members. It visually explains moving module code from a version-control repo into a private Terraform registry so organization members can browse and use it.

​
Referencing a private module in configuration

Private modules use a registry source address that instructs Terraform to fetch them from your private registry instead of the public registry. The typical format is:
Example module block that consumes a private module:
Because the source begins with app.terraform.io, Terraform directs the request to the private registry in your HCP Terraform organization. Everything else behaves the same as with public registry modules: Terraform downloads the module, variables are passed in, and the module is included in the plan and apply operations.
When you push a Git tag that follows semantic versioning (for example v1.0.0), the private registry automatically creates a new version. Teams can pin to specific versions or use version constraints just like with the public registry.

​
Key takeaways

  • The HCP Terraform Private Registry lets you share modules and providers privately within your organization.
  • You can surface vetted public modules alongside your private modules to create a single, curated catalog for teams.
  • Private modules are published from connected VCS repositories and are automatically versioned via semantic git tags.
  • The source format begins with app.terraform.io, followed by your organization, module, and provider — this tells Terraform to use your private registry.
  • Viewing the registry is available to organization members; publishing requires the Manage Private Registry permission.
For the exam, remember the private registry source format:
That wraps up this lesson on the HCP Terraform private registry.

Watch Video