Migrate Workspace State Using Terraform Backend Configuration

Use Case

If you need to migrate a workspace to a different organization

Procedure

Please note you’ll need a user API token that has sufficient permissions in both organizations. (https://app.terraform.io/app/<your organization>/settings/authentication-tokens) for cloud or (https://<tfe-url>/app/<your organization>/settings/authentication-tokens)

Ensure that all of the settings (VCS, variables, SSH keys, Terraform version, etc) are the same in both the Original and Destination Organizations workspaces.

NOTE: The hostname attribute should be set to either Terraform Cloud such as app.terraform.io or Terraform Enterprise <tfe-hostname>.

1. Download the same version of terraform used in the Organizations/workspaces locally
2. Locally, create a backend.tf file of the origin Organization * Do not commit this to your VCS repository.*

terraform {
  backend "remote" {    
    hostname = “”
    organization = "<Originating Organization name>"

    workspaces {
      name = "<Originating workspace name>"
    }
  }
}

3. From a command prompt where the backend.tf exists, log in into Terraform API from the command line by issuing terraform login
4. Follow the instructions of the prompts, the second one will require the user API token
5. Run the command terraform init to begin establishing communications between the Organizations
6. Ensure the Destination Organization and Workspace exists and if not create them prior to continuing to step 7
7. Modify the backend.tf to point to the Destination Organization:

terraform {
  backend "remote" {    
    hostname = “” 
    organization = "<Destination Organization name>"

    workspaces {
      name = "<Destination workspace name>"
    }
  }
}

8. Execute $terraform init -migrate-state to trigger the communication with the Destination Organization. Terraform should prompt to copy the state file to the new Organization workspace. Enter yes.
9. Check the Destination Organization workspace for the new state file
10. If there is no prompt to move the state file rename the state file to statefile.json
11. Run terraform state push /path/to/statefile.json
12. Check the Destination Organization workspace for the new state file