What you can export from HCP Terraform and what you must rebuild
Workspace state is the one object you can pull out of HCP Terraform programmatically. The state versions API exposes each workspace's current state, and it includes a JSON download URL for states created by Terraform 1.3 or later. Almost everything else, including variables, workspace settings, team access, VCS links, run history and notifications, has no equivalent export and must be written down and re-created in the target platform. Your exit plan should treat state as the data you move and everything else as configuration you rebuild. Reading state requires permission to read state versions for each workspace. If a workspace has no current state, or your user is not authorized, the current state version endpoint returns a 404, which can look like an empty workspace when it is not. Before you start, confirm with a workspace administrator that your account can read every state version you need, and keep a record of which workspaces hold state, which are empty, and which are locked. Sensitive variable values are write-only in HCP Terraform, so plan to obtain them from the teams that own the source systems, not from the platform. In the replacement model, OpenTofu is the CLI and a platform such as Terrakube or Atlantis runs the plans and stores state. Terrakube can hold organizations, workspaces, variables and registry modules that you re-create by hand, and Atlantis expects an external state backend such as S3 or GCS. Before cancelling, check each workspace against an inventory: state downloaded and checksummed, variables recorded, VCS and team mappings noted, and a test plan on the new platform showing no unexpected changes. Confirm the cutover steps with the migration pages linked from this section.
Which data exports from HCP Terraform, by method and format
This table compares the ways to read state and related data out of HCP Terraform, with the access rules and format limits that apply to each. Read it row by row before you script a bulk export, because the state rows have permission and format conditions that decide whether a download succeeds.
| Export item | Method and format | Access and limits |
|---|---|---|
| Current state | State versions API, current state version endpoint, raw state download URL | Requires permission to read state versions for the workspace. Returns 404 if the workspace has no current state or the user is not authorized. |
| Current state (JSON) | State versions API, JSON state download URL | Available for states created by Terraform 1.3 or later. Older states may need a raw download and a separate check. |
| Historical state versions | State versions API, listing and per-version download URLs | Same read permission on the workspace applies. Confirm retention of older versions in your plan or edition before relying on them as a backup. |
| Workspace state access check | API call or CLI session with a token for the workspace | A 404 can mean missing state or missing permission, so confirm the user's role on each workspace before reading the result as empty. |
| Variables, workspace settings, VCS links and teams | No documented state-style export in the researched sources | Record these by hand or through the API before cancelling. Confirm what the API returns for your organization version. |
| Registry modules and providers | Private registry contents are not covered by the state versions API | Download source code from its VCS origin or your module repositories. Confirm how the private registry can be exported in your environment. |
How the state versions API returns each workspace's state
The state versions API is the only documented route for pulling each workspace's state out of HCP Terraform in bulk. For every workspace you want to keep, first list its state versions, then fetch the current one. The current state version endpoint returns a 404 if the workspace has no current state or if your user lacks permission to read state versions for that workspace, so a 404 on a workspace that you know has state usually means a permissions problem, not missing data. Run the list call with an account that has read access to every workspace in scope, and record the workspace name, ID and state version count in your inventory before you download anything. The API documentation linked from this section sets out the request paths and the fields returned for each state version.
Each state version exposes a raw state download URL and, for states created by Terraform 1.3 or later, a JSON state download URL. The JSON form is easier to query with tools such as jq and is the format to use when you need to inspect resource addresses or outputs. Older workspaces may only offer the raw form, so do not assume JSON is available. Keep the raw file as the archive copy for every workspace, because it is the form closest to what Terraform itself wrote and it remains usable for a restore if a JSON conversion goes wrong. Download URLs are short-lived and require a valid API token, so script the downloads and verify each file's size and checksum immediately after saving it.
Treat every downloaded state file as sensitive material. State can contain provider credentials, database passwords and other secrets in plain text, depending on what your configurations stored. Store the exports with the same access controls, encryption and retention rules that applied to the original workspace, and restrict who can read the bucket or share holding them. Confirm with your security team where the files will live before the first download, and record who approved that location, since the export is now a copy of your most sensitive infrastructure data.
What has no export and must be re-created
The state versions API moves state out of HCP Terraform, but most of the surrounding configuration does not come with it. The cards below cover the objects the researched sources do not document as exportable, the workaround for each, and the point where a secret owner must re-enter a value. Confirm each gap with HashiCorp before you assume it is permanent.
Workspace variables and sensitive values
Workspace variables hold the inputs that each run depends on, and sensitive variables are write-only once saved. Record every key, category (Terraform or environment), HCL flag and non-sensitive value from the UI or API while you still have access. Treat each sensitive value as a re-entry task for the secret owner, not something the migration can copy. Compare the variable count per workspace with the target before you cancel.
Variable sets
Variable sets are shared groups of variables applied across several workspaces, so a single missing set can break many runs at once. List each set, its scope and the workspaces it applies to before you start moving workspaces. Rebuild them as shared variable files, Terrakube variable definitions or pipeline secrets, then confirm each workspace resolves the same values. Check which sets carry sensitive data before you assign ownership.
Teams, roles and permissions
Team membership and workspace permissions define who can plan, apply and read state. These assignments are not part of the state data, so they must be recorded and rebuilt by group. In Terrakube, permissions on workspaces, modules and VCS connections are assigned by group through the identity provider. Map each HCP Terraform team to a group and verify that read access to state matches what the old team had.
VCS connections and OAuth tokens
Each VCS connection links a workspace to a repository and branch, and it relies on an OAuth token that belongs to the connecting account. The token itself cannot be exported, so every connection must be re-authorized on the new platform. Record the repository, branch, working directory and trigger settings for each workspace. Confirm with the source control administrator which account will own the new integration.
Run history and policy configuration
Past run logs, plan outputs and audit events are useful evidence for change records, but the sources do not document a full export of them. Archive the runs you need for compliance now, and export or screenshot the policy set and any Sentinel configuration as text. Translate policies into Open Policy Agent rules and test them against recent plans. Ask HashiCorp directly what run history can be downloaded for your plan.
Private registry contents
Private modules and providers published to the HCP Terraform registry are stored by the platform. Obtain the source code of each module from its repository, not from the registry, and republish it to Terrakube's private registry or another source your configurations can reach. Update module sources and version constraints in each configuration, then run a plan to confirm the same resources resolve.
The export sequence and how to verify each step
This sequence turns an HCP Terraform estate into a verified inventory, a set of downloaded state files and a written record of everything that does not travel with them. Each step ends with a check you can repeat before any workspace is cancelled.
Back up state and code first
Before touching anything in HCP Terraform, take a complete copy of every configuration repository the workspaces use, at the commit each workspace currently runs. OpenTofu's migration guide recommends backing up state and code as the first step and describes the overall process as designed to be safe and reversible, so this backup is the baseline you return to if a later step fails. Platform or security owners should hold the copy in storage they control. The step is done when each repository has a tagged or recorded commit hash that matches the workspace's last successful run.
Inventory every organization and workspace
List each organization in the account and every workspace inside it, including workspaces that are locked, idle or rarely used. Record the workspace name, its VCS or CLI-driven source, its working directory, its current state version and the teams with access. Platform engineering usually owns this list, and it should be reviewed by the teams that depend on each workspace. The step is done when the inventory matches the workspace list shown in the HCP Terraform interface and every entry has an owner.
Pin the Terraform and OpenTofu versions in use
Record the Terraform version each workspace runs, which is set in the required_version constraint, the workspace settings or a
.terraform-versionfile, along with the provider versions locked in.terraform.lock.hcl. This tells you which OpenTofu release can read the state and which providers you need to mirror. Note any workspace on a version the team has not upgraded in a long time, because that affects compatibility testing later. The step is done when every workspace has a recorded Terraform version, an OpenTofu candidate version and a lock file checked into its repository.Download state versions in raw and JSON formats
Use the state versions API to list the state versions for each workspace and download the current one. The API returns a raw state download URL and, for states created by Terraform 1.3 or later, a JSON state download URL. Keep both forms: the raw file is the exact bytes HCP Terraform stored, and the JSON file is easier to inspect. Your token needs permission to read state versions for the workspace, and the current state endpoint returns 404 when a workspace has no current state or the caller is not authorized, so treat any 404 as a gap to investigate rather than an empty workspace. The step is done when every workspace has a raw file, a JSON file where available, and a written list of exceptions.
Record configuration that is not in state
State does not hold workspace variables, variable sets, run triggers, notification settings, team assignments, VCS connection details, policy sets or the workspace's run settings. Export or write these down from the workspace settings pages and the API, and mark which items must be re-created by hand. Store secret values in your own secrets manager rather than in a spreadsheet, and record which values are sensitive so they are not copied in plain text. The step is done when every non-state object has an entry in the migration record with its source workspace and a target owner.
Export module sources and private registry items
List every module and provider the configurations reference, separating public registry sources from items published to the HCP Terraform private registry. Public items can be referenced again from the OpenTofu Registry, while private modules need their source repositories and version tags copied to a location your self-hosted platform can reach. Update module source strings and version constraints in a branch so the change is reviewed with the code. The step is done when each private module has a repository, a tagged version and a documented source address in the target environment.
Verify with checksums and a plan against a copy
Calculate a SHA-256 checksum for each downloaded state file and store the list beside the files, so later copies can be compared. Then restore one copy into a non-production backend, point a copy of the configuration at it, and run
tofu plan. A clean plan with no unexpected changes shows that the state and code agree. Repeat for each workspace, and treat any unexpected diff as a blocker until the cause is understood. The step is done when every checksum matches its stored record and every test plan completes with changes you can explain. Only then should a workspace be considered ready to cancel.
Why terraform_remote_state dependencies need extra care
Workspaces that share outputs through the terraform_remote_state data source must be migrated as a group, not one at a time. A consumer workspace reads another workspace's state file directly, so once the producer's state moves, or its backend changes, the consumer can fail on its next plan or read stale values without any error. Before you export anything, build a map of every producer and consumer pair, including which output names each consumer reads and which backend block each one points to. Search the configuration of every workspace for terraform_remote_state blocks, and check the CLI-driven and VCS-driven workspaces alike, since both can carry the reference.
Use that map to set a cutover order. Plan to move each producer and its consumers in the same change window, and confirm that the producer's outputs are unchanged after its state is imported into the new backend. Record the output values before the move and compare them afterward. Decide whether the old HCP Terraform state will stay readable during the transition, because consumers still pointing at it will keep reading whatever it holds. Keep the old workspace and its state versions available until every consumer has been verified, and do not cancel the subscription while any reference still points there.
OpenTofu's migration overview warns that configurations sharing data through terraform_remote_state typically need additional care, and it links a separate guide for that case. Read that guide before you start, and confirm with your platform team how your chosen backend, whether Terrakube or a state store used with Atlantis, will expose producer outputs to consumers. The exact steps depend on your backend configuration, so treat the guide as the authority for that detail. Read the OpenTofu migration overview before you finalize the cutover plan.
Checks for each workspace, by how it is run
Workspaces driven from a terminal use the cloud block or the remote backend, so their state history and variables live only in HCP Terraform. Start by listing the state versions for each workspace through the state versions API. Your user needs permission to read state versions for that workspace, and the current state endpoint returns 404 when the workspace has no current state or you are not authorized, so check permissions before you assume the state is empty.
- State version count and latest serial: Record how many state versions exist and the serial of the latest one. Download the JSON state for the current version and for any older version you may need to roll back to.
- Locking status: Confirm the workspace is unlocked and that no engineer is running a plan from the CLI. A lock with no active run needs an owner's decision before you proceed.
- Variable inventory: List each Terraform and environment variable, its category and whether it is sensitive. Non-sensitive values can be copied, while sensitive values need the source described in the next tab.
- Backend and cloud block settings: Record the organization, workspace name and the
cloudorbackendblock in each configuration, since these point the CLI at HCP Terraform. - Queued or applying runs: Check the run list for runs in the queue or in the applying state. Let an applying run finish, and confirm with the owner whether any queued run should be discarded.
Before you cancel, confirm that the last state download matches the serial you recorded and that no run is queued or applying.
Workspaces connected to a version control repository start runs from pull requests or merges. The code lives in your repository, but the state, run history and workspace settings still sit in HCP Terraform, so the state checks from the CLI path also apply here. The repository connection and the automation around it need their own inventory because they do not appear in a state download.
- Connected repository and branch: Record the repository, the working directory, the branch each workspace tracks and whether automatic apply is enabled. Automatic apply changes how much warning you get before a change lands.
- Runs waiting for confirmation: A run that is planned and waiting for confirmation is not finished. Decide whether it should be applied or discarded before you cancel, and record the decision.
- Run triggers and run tasks: List any run triggers that link one workspace to another, along with any run tasks or policy checks. These do not follow the workspace when you move it.
- Terraform version pins: Record the Terraform version set on each workspace and any
required_versionconstraint in the code. Confirm that OpenTofu accepts the constraints you plan to keep. - VCS connection ownership: Note who authorized the connection and which account or app it uses. You will need to create the equivalent connection in your new platform, and the existing one cannot be exported.
Before you cancel, confirm that every connected repository is documented, that pending runs have a recorded decision and that each trigger has a replacement plan.
Sensitive variables and dynamic provider credentials carry the most risk in an export because the values are often hard to read back once stored. Expect that sensitive variable values will not be fully retrievable through the HCP Terraform interface or API, and confirm this in your own organization before you rely on it. The export plan for these workspaces therefore depends on the systems that hold the original values, not on HCP Terraform.
- Origin of each sensitive variable: Map every sensitive variable to where its value is kept, such as a password manager, a secrets manager, a CI system or a named owner. Where no source exists, plan a controlled re-entry of the value before cutover.
- Variable sets: List every variable set applied to these workspaces, since one set can feed many workspaces and changing it affects all of them.
- Dynamic provider credentials: Identify which cloud roles trust HCP Terraform's identity for each run. Those trust relationships must be pointed at your new runner before the first run there, and you should confirm with the Terrakube documentation how it issues equivalent credentials.
- State contents: State can hold secrets from resources. If you plan to use OpenTofu state encryption, choose the key provider, such as AWS KMS, GCP KMS, OpenBao, Azure Vault or PBKDF2, before the first migrated state is written.
- Approval ownership: Record which teams can apply to each sensitive workspace so that approval rights are rebuilt with the same people in the new platform.
Before you cancel, confirm that each sensitive value has a source you can retrieve and that every dynamic credential trust has an agreed replacement.
What to plan before the contract or plan ends
Exporting state is the easy part. The risk sits in the period around it: which plan you are on, who can still read the workspaces, and whether applies keep changing state while you copy it. The cards below cover the decisions to make before the contract or plan ends.
Confirm your current tier and resource count
The legacy HCP Terraform Free plan reached end of life on March 31, 2026, and remaining organizations moved to the enhanced Free tier of up to 500 managed resources with unlimited users. Check which tier your organization is on now, then count the managed resources across every workspace. Paid tiers bill per managed resource, so the count shows whether you are close to a limit or already over it. Record the figures before you start the export so you can compare them with your final state.
Keep read access until the download is verified
Viewing state versions requires permission to read state versions for each workspace. If you lose that access early, the current state endpoint returns 404 for a workspace you still need, and that looks the same as an empty workspace. Keep a named admin account with read access until you have downloaded each state, compared its serial and resource count with the target, and recorded the result. Remove the access only after that check passes.
Freeze applies during the cutover
Any apply that runs between your final state download and the switch to the new backend creates a state the new platform does not have. Agree a freeze window with every team that runs applies, disable VCS-triggered and scheduled runs for the affected workspaces, and confirm no run is queued or in progress. Lift the freeze only after the new backend holds the state you verified. Write the window and its owner into the cutover ticket.
Retain exports under your records policy
State files often contain secrets, resource identifiers and infrastructure layout, so treat them as sensitive records. Store the exported state, variable lists and workspace settings in location your records policy names, with encryption at rest and access limited to the migration team. Set a retention period that matches your policy and your audit obligations, and record the checksum of each file so a later reviewer can confirm it is unchanged. Do not keep copies on personal devices.
Ask how long data remains after termination
Before you cancel, ask HashiCorp in writing how long workspaces, state versions and logs remain available after the subscription or plan ends, and how you can request deletion. Ask whether any data is deleted automatically and on what schedule. The answer should come from the contract or the vendor's written terms, not from memory of the console. Record the response in your migration file, because it sets the window in which you can still re-download anything you missed.
Inventory objects that do not export
The state versions API returns state, but variables, VCS connections, team permissions, run triggers and notification settings must be re-created by hand in the target platform. Export what the console and API allow, such as variable lists with sensitive values flagged, and write down the rest as a checklist per workspace. Assign each item to an owner. Missing a sensitive variable is a common reason a first apply on the new platform fails.
Questions teams ask before exporting from HCP Terraform
Can we export all our state without a paid HCP Terraform plan?
Probably, but confirm it with HashiCorp for your tier before you plan around it. The state versions API is the documented route for pulling each workspace's current state, and it requires permission to read state versions for that workspace. The endpoint returns 404 when a workspace has no current state or when your user is not authorized, so a 404 can mean missing access rather than missing state. Check your role on every workspace, and ask HashiCorp directly whether your plan and organization type expose the download endpoints you need. The JSON state download URL is available for states created by Terraform 1.3 or later, so older state may need a different check.
How long does a full workspace export take?
The duration depends on how many workspaces you have, how many state versions each one holds, and how much of the work is manual. State download is the quick part when access is in place. Most of the time goes to inventorying workspaces, recording variables and their sensitivity, mapping VCS connections and teams, and confirming that each workspace's configuration still plans cleanly after the move. No timeline figure applies to your environment, so ask for a workspace count and a breakdown of state versions per workspace before agreeing to any schedule in writing.
Can our own team export HCP Terraform data without outside help?
Yes for state and code, which are the parts with the clearest documented path. Your team can download state through the API, keep the configuration in its existing Git repository, and install OpenTofu to verify the configuration. The harder parts are variables, especially sensitive ones whose values the platform does not show back, VCS links, team permissions and any workspaces that read other workspaces through the terraform_remote_state data source. These need someone who knows the dependency map and has a secrets owner ready to supply values. Teams that have run this kind of move before tend to find the gaps faster.
What does our team need in place before starting the export?
Three things matter most. First, read access to every workspace in scope, with permission to read state versions. Second, named owners for secrets and sensitive variables, since their values often live in a password manager, a cloud secrets store or someone's memory rather than in any export. Third, a test environment where you can point a copy of the configuration at a new backend and run a plan without touching production state. Also agree who approves cutover and who can roll back. Confirm each of these with your own administrators before work starts.
Should we hire a consultant for the export, and what would they cover?
A consultant makes sense when the workspace count is high, sensitive variables are spread across teams, or several configurations depend on each other. DeployOpen plans, implements and documents open-source platform migrations inside your own infrastructure, and most engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts. A written scope should list the workspaces covered, the state and variable inventory, the test plan, the cutover steps and the handover documentation. Ask any provider to show how they will handle secret values, so that credentials never end up in a chat or a ticket.
What makes the export more expensive or slower?
Cost and effort rise with the number of things that must be recreated by hand. The main drivers are:
- Workspace count and how many distinct configurations they represent
- Sensitive variables that need a secrets owner to supply values
- Dependencies between workspaces, especially terraform_remote_state reads that must keep working after the move
- Private registry modules and providers that must be republished and their source addresses updated
- Number of VCS connections, teams and permission rules to rebuild
In a quote, ask for each of these counted separately, because they recur differently: state and code are largely one-time work, while the platform that runs afterward carries ongoing operating cost.
What should we check in every workspace before cancelling?
Do not cancel until each workspace has been verified on its new backend. For every workspace, confirm the state was downloaded and stored with restricted access, that a plan against the new backend shows no unexpected changes, that variables and sensitive values are recorded, and that any remote state readers still resolve. Keep the old state versions for an agreed retention period so you can recover if something was missed. OpenTofu's migration guidance follows the same pattern: back up state and code, install OpenTofu, initialize and verify the configuration, then test with a small change. Check the OpenTofu migration overview for the sequence and the warning about shared state.
How DeployOpen scopes an export and exit
DeployOpen treats the export as fixed-scope work. Before any workspace is touched, the scope, deliverables and timeline are agreed in writing. The first phase is an inventory: every organization, workspace, state version, variable set, VCS connection, team and private registry module, along with the configurations that read from each other. Dependencies matter most. A workspace that consumes another workspace's outputs through the terraform_remote_state data source needs its consumers and producers moved together, and the inventory is where that ordering is decided.
The second phase covers the data itself and the evidence that proves it moved intact. State is pulled through the state versions API, and each downloaded file is compared against the source so the team can show which version was taken and when. Variables, workspace settings and access rules are documented by hand, because several of these objects have no export and must be re-created in Terrakube or Atlantis. The cutover plan records what was re-created, who approved it and how the old workspace is kept read-only until the new one has run a clean plan. Confirm with your own team which audit records your compliance program needs to retain from HCP Terraform before that work starts.
DeployOpen can support the cutover itself, including switching the cloud block or remote backend, moving the CLI to OpenTofu where that is the chosen path, and running a controlled test change in each workspace. DeployOpen prepares systems, controls and evidence, but independent auditors and certification bodies issue any audit report or attestation. Ongoing support, upgrades and continuous testing are available as a retainer after cutover. DeployOpen does not publish a price list, so a quote follows from the written scope. Ask for the inventory deliverable to be priced separately from the cutover, so you can decide how far to take the engagement once the scale of the workspace estate is known.
