Where private modules go when you leave the HCP Terraform registry
If your private modules and providers live in the HCP Terraform registry, Terrakube's built-in private registry is the self-hosted home for them, and community providers come from the public OpenTofu Registry. Terrakube provides a private registry for Terraform modules and providers, so the internal code your teams reference stays inside infrastructure you run. Public providers that your configurations already use can continue to be pulled from the public registry, so the decision you need to make is about private content, not about every dependency.
The answer has two parts. The first is the private registry in Terrakube, which holds your own modules and any private providers and sits alongside its organizations, workspaces and VCS connections. The second is the public OpenTofu Registry, which lists more than 3,900 providers and 23,600 modules according to the OpenTofu website and is searchable at search.opentofu.org. The CLI that resolves these sources can be OpenTofu or Terraform, because Terrakube supports both. Terrakube is licensed under Apache 2.0, so the platform that hosts your private registry carries no source-available restrictions on how you run it.
Before you move anything, inventory every module and provider source reference in your configurations and confirm with Terrakube's documentation how private registry sources are written, authenticated and versioned in your setup. Check which teams and groups need read access, because Terrakube assigns permissions on modules by group. Plan a test in a non-production organization first, so you can see how version constraints resolve against the new source before you change production configurations.
Which open-source option covers each registry capability
This table maps each private registry capability you rely on in HCP Terraform to Terrakube's private registry, the public OpenTofu Registry, or a gap you will need to fill. Read the coverage notes first, since they flag where a capability is missing or needs confirmation against the Terrakube documentation for your version.
| Capability | Terrakube private registry | OpenTofu Registry and tooling | Coverage notes |
|---|---|---|---|
| Private module hosting | Provides a private registry for Terraform modules, per the Terrakube README | Not applicable, the OpenTofu Registry is public | Covered in principle. Confirm module naming and versioning conventions in the Terrakube docs for your release. |
| Private provider hosting | Provides a private registry for providers, per the Terrakube README | Not applicable for private content | Partial. Confirm provider packaging, signing and publishing steps for your version before you commit to an internal provider. |
| Public community providers | Consumed through the normal registry hosts in configurations | OpenTofu Registry lists more than 3,900 providers and 23,600 modules, searchable at search.opentofu.org | Covered. The public registry is reachable from self-hosted runs only if your network policy allows outbound access. |
| Private content in a public registry | Not applicable | Not supported. The OpenTofu Registry is public and cannot hold private modules or providers | Gap by design. Keep proprietary modules in Terrakube or in a private source such as a VCS repository. |
| Version publishing | Publishing flow is part of the registry feature set, exact steps to confirm in Terrakube docs | Not applicable for private content | Confirm how versions are tagged, published and deprecated in your Terrakube release before migrating. |
| Search across private modules | Confirm whether the Terrakube UI offers search and filtering comparable to HCP Terraform | OpenTofu search covers only the public registry | Unknown until tested. Verify on a staging instance with your own module set. |
| Group-based access by module | Permissions on modules are assigned by group, per the Terrakube README | Not applicable | Covered in principle. Map existing HCP Terraform teams to Terrakube groups before cutover. |
| VCS-linked module sources | Terrakube integrates with GitHub, GitLab, Bitbucket and Azure DevOps to retrieve code, per its README | Not applicable | Covered for retrieving code. Confirm how module releases are linked to VCS tags in your version. |
Terrakube, the OpenTofu Registry and direct source options compared
HCP Terraform's private registry does three jobs: it hosts private modules and providers, it serves public content, and it gives teams version discovery. Self-hosting splits those jobs across different tools, so each option below covers a different slice. None of them is a drop-in copy of the HCP Terraform registry, and the checks on each card show what your team will still need to run.
Terrakube's built-in private registry
Terrakube includes a private registry for Terraform modules and providers, so private code can stay inside the same platform that runs your plans and holds your state. Access follows Terrakube's group permissions on modules, which lets you split teams by module ownership. Check which provider types and module versioning behaviors your configurations depend on, and test publishing and version constraints against a copy of your real modules before you move production. You still operate the database, the Terrakube installation and its upgrades.
Public OpenTofu Registry for community content
The OpenTofu Registry, searchable at search.opentofu.org, is the right source for public providers and community modules that do not contain your code. It is public content, so private modules, internal naming or account-specific values must never be published there. Pin versions in your configurations and review what each community module does before you rely on it, since the registry lists content from many authors. Your team still owns the review and the decision to adopt each dependency.
Git sources for teams without a registry
Modules can be referenced directly from a Git repository, pinned to a tag or commit. This removes a registry service entirely, which suits small teams or a few stable modules. The trade-off is that Git sources do not offer version discovery, so consumers must know which tags exist and read them from the repository. Confirm that your Git host is reachable from every runner and that tag policies prevent force-pushed releases.
Object store sources for artifact control
Module archives can be published to an S3-compatible or other object store and referenced from configurations, which keeps artifacts inside your own storage and lets you apply bucket policies, retention and versioning. The configuration must be written against the source format that OpenTofu supports, and you must generate an index or version naming scheme yourself. Your team operates the publishing pipeline, access policies and the checks that stop an unreviewed archive from reaching production.
How module sources and version constraints change in your configurations
A module block that pulls from the HCP Terraform private registry usually names app.terraform.io in its source address, in the form organization, module name and provider. Moving to Terrakube means changing the hostname so it points at your self-hosted Terrakube API hostname, and confirming the organization and module path that your instance uses. Do not assume the source syntax from HCP Terraform examples carries over unchanged. Check the exact source format for the Terrakube private registry in the Terrakube documentation before you edit any module block. The version argument keeps its meaning. A constraint such as ~> 5.0 still selects matching versions, but only versions that Terrakube actually holds can satisfy it.
The registry host in every source address must match the self-hosted hostname exactly. A mismatch usually fails during init with an error that looks like a missing module, which slows troubleshooting. Authentication must also match across the team. Log in to the Terrakube API hostname with terraform login, and confirm the login command for the CLI you run in OpenTofu. Developer machines and CI runners need the same host configuration and credential handling. The cloud block requires Terraform v1.1 or later, so check the CLI version on every runner before you switch. Pipelines that still point at the old host should fail visibly, not quietly pull stale modules.
Test with a small change before you migrate the rest. Pick one low-risk module, publish it to Terrakube, update its source and version lines, then run init and plan in a non-production workspace. Make one small, reversible change and apply it to confirm that the whole path works. Keep the previous source and version lines in version control so you can revert in a single commit. Review the Terrakube CLI-driven workflow documentation for the current registry and login steps, and record what you confirmed so the rest of the team follows the same pattern.
What changes depending on whether you host modules, providers or both
If your configurations consume only community providers and public modules, the registry change is mostly about where lookups resolve. The OpenTofu Registry lists more than 3,900 providers and 23,600 modules, searchable at search.opentofu.org, so most of the providers your configurations already declare are expected to be there. Nothing private needs to be hosted, and the module and provider blocks in your code can usually stay as they are once the CLI is switched to OpenTofu.
- Provider sources: Confirm that each entry in
required_providersresolves in the OpenTofu Registry, since the source address is what the CLI uses to find it. - Module sources: Public modules referenced from the public registry keep their addresses, but pinned versions should be checked against what the public index actually publishes.
- Lock files: Regenerate
.terraform.lock.hclunder OpenTofu and review the provider hashes it records. - Egress: Your runners or Terrakube workers need outbound access to the OpenTofu Registry and provider download hosts, which your network team should confirm.
- Community provider risk: Community providers are maintained by third parties, so review their release cadence and sources before you depend on them.
Confirm that your egress rules and lock files work in a test workspace before you change the production CLI version.
If your team writes its own modules but consumes public providers, the main move is the private module registry. Terrakube provides a private registry for Terraform modules and providers, so module versions previously published to the HCP Terraform registry can be re-published there under the same organization model. Your provider usage stays on the public OpenTofu Registry, which means only one part of the registry estate changes.
- Module publishing: Re-publish each module with its version tags and confirm that the version numbers match what your configurations pin.
- Source addresses: Module source strings that point at the HCP Terraform registry must be rewritten to the Terrakube hostname, and this is a configuration change that goes through review.
- Version constraints: Check that
versionarguments still resolve after re-publishing, because a missing or renumbered tag will failinit. - Access control: Map module access to Terrakube groups so that only the teams that own a module can publish it.
- VCS linkage: Decide whether module releases come from tags in your Git host, and confirm that Terrakube's VCS integration handles those tags.
Run tofu init against a sample configuration that uses every private module before you rewrite sources across the estate.
If your team publishes its own providers, the registry change has the most moving parts. Terrakube's private registry covers Terraform modules and providers, but a provider needs more than an upload: it has to be built for each target platform, signed, and served with the metadata the CLI expects. The public OpenTofu Registry is not a place to publish private providers, so they stay in your own infrastructure.
- Build and signing: Confirm the release process produces signed artifacts for every platform you support, and that signing keys are held in a system you control.
- Registry protocol support: Verify with the Terrakube documentation that the private registry serves providers in the form OpenTofu expects, and test a full
initon each operating system your teams use. - Mirror needs: For air-gapped or restricted networks, decide whether you need a local provider mirror so that
initdoes not depend on outbound access. - Key trust: Decide how signing public keys are distributed to engineers and CI runners, and how they are rotated.
- Upgrades: Plan how a provider version change reaches every workspace without breaking existing state.
Confirm the signing and mirror design with your security team before the first provider is published, since changing it later affects every consumer.
Moving private modules and providers without breaking existing workspaces
This sequence moves private modules and providers from HCP Terraform into Terrakube's registry while every workspace is checked for unexpected changes before any cutover. It ends with a verified configuration that can be rolled back if a plan shows drift.
Inventory every module and provider reference
Platform engineers list every module source and provider block used by each HCP Terraform workspace, including the version constraints and the workspace that calls each one. Search the configuration repositories for module blocks, required_providers entries and any terraform_remote_state references, since those need separate handling. The output is a spreadsheet or file with one row per module or provider, its current source address, its constraint and its owning team. Done means every workspace in scope appears in the list and nothing is left to discover during cutover.
Export module source from version control
Module versions in a private registry point to source code, so the code already lives in your version control system. Engineers confirm the repository, the tag or commit behind each published version and any submodule or subdirectory layout the module depends on. Where a module was uploaded without a tag, the team picks the commit that matches the deployed behavior and records it. Done means each module version in the inventory maps to a specific commit that a reviewer has checked against the registry copy.
Publish each version to Terrakube
Platform engineers create the module and provider entries in Terrakube's private registry and upload each version from the tagged source. Because versions are tied to source code, this is usually a re-tag and upload rather than a copy of registry data, though the exact upload path and provider signing requirements should be confirmed against the Terrakube documentation before the work starts. Done means every version from the inventory appears in Terrakube with the same version number and a test workspace can resolve it with OpenTofu init.
Update source and version arguments in a branch
Engineers change each module source and version argument to the Terrakube registry address in a feature branch, and update required_providers source entries for private providers. Constraints stay the same unless a review says otherwise, so behavior does not shift during the change. Where a configuration reads outputs through terraform_remote_state, the team follows the separate migration guidance before editing those files. Done means the branch contains one reviewed commit per workspace or per shared module and the diff shows only source address and version changes.
Run init and plan against each workspace
For each workspace, an engineer runs OpenTofu init and plan against the branch using a state copy or a read-only test backend, so no live state is changed. The team reviews every planned change and expects no creates, updates or deletes caused by the registry switch alone. Any unexpected diff is traced to a module version, provider version or variable difference before the workspace moves on. Done means each workspace has a plan record, signed off by its owner, that shows no changes beyond what the code change intended.
Test with a small change before cutover
The OpenTofu migration guide describes its process as designed to be safe and reversible and recommends testing with a small, low-risk change before wider use. Engineers apply one harmless change through the new Terrakube-backed workspace, confirm the run history, state version and registry resolution, and then revert it. Done means one controlled apply has completed end to end and the team has confirmed that rollback to the HCP Terraform configuration is still possible.
Cut over and keep the old source available
The team merges the verified branch, switches each workspace to the Terrakube backend or cloud block, and records the cutover time and owner. The original HCP Terraform private registry entries and version tags stay in place until every consumer has been confirmed on the new addresses. Done means all workspaces plan cleanly from Terrakube, a rollback procedure is written down, and no configuration still references the old registry address.
Compatibility risks when you switch the CLI to OpenTofu
OpenTofu aims for feature parity with Terraform, but it does not guarantee compatibility with future Terraform releases. The OpenTofu FAQ says the community decides which Terraform features OpenTofu adopts, so a module that works today may behave differently after either tool ships its next release. Once you switch the CLI, pin the OpenTofu version in your configuration and in your Terrakube or CI images, and upgrade only through a tested change. Do the same for providers and modules, using version constraints in the required_providers block and the version argument on module calls, so a registry update cannot change behavior without a review.
Some divergences are already visible in the feature sets. OpenTofu added early evaluation of variables and locals in v1.8 and provider for_each in v1.9. Code that relies on these features will not run on Terraform, and a module written against OpenTofu may fail under Terraform. Check every module that will be published to your private registry for required_version settings, and decide whether your organization standardizes on OpenTofu for all workspaces or keeps a mixed fleet. A mixed fleet doubles the test matrix, so most teams should choose one CLI. OpenTofu v1.13.1 was released on October 1, 2026, so confirm which version your Terrakube workers run before you pin it.
Build a test plan that covers the registry path, not only the plan output. For each module, run tofu init against the private registry and the public OpenTofu Registry sources you depend on, then run tofu plan on a sandbox workspace and compare the output with the current Terraform plan. Include a check that resolves every version constraint to the expected version, and a check that providers from the public registry install without changes to lock files. Record the results as your evidence for each pinned version. Confirm with your platform team which OpenTofu release you will standardize on, and repeat this test whenever you raise the pin.
Questions teams ask before replacing the HCP Terraform private registry
Can our team replace the HCP Terraform private registry ourselves?
Yes, if your team already runs containers or Kubernetes and has someone comfortable with Terraform module versioning, but the work is more than a single install. The registry sits on Terrakube, which documents installation with a Helm chart or Docker Compose, so the platform itself is a known deployment. The harder parts are the decisions around it: which modules and providers move, how versions are published, which groups can publish, and how module sources in every configuration are rewritten. Teams without a platform owner often find the cutover and access model take longer than the install. DeployOpen works from a written, fixed scope if you prefer to hand that part over.
What drives the effort of moving a private module registry?
Effort scales with four things: the number of private modules, the number of providers you publish, the number of versions each one carries, and how many VCS links feed them. A small set of modules with one version each is a short job. Dozens of modules with years of tagged releases, pinned in many repositories, means more source rewrites and more checks. Each VCS connection to GitHub, GitLab, Bitbucket or Azure DevOps also needs its permissions mapped to groups in Terrakube, which Dex authenticates against your identity provider. Ask for an inventory of modules, providers, versions and VCS links before any scope is agreed.
What recurring work does a self-hosted private registry add?
The registry adds ongoing work that HCP Terraform previously carried for you. Expect these recurring tasks:
- Upgrades of Terrakube and its database, tracked against its releases and tested before rollout
- Backups of the database and of whatever stores published module and provider content
- Periodic access reviews of groups that can publish, read or change VCS connections
- Monitoring of the services and certificates that module consumers depend on
The exact cadence depends on your change policy and how often Terrakube and OpenTofu release. Confirm these tasks, their owner and their frequency in writing before you cut over.
How long does a private registry migration take?
The duration depends on scope rather than on a fixed number of days. A registry with a few modules, one team and no provider publishing can move quickly. A registry with many modules, several business units, legacy version tags and configurations spread across many repositories takes longer, mainly because each source reference and version constraint must be verified. Testing with a small change, as OpenTofu's migration guidance suggests, adds time but reduces risk. Ask any provider for a timeline that is tied to the inventory and the agreed deliverables, and check what is excluded.
What should we ask a consultant to put in a written scope?
A written scope should name exactly what is delivered and what is not. Ask for:
- The inventory method and the list of modules, providers and versions in scope
- How module sources and version constraints in each configuration will be updated, and who reviews them
- Which identity groups map to publish, read and admin roles, and how Dex is configured
- Backup, restore and upgrade procedures, with their owner after handover
- Acceptance criteria for the cutover, and what happens if a consumer breaks
- Items the client must supply, such as repository access and identity provider details
Fixed-scope engagements agree scope, deliverables and timelines in writing before work starts, so these points belong in that document.
Is the Terrakube registry the same as HCP Terraform's private registry?
No, they are not identical, so compare them feature by feature before you commit. Terrakube provides a private registry for Terraform modules and providers, and it is part of the same organization, workspace and permission model as its run platform. HCP Terraform's registry has its own publishing workflow, sharing rules and integrations. Check each capability you rely on, such as how versions are published, how providers are signed and how consumers authenticate, against the capability map on this site and the Terrakube documentation. Anything you cannot confirm should be tested in a pilot before you retire the hosted registry.
Can the public OpenTofu Registry hold our private modules?
No. The public OpenTofu Registry, searchable at search.opentofu.org, lists community providers and modules that are published openly, so it cannot hold private code. Private modules and providers must live in a private registry, such as the one built into Terrakube, or in another store you control. You can still use public providers and modules from the OpenTofu Registry alongside your private ones, and your configurations will reference both. Keep the two sources clearly separated in your module sources so that access control stays with your internal registry.
Will changing module sources break existing configurations?
It can, if the source paths or version constraints change without checks. Every configuration that references a private module must point at the new registry address and use a version constraint the registry can satisfy. Moving a module without updating its constraints can pull an unexpected version or fail at init. Run tofu init and a plan against a non-production workspace after each change, and review the plan output for unintended resource changes. Your change record should show which sources and constraints were updated, by whom and when.
How DeployOpen scopes and delivers registry replacement
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For the HCP Terraform private registry, we start from a written scope that defines which modules, providers and module sources move to Terrakube's private registry, which stay on the public OpenTofu Registry, and how your configurations will reference them.
How we scope
- We inventory every private module and provider in your HCP Terraform organization and record its current source and version constraints.
- We decide which items move to Terrakube's private registry and which community providers keep pointing at the public OpenTofu Registry.
- We agree the written scope, deliverables and timeline with you before any work starts, since most engagements are fixed-scope.
How we build
- We deploy Terrakube in your own cloud account, data center or air-gapped network, and configure its private registry for your modules and providers.
- We rewrite module source and version constraint lines in your configurations and verify that
tofu initresolves each one. - We test publishing and consuming a sample module version in a non-production workspace before any production configuration changes.
How we hand over
- We document the registry setup, the module publishing steps, group permissions for modules, and the rollback path for each configuration change.
- We record which dependencies still rely on external sources so your team knows what to review on future upgrades.
- We walk your platform team through the handover and provide written runbooks for registry operations, backups and access reviews.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- We can track OpenTofu and Terrakube releases against your registry configuration and plan upgrades in a separate written scope.
- We can prepare access control and change evidence for your compliance assessments, while independent auditors issue any formal opinion.
