April 6 & 7
Learn about Vault, Consul, & more at HashiDays Sydney in Australia Register Now

Terraform Cloud


If you already use Terraform to manage infrastructure, you're probably managing some infrastructure that you want to transfer to Terraform Cloud (TFC). By migrating your Terraform state to TFC, you can hand off infrastructure without de-provisioning anything.

Step 1: Gather Credentials, Data, and Code

Make sure you have all of the following:

  • The location of the VCS repository for the Terraform configuration in question.

  • A local working copy of the Terraform configuration in question.

  • The existing state data. The location of the state depends on which backend you've been using:

    • If you were using the default local backend, your state is a file on disk. You need the original working directory where you've been running Terraform, or a copy of the terraform.tfstate file to copy into a fresh working directory.
    • For remote backends, you need the path to the particular storage being used (usually already included in the configuration) and access credentials (which you usually must set as an environment variable).
  • A TFC user account which is a member of your organization's owners team, so you can create workspaces.

  • A [user API token][user-token] for your TFC user account. (Organization and team tokens will not work; the token must be associated with an individual user.)

    In your shell, set an ATLAS_TOKEN environment variable with your API token as the value.


Step 2: Create a New TFC Workspace

Create a new workspace in your TFC organization to take over management of this infrastructure. Set the VCS repository and any necessary variable values appropriately. You can set team access permissions now or later, whichever is more convenient.

Do not perform any runs in this workspace yet, and consider locking the workspace to be sure. If an apply happens prematurely, you'll need to destroy the workspace and start the process over.

Step 3: Stop Terraform Runs

However you currently run Terraform to manage this infrastructure, stop. Let any current runs finish, then make sure there won't be more.

This might involve locking or deleting CI jobs, restricting access to the state backend, or just communicating very clearly with your colleagues.

Step 4: Prepare Your Terraform Working Directory

In your shell, go to the directory with the Terraform configuration you're migrating.

  • If you've already been doing Terraform runs in this directory, you should be ready to go.
  • If you had to retrieve a terraform.tfstate file from elsewhere, copy it into the root of the working directory and run terraform init.
  • If you use a remote backend and had to check out a fresh working directory from version control, run terraform init.

Step 5: Edit the Backend Configuration

If the Terraform configuration has an existing backend block, delete it now.

Add a terraform { backend ... block to the configuration.

terraform {
  backend "atlas" {
    name = "<TFC ORG>/<WORKSPACE NAME>"
    address = "https://<TFC HOSTNAME>"
  • Use the atlas backend. (This is TFC's backend; the Atlas name is used here for historical reasons.)
  • In the name attribute, specify the name of your TFC organization and the target workspace, separated by a slash. (For example, example_corp/database-prod.)
  • The address attribute is only necessary with private Terraform Enterprise instances. You can omit it if you're using the Paid Tier of TFC.

Step 6: Run terraform init and Answer "Yes"

Run terraform init.

The init command will notice that your new TFC workspace doesn't have any state, and will offer to migrate the previous state to it. The prompt usually looks like this:

Do you want to copy existing state to the new backend?
  Pre-existing state was found while migrating the previous "local" backend to the
  newly configured "atlas" backend. No existing state was found in the newly
  configured "atlas" backend. Do you want to copy this state to the new "atlas"
  backend? Enter "yes" to copy and "no" to start with an empty state.

Answer "yes," and Terraform will migrate your state.

After the init has finished, you can delete the temporary atlas backend block.

Step 7: Enable Runs in the New Workspace

In TFC, unlock the new workspace and queue a plan. Examine the results.

If all went well, the plan should result in no changes or very small changes. TFC can now take over all Terraform runs for this infrastructure.


  • If the plan would create an entirely new set of infrastructure resources, you probably have the wrong state file.

    In the case of a wrong state file, you can recover by fixing your local working directory and trying again. You'll need to re-set to the local backend, run terraform init, replace the state file with the correct one, change back to the atlas backend, run terraform init again, and confirm that you want to replace the remote state with the current local state.

  • If the plan recognizes the existing resources but would make unexpected changes, check whether the designated VCS branch for the workspace is the same branch you've been running Terraform on, and update it, if it is not. You can also check whether variables in the TFC workspace have the correct values.