Skip to main content
In this lesson we’ll cover the HCP Terraform Private Registry: what it is, why it exists, and how teams use it to share versioned, organization-specific Terraform modules and providers. Why modules matter
  • Teams create reusable Terraform modules to standardize common infrastructure patterns (TLS certificates, load balancers, message queues, Kubernetes clusters, databases).
  • Modules let application teams consume tested building blocks instead of reimplementing infrastructure logic, reducing risk and accelerating delivery.
  • Modules also enable consistency across teams while allowing environment-specific inputs.
For example, a marketing app team can consume a TLS certificate, load balancer, and Kubernetes cluster module without reimplementing them.
The image is a diagram outlining "Modules for Repeatability" within a "Marketing Application," listing modules like TLS Certificate, Load Balancer, Message Queuing, Kubernetes Cluster, and Database Cluster.
Another team building a GenAI service can reuse the same modules with different inputs — demonstrating the “write once, use everywhere” value of modules.
The image illustrates a modular framework for repeatability, depicting a central module block that provides infrastructure components like TLS Certificate, Load Balancer, and Kubernetes Cluster, connected to both a Marketing Application and a GenAI Service.
Versioning matters
  • Modules evolve (for example: 5.10.0 → 5.11.0 → 5.12.0). With many consumers, semantic versioning is essential so teams can pin versions and upgrade on their own schedule.
  • The public Terraform Registry offers browsable versions and docs, but it is public. For internal, security-sensitive, or compliance-driven modules you need a private, organization-scoped solution.
What the HCP Terraform Private Registry provides
  • Private sharing of modules and providers — visible only to members of your HCP Terraform organization.
  • Semantic versioning and version constraints equivalent to the public registry.
  • A way to enforce standards by publishing approved, tested, and secure modules for team consumption.
Below is a quick comparison (for quick scanning) followed by an illustrative image.
AreaPublic RegistryHCP Terraform Private Registry
Hosting / visibilityPublicly visible to everyoneScoped to your HCP Terraform organization (requires credentials)
Who can publishAny community memberOnly approved organization members via connected VCS repos
Typical contentCommunity-maintained modulesOrganization-private modules + curated public modules you approve
Source address formatnamespace/name/providerapp.terraform.io/<ORG>/<MODULE_NAME>/<PROVIDER>
The image is a comparison table between a public and private registry, highlighting differences in hosting, visibility, content publishing, and source format within the context of Terraform.
Key distinctions explained
  • Hosting/visibility: Public registry = global visibility; Private registry = organization-scoped visibility with access control.
  • Publishing: Public = open publishing; Private = controlled publishing from connected VCS repositories by authorized maintainers.
  • Content: Private registry aggregates your internal modules and any curated public modules you choose to expose for team discovery.
  • Source format: Private modules include the hostname prefix so Terraform queries your private registry: app.terraform.io/<ORG>/<MODULE_NAME>/<PROVIDER>.
What lives inside a private registry? There are two main categories:
  1. Private modules and providers — authored and maintained in your organization’s connected VCS repositories and surfaced only to organization members.
  2. Curated public modules — pointers or mirrored entries for vetted public registry modules, so teams can find both internal and approved external modules in one place.
The image explains what is inside a private registry, featuring "Private Modules & Providers" and "Curated Public Modules" with brief definitions for each.
How modules get into the private registry Publishing to the Private Registry is a simple three-step flow:
  1. Develop and commit the module code to a VCS repository (GitHub, GitLab, Bitbucket, Azure DevOps, etc.) using the standard Terraform module layout (README, inputs, outputs, examples).
  2. Connect that repository to your HCP Terraform organization and publish it to the Private Registry. HCP Terraform imports the module metadata and generates browsable docs.
  3. Create new module versions by pushing semantic Git tags (for example, 1.0.0, 1.1.0); the registry automatically creates version entries from those tags.
Once published, organization members can browse module docs, copy usage snippets, and reference the modules in Terraform configurations.
The image outlines three steps for publishing private modules in Terraform: storing module code in a VCS repo, publishing to HCP Terraform, and enabling organization members to use the modules.
Referencing a private module in your configuration Private registry module source addresses include the registry hostname so Terraform knows to query your organization’s registry instead of the public one. Use the following source format: app.terraform.io/<ORG>/<MODULE_NAME>/<PROVIDER> Example HCL module block: 
module "webapp" {
  source  = "app.terraform.io/krausen-hcp/webapp/gcp"
  name    = var.name
  prefix  = var.prefix
  version = "1.0.0"
}
  • app.terraform.io — hostname indicating the private registry
  • krausen-hcp — organization name
  • webapp — module name
  • gcp — provider
  • version — pins the module to a specific released version
Everything else works the same as public modules: pass variables, Terraform downloads the module source, and the module is included in plan/apply. If you see a source beginning with app.terraform.io, it’s a private registry module.
The private registry auto-creates module versions when you push semantic Git tags (for example, 1.0.0). Ensure your repository follows the standard Terraform module layout so the registry can detect and import it correctly.
Key takeaways
  • The HCP Terraform Private Registry lets you share modules and providers privately within your organization, maintaining access control and governance.
  • You can curate approved public modules and surface them next to your private modules to create a single source of truth for teams.
  • Private modules are published from connected VCS repositories and are versioned automatically via semantic Git tags.
  • Private module source addresses include the hostname prefix app.terraform.io so Terraform queries your private registry.
  • Publishing to the Private Registry requires the “Manage Private Registry” permission — limit this to trusted maintainers.
Publishing modules to the private registry requires the Manage Private Registry permission. Ensure only trusted maintainers have this permission to prevent unauthorized module publication.
That wraps up this lesson on the HCP Terraform Private Registry. Keep these concepts in mind when designing a module publishing workflow for your organization or preparing for certification exams. Links and references

Watch Video