Migrate from HCP Terraform to Terrakube

Moving workspaces from HCP Terraform to self-hosted Terrakube is mostly state, configuration and identity work, and it can run in parallel with the hosted service until cutover.

On this page

Migrate from HCP Terraform to Terrakube: what the move involves

The move is a state, backend and identity migration that runs in parallel. A platform team leaving HCP Terraform, whether because of a renewal, a pricing change, a residency requirement or lock-in, has to move each workspace's state out of the hosted service, point the configuration at the Terrakube API, and move people from HashiCorp's sign-in to Terrakube's Dex-based authentication, all without leaving a window where nobody can plan or apply. Terrakube does not run Terraform or OpenTofu itself in the sense of replacing the CLI. The CLI remains the tool that initializes, plans and applies, and Terrakube supplies the remote runs, state storage, variables, VCS connections and private registry behind it. In practice, the platform engineers who already operate HCP Terraform usually carry out the work, with a security or identity lead owning the group mapping and the cutover sign-off. The effort is moderate and the risk sits in state and secrets rather than in code. Configurations often need little change, since the cloud block or backend "remote" block only needs the Terrakube hostname, and terraform login (or the OpenTofu equivalent) must be run against that hostname. The work that takes time is re-creating what the state versions API does not export, such as workspace variables, sensitive values, team permissions, VCS links and notification settings, and checking every workspace one by one. Ask Terrakube's maintainers and your own platform team to confirm how each object type maps in your version before you commit to a schedule. A sound first step is to inventory every workspace, export state from a copy-tested set, and run a small change through Terrakube against a non-production workspace. The Terrakube documentation and its CLI-driven workflow guide describe the configuration you will need. Decide early whether to switch the CLI to OpenTofu in the same change. Running the migration in two steps keeps each rollback simple, because a failure in backend configuration is easier to diagnose when the binary is unchanged. If you move to OpenTofu at the same time, test state encryption settings before any production state is written, because OpenTofu can encrypt state at rest with providers such as AWS KMS or OpenBao, and changing that later means handling state again. Keep HCP Terraform active and read-only until every workspace has completed a clean plan and apply on the new backend, and plan the retention of exported state files as sensitive records.

Which HCP Terraform capabilities map cleanly to Terrakube

This table maps each HCP Terraform capability to its Terrakube equivalent and marks it as clean, needs rework or gap. Read the status column as the amount of work each item adds to the migration, not as a verdict on either product. Items marked needs rework or gap should be scoped and signed off before any workspace is cut over.

CapabilityTerrakube equivalentMigration status
Organizations and workspacesOrganizations and workspaces are recreated in Terrakube with matching names and settingsNeeds rework: recreate each workspace by hand and record its settings first
Remote backend and cloud blockTerrakube supports both, so CLI-driven runs can keep the same configuration shapeClean: change the hostname and log in with terraform login against the Terrakube API
State migrationState is downloaded from HCP Terraform's state versions API and loaded into Terrakube through the remote backendNeeds rework: verify each state file and confirm locking before cutover
Private registryTerrakube provides a private registry for modules and providersNeeds rework: republish modules and update source addresses and version constraints
VCS connectionsConnections exist for GitHub, GitLab, Bitbucket and Azure DevOps, configured again in TerrakubeNeeds rework: new OAuth or app credentials and webhook setup for each repository
Teams and permissionsGroup permissions in Terrakube, with identity supplied through Dex, replace HCP Terraform team settingsNeeds rework: map each team to a group and test access on every workspace
Variables and variable setsVariables are re-created on each workspace, including sensitive values that HCP Terraform does not exportNeeds rework: sensitive values must be re-entered from the secrets source
Policy checks (Sentinel)Sentinel does not carry over directly; Terrakube uses OPA policy checks through its extensionGap: policies must be rewritten in Rego and tested again
Run UI and approvalsTerrakube provides a run UI and API for plans and applies, with approval flows to confirmNeeds rework: confirm approval steps and notifications match your change process

What exports and what must be re-created

HCP Terraform lets you download current state, but most of the surrounding configuration has no documented export. Plan the migration around two lists: what you pull out through the state versions API, and what you rebuild by hand in Terrakube before the first run.

Current state through the state versions API

The state versions API returns each workspace's latest state, and for states created by Terraform 1.3 or later it includes a JSON download URL. Pull the JSON state for every workspace, not only the production ones, and store the files in encrypted storage under your control. Confirm each file's serial and lineage against the workspace before you import it into the new backend, because a stale download can overwrite newer resources on the next apply.

Variables and variable sets

Workspace variables, sensitive values and variable sets are not part of the state, so they do not come out with it. Export the names and non-sensitive values from the HCP Terraform interface or API before you cancel, and record which values are marked sensitive. Sensitive values must come from your secrets manager or a fresh entry in Terrakube, since HCP Terraform does not return them in plain text.

VCS connections and workspace teams

VCS links to GitHub, GitLab, Bitbucket or Azure DevOps are configured per workspace and must be recreated in Terrakube, which retrieves code from the same providers. Teams and their workspace permissions are also lost in translation. Map each HCP Terraform team to a group in your identity provider, then assign workspace, module and VCS permissions by group in Terrakube, which uses Dex for authentication.

Notifications and run triggers

Notification configurations, webhooks and run triggers between workspaces are settings that HCP Terraform does not hand over as a migration artifact. List every trigger chain and every Slack, email or webhook receiver before cutover, then rebuild each one in Terrakube or in your CI system. Test a downstream workspace with a no-op change so you know the chain fires as expected.

terraform_remote_state consumers

Configurations that read another workspace's outputs through the terraform_remote_state data source need extra care during migration. Find every consumer across your repositories, since the source workspace's backend changes when you move. OpenTofu's migration guide covers this case separately, so read it before you change any producer. Update the backend settings in each consumer in the same change window as its producer.

Private registry modules and provider references

Modules published to the HCP Terraform private registry do not move automatically. Republish each module to Terrakube's private registry or to another source you control, then update module source addresses and version constraints in every configuration that calls them. Check each workspace with a plan before you approve any apply, and confirm the plan shows no unexpected resource replacements.

Migration sequence from inventory to decommission

This sequence moves each HCP Terraform workspace to Terrakube in a controlled order, so every workspace has a verified state backup, a tested run path and a documented cutover before the HCP Terraform organization is retired. Each step ends with a named output that the next step depends on.

  1. Inventory workspaces and their dependencies

    The platform or cloud team lists every organization, workspace, variable set, VCS connection, team, private registry module and run trigger in HCP Terraform, and records which workspaces read other workspaces through the terraform_remote_state data source. Confirm the Terraform version each state was created with, since state download behavior depends on it. The output is a written inventory with one row per workspace, its owner, its backend type and its upstream and downstream dependencies. Done when the list has been reviewed by the owners of every workspace that other workspaces depend on.

  2. Back up state and code before any change

    Before touching any workspace, download the current state for each one through the state versions API and store it in a versioned, access-controlled location you own. Also archive the configuration repositories at the commit that matches the latest applied run. OpenTofu's migration overview recommends backing up state and code as the first step of any move, because it keeps the process reversible. The output is a dated backup set with checksums and a restore note per workspace. Done when a test restore of one state file has been checked against the workspace's latest state serial.

  3. Stand up Terrakube and run a pilot workspace

    Install Terrakube with its Helm chart or Docker Compose files, connect it to your relational database, and configure Dex with your identity provider and group mappings. Choose one low-risk workspace with no terraform_remote_state consumers, recreate its variables, VCS link and team permissions in Terrakube, and import the backed-up state. Run a plan with no code changes and confirm it reports no changes. The output is a pilot workspace that plans cleanly against the imported state. Done when the team that owns the workspace has run a plan and an apply of a small, approved change from Terrakube.

  4. Decide on OpenTofu or Terraform for the pilot

    Decide whether the pilot runs OpenTofu or Terraform, and confirm the chosen version in the CLI and in the Terrakube workspace settings. OpenTofu's migration overview describes a four-step path: back up, install OpenTofu, initialize and verify the configuration, then test with a small change. Check that providers and modules resolve from the registries you use. If you enable state encryption, plan the key provider in advance, since OpenTofu offers AWS KMS, GCP KMS, OpenBao and Azure Vault among others. The output is a recorded runtime decision and a verified init and plan on the chosen binary. Done when a plan completes with no unexpected diffs.

  5. Run HCP Terraform and Terrakube in parallel

    Keep the HCP Terraform workspace in place but freeze new applies for the pilot. Point the CLI for a test copy of the configuration at Terrakube, and compare plan output from both systems on the same commit. Repeat for the remaining workspaces in batches, starting with those that have no dependents. Record every difference in plan output and resolve it before moving on. The output is a parity log per workspace showing that Terrakube plans match HCP Terraform plans. Done when two consecutive comparison runs show no unexplained differences for a workspace.

  6. Cut over with the cloud block or remote backend

    For each workspace, change the configuration to use the cloud block or remote backend that points at the Terrakube API hostname. Terrakube's CLI-driven workflow documentation states that the cloud block needs Terraform v1.1 or later, and that earlier versions can use the remote backend, which also supports migrating state. Authenticate with terraform login against the Terrakube hostname, then run init with state migration if prompted and confirm the plan reports no changes. Update CI variables and any terraform_remote_state references to match. The output is a cutover record showing the commit, the hostname and the empty post-cutover plan. Done when the first real apply through Terrakube has succeeded and the workspace is marked as migrated.

  7. Decommission HCP Terraform after verification

    Once every workspace has run successfully through Terrakube for a period your change process approves, disable VCS triggers and run permissions in HCP Terraform, then retain the final state backups under your records policy. Before cancelling any paid plan, confirm that no pipeline, notification or dependent configuration still references HCP Terraform hostnames. Ask your vendor contract owner which data export and retention terms apply at cancellation. The output is a decommission record listing each workspace, its final HCP Terraform state version and where its backup is stored. Done when the inventory from the first step has every row marked as migrated and verified.

Should you switch to OpenTofu during the same move?

Keep the platform move and the CLI change separate unless you have a specific reason to combine them. Terrakube runs both Terraform and OpenTofu, so the remote backend or cloud block works with either binary, and you can move your workspaces first while your team keeps using the CLI it already has. OpenTofu is an MPL-2.0 fork of Terraform under Linux Foundation stewardship, and it was accepted to the CNCF Sandbox on April 23, 2025. Moving the platform and the CLI at once doubles the number of changes you must validate, and a state problem becomes harder to isolate when both the backend and the binary are new.

The main reason to switch early is state encryption. OpenTofu encrypts state and plan files at rest, for local storage and remote backends, with key providers such as AWS KMS, GCP KMS, OpenBao and Azure Vault. Confirm which key provider your security team approves and where the key lives before you configure it, because encrypted state written with a key you later lose cannot be read. Also confirm that your Terrakube deployment stores the encrypted artifacts as you expect. Feature parity is the other factor: the OpenTofu FAQ aims to keep parity with Terraform, but it does not guarantee compatibility with future Terraform releases, so check your provider and module versions against the OpenTofu release you pin.

A workable order is to finish the state migration on Terraform, verify each workspace with a plan that shows no unexpected changes, and then switch the binary in a separate change. OpenTofu's migration guide describes this as a safe and reversible process: back up state and code, install OpenTofu, initialize, verify and test with a small change. If your configurations share data through terraform_remote_state, give that switch extra time, because the migration guide flags that case for additional care. Record the Terrakube version you deploy, for example the 2.33.2 release published on September 14, 2026, so you can tell platform changes from CLI changes if a run behaves differently.

What drives the cost and duration of the move

This table lists the factors that change how long the move takes and what it costs to run afterward, with the one-time and recurring side of each. Use it to structure a written scope request, since each driver maps to a line a quote should price separately. Workspace count, state size and cross-workspace dependencies usually matter most for the migration itself, while hosting and platform ownership drive what continues after cutover.

DriverWhy it changes cost or effortWhat to ask for in a written scope
Workspace count and namingEach workspace needs its state exported, verified, imported and its backend block changed, so effort grows with the number of workspaces and their owners.An inventory of every workspace with owner, state size, last run date and whether it is still in use
Variables and secrets volumeSensitive values cannot be exported from HCP Terraform, so each one is re-entered by hand or re-sourced from a secrets manager.A count of variables by workspace, marking which are sensitive and where their true values are kept
VCS connections and triggersEach repository link, branch trigger and working directory must be rebuilt in Terrakube and tested with a run.A list of VCS connections, the GitHub, GitLab, Bitbucket or Azure DevOps accounts they use, and the expected trigger behavior
Teams and permissionsTerrakube assigns permissions by group through Dex, so HCP Terraform teams must be mapped to groups and access tested per workspace.A mapping of current teams to identity provider groups and the access model each team needs
remote_state dependenciesWorkspaces that read each other through terraform_remote_state must be moved in a planned order, and the readers updated at the same time as the writers.A dependency graph of which workspaces read which outputs and an agreed cutover sequence
Self-hosted database and runtimeTerrakube needs a relational database supported by Liquibase and either a Helm chart on Kubernetes or Docker Compose, each with its own setup and sizing.Confirmation of the chosen database, runtime, high availability design and who operates them after go-live
Identity integrationConnecting Dex to the organization's identity provider, such as SAML or Azure Active Directory, adds configuration and testing before users can log in.The identity provider type, certificate and group handling, and how logins are tested
Adopting OpenTofu at the same timeSwitching the CLI to OpenTofu alongside the platform change adds provider and version checks, and state encryption decisions if enabled.A decision on whether the CLI changes in the same window, and a provider and module compatibility check
Recurring platform ownershipUpgrades, backups, monitoring and on-call for the Terrakube stack and its database continue after cutover, and this is a continuing team cost.Who owns upgrades and backups, the support hours, and the recovery steps for a failed run or state loss

What usually goes wrong and how to prevent it

Most failed HCP Terraform to Terrakube moves do not fail on the first run. They fail in the weeks when two copies of state, two sets of variables and two webhook paths exist at once. Each card below names one such risk and the check that keeps it from reaching production.

State drift during parallel runs

While workspaces run from both HCP Terraform and Terrakube, the state in each place can diverge after any apply. A plan that looks clean in one system can be stale in the other. Freeze each workspace's writes to one backend at cutover, then compare the serial and lineage of the downloaded state with the state Terrakube holds before the first self-hosted apply. Record the state version you migrated so you can prove which copy is current.

Forgotten variables and sensitive values

HCP Terraform stores workspace variables, environment variables and sensitive values that the API will not return in plain text. Teams often migrate only the Terraform code and discover missing credentials on the first plan. Build an inventory per workspace that lists every variable, its category and whether it is sensitive, then confirm each value with the owning team. Sensitive values usually have to be re-entered from the secrets source, not copied from the old platform.

Broken VCS webhooks

Runs triggered by a pull request or a branch push depend on webhook endpoints and tokens configured in the VCS provider. When a repository still points at HCP Terraform, merges may start hosted runs that no longer reflect the Terrakube configuration, or no run starts at all. Reconfigure each repository's webhook to the Terrakube endpoint, then test with a harmless change on a non-production workspace and confirm the run appears in the right place.

Missing team permissions after Dex setup

Terrakube uses Dex for sign-in and assigns workspace, module and VCS permissions by group. If group names do not match the identity provider claims exactly, users can sign in but lose access to workspaces they used daily, or gain access they should not have. Map each HCP Terraform team to a Terrakube group, verify membership through the identity provider, and test with one account per role before inviting the wider organization.

Applies run from two places

If a developer still runs terraform apply from a laptop against the hosted backend while CI applies through Terrakube, two processes can change the same resources in an order neither expects. Locking helps only when both sides use the same backend. Announce a single apply path for each workspace, remove apply permissions from the hosted organization once cutover starts, and check the state lock behavior in a test workspace first.

Cancelling before verification

Cancelling the HCP Terraform organization ends access to state, run history and variables that have no export path. Once it is gone, a missed workspace can only be rebuilt from code and any remaining backups. Before cancelling, confirm for each workspace that the latest state downloads, that a plan against Terrakube shows no unexpected changes, and that a rollback path is documented. Ask your vendor in writing what data remains available after cancellation and for how long.

How the move differs by starting point

A small team with a handful of workspaces usually moves for cost predictability or to stop depending on a hosted free plan. The migration is mostly a sequencing exercise: few workspaces, few variables and a short list of VCS links. Because the state volume is small, you can move one workspace at a time and keep the HCP Terraform workspace in place until each one has produced a clean plan.

  • Inventory first: list every workspace, its VCS connection, its variable sets and its current Terraform or OpenTofu version.
  • Move one workspace at a time: download its state, point a test configuration at Terrakube and run a plan with no changes before touching the next workspace.
  • Keep the CLI simple: a single operator can often use the same terraform login pattern against your Terrakube API hostname.
  • Decide on OpenTofu early: switching the binary during the same window adds a second variable, so many small teams separate the two steps.
  • Plan for a one-person platform role: someone must own upgrades and backups of the Terrakube database and state.

Confirm with the vendor what the enhanced Free tier counts as managed resources today, so you know whether staying put is still an option while you test.

Questions teams ask before moving from HCP Terraform

How much effort and time does a move from HCP Terraform to Terrakube take?

The effort depends mostly on how many workspaces you run, how many of them use VCS-connected runs, and how many variables, teams and private registry modules must be re-created by hand. No duration figure is supplied for this move, so ask any implementation partner for a written estimate based on your own workspace inventory. Start by counting workspaces, listing which ones use the cloud block or the remote backend, and noting which depend on terraform_remote_state data sources, since those need extra care. Each workspace adds a repeatable set of steps: export state, point the configuration at the Terrakube API, re-create variables and VCS links, then run a plan and confirm it shows no unexpected changes. Pilot workspaces give you a realistic figure before you commit to the full set.

Can an in-house platform team complete the migration alone?

Often yes, if the team already runs Terraform or OpenTofu in production and has someone comfortable operating Kubernetes or Docker Compose. Terrakube documents installation with a Helm chart or Docker Compose, and it needs a relational database that Liquibase supports, such as PostgreSQL. The harder part is usually not the install but the ongoing operation: upgrades, backups of the Terrakube database, authentication through Dex, and group-based permissions on workspaces, modules and VCS connections. Ask whether your team has capacity for that after cutover. DeployOpen plans, implements, integrates, hardens, backs up, upgrades and documents self-hosted platforms in your own infrastructure, and ongoing support is available as a retainer, so you can choose which parts to keep in-house.

What does the migration need from our team before work starts?

Expect to provide access and a few decisions before any state moves. The team needs read access to every HCP Terraform organization in scope so state versions and settings can be exported, plus a place in your own infrastructure to host Terrakube and its database. You also need an owner for variables that contain secrets, a decision on identity provider integration through Dex, and a list of teams that must map to Terrakube groups. Take complete state backups before any change, keep the originals until every workspace has been verified, and choose one pilot workspace with low risk and a clear owner. Scope, deliverables and timelines are agreed in writing before a fixed-scope engagement starts.

Can state move to Terrakube without downtime?

State can usually be moved one workspace at a time, with planned pauses limited to the workspace being cut over. The state versions API exposes current state, including a JSON download for states created by Terraform 1.3 or later, which is how state leaves HCP Terraform. Freeze runs for the workspace being moved, download the state, confirm its serial and resource count, then point the configuration at Terrakube and run a plan. A plan that shows no changes confirms the state is intact. Whether any particular service sees downtime depends on your architecture and on the workspace, not on the platform, so confirm the change window for each workspace with its owner.

Do we have to switch to OpenTofu at the same time as Terrakube?

No. Terrakube supports both Terraform and OpenTofu, so you can move the platform first and change the CLI later, or switch both together. OpenTofu's migration overview describes four steps: back up state and code, install OpenTofu, initialize and verify the configuration, and test with a small change, and it describes the process as designed to be safe and reversible. Keep in mind that OpenTofu aims for feature parity with Terraform but does not guarantee compatibility with future Terraform releases. OpenTofu also adds client-side state encryption with key providers such as AWS KMS, GCP KMS and OpenBao, which you may want to configure as part of the same change.

Which parts of the HashiCorp and Terrakube documentation do we still need to check?

Confirm the exact API calls, authentication steps and CLI behavior against the current documentation for your versions before writing scripts. The HCP Terraform state versions API page describes export endpoints, and Terrakube's CLI-driven workflow page describes the cloud block, which needs Terraform v1.1 or later, the remote backend for earlier versions, and terraform login against the Terrakube API hostname. Check the Terrakube GitHub releases page for the version you plan to run, since release notes change how installs and upgrades behave. Items that the documentation covers only partly, such as variable sensitivity, team permissions and VCS webhook setup, should be tested in a pilot and recorded in your runbook.

What does HCP Terraform keep that we must re-create by hand?

Several objects do not move with state and must be re-created in Terrakube. These typically include workspace variables, including sensitive values that you may need to source again from a secrets manager, VCS connections, team memberships and their permissions, and any private registry modules or providers you publish. Recreate them in a controlled list per workspace and verify each item with a plan before cutover. Terrakube assigns permissions on workspaces, modules and VCS connections by group, so map HCP Terraform teams to Terrakube groups before you start. Confirm the full list of objects that have no export path against the state and data export documentation for your HCP Terraform plan.

How DeployOpen scopes and runs the Terrakube migration

DeployOpen is a Chainscore Labs company that plans, implements, integrates, hardens, backs up and documents self-hosted open-source platforms inside the client's own infrastructure, including the cloud accounts, data centers or air-gapped networks where Terrakube and the OpenTofu CLI would run. For a move off HCP Terraform, that work typically covers the Terrakube deployment itself (Helm chart or Docker Compose, as documented in the README), its database, identity integration through Dex, VCS connections, team and workspace permissions, and the state backend. DeployOpen does not issue audit reports or certifications, so any compliance evidence it prepares is handed to your independent auditor. Before any work starts, the scope should be written down: the list of workspaces, the state and variable inventory, the decision on whether OpenTofu is adopted at the same time or later, and the cutover and rollback steps for each workspace.

Most engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work begins. A quote follows from that written scope rather than from a published price list, which DeployOpen does not maintain. To get a comparable quote from any provider, ask for the workspace count and size, the number of VCS connections and teams to re-create, the target database and hosting environment, the identity provider to integrate, and whether the scope includes running OpenTofu, extensions such as OPA policy checks, and handover documentation. Ask which items are one-time work and which recur. Ongoing support, upgrades and continuous testing of the Terrakube deployment are available as retainers, and that recurring cost should be priced separately from the migration itself. Confirm in the written scope who holds administrator credentials and state backups after handover.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.