Documentation · Infrastructure runs

Taking your state with you

Download your state, move a workspace to another backend, and what happens to your runs and state versions when you delete them or close the organisation.

How to get your state out, how to point a configuration at another backend, and what happens to what you leave behind. You can do all of it yourself, at any time, including while new runs are paused over a bill.

There are two ways, and both give you an ordinary state file that OpenTofu and Terraform read with no conversion.

• From the dashboard. Open the workspace from Terraform in the dashboard, then its State tab. Every version has a Download link; the newest is marked current. The tab lists the newest 50 versions. If you use two-factor authentication, the download asks for your code unless you entered one in the last fifteen minutes.

• From the CLI. In a working directory whose cloud block names the workspace, terraform state pull (or tofu state pull) prints the current state.

terraform state pull > terraform.tfstate

Downloading state does not depend on your bill. It works while new runs are paused for an unpaid invoice or a missing card: a billing problem never stops you reading back what is yours.

Do one workspace at a time, so nothing changes its state while you move it.

1. Let any run in the workspace finish, or discard it, including one waiting for somebody to confirm its apply, and cancel any queued behind it. A run holds the workspace's lock from the moment it is queued until it is done, so while one does, the page shows the workspace as locked and offers no Lock workspace button. Once no run holds it, an owner or an admin presses Lock workspace. A run started after that waits until the workspace is unlocked; only a plan-only run, which cannot change state, still goes ahead.

2. Pull the current state, as above, into terraform.tfstate.

3. Replace the cloud block with the backend you are moving to, or remove it to keep state in a local file.

4. Run terraform init -reconfigure. It sets up the new backend without trying to copy state out of the old one, which you have already done.

5. For a backend other than a local file, run terraform state push terraform.tfstate. A local backend reads the file where it already is.

6. Run terraform plan. If the state moved intact, and nothing has been changed outside Terraform since the last apply, it reports no changes.

Leave the workspace locked here, so nothing runs against the old copy by mistake.

• Closing your organisation deletes nothing. Your workspaces, their state and every run's output are kept. Members and roles says how an owner closes one.

• A run's output is kept until you delete it. It goes with the run, or with the workspace it ran in. Nothing deletes it by age.

• A deleted state version can be restored for 30 days. After that it is deleted for good. The State tab lists it under Recently deleted with the time it has left, and Restore brings it back. The version a workspace is currently using cannot be deleted at all.

• Deleting a workspace deletes its state at once, with every version of it, and there is no 30-day window for that. Download what you need first.

• Deleted data lingers in our backups for a short while. Our privacy policy says for how long.

Deleting a state version or a workspace is done through the Terraform API with an API token.