Migrating state files from one Terraform Cloud workspace to another can be crucial for various operational reasons such as reorganizing your infrastructure, renaming workspaces, or consolidating environments. Here’s a step-by-step guide to help you through the process.

Prerequisites

• Terraform CLI installed on your local machine.

• Access to Terraform Cloud.

• GitHub repository for your Terraform configuration.

Step-by-Step Migration Process

Step 1: Log in to Terraform

First, you need to log in to Terraform Cloud from your CLI. Run the following command and follow the prompts to authenticate:

terraform login

Step 2: Log in to GitHub

Ensure you're authenticated with GitHub if your Terraform configuration is stored in a private repository. You can use git commands to authenticate if needed:

git config --global credential.helper cache

This will cache your credentials for some time and allow you to pull changes from your GitHub repository.

Step 3: Clone or Pull the Repository

Navigate to your local repository or clone it if you haven’t done so already:

git clone https://github.com/your-repo/your-terraform-config.git
cd your-terraform-config

Step 4: Initialize Terraform

Initialize your Terraform configuration:

terraform init

This command will set up the necessary backend configurations and download provider plugins.

Step 5: Pull the Current State

Pull the state file from your current Terraform Cloud workspace:

terraform state pull > terraform.tfstate

Step 6: Convert Line Endings (Windows Only)

If you're on Windows, you need to convert the line endings of the state file to Unix-style to avoid issues with terraform state mv commands. Use the following PowerShell command to do this:

((Get-Content .\terraform.tfstate) -join "`n") + "`n" | Set-Content -NoNewline .\terraform.tfstate

This command reads the file, joins the content with Unix-style line endings, and writes it back.

Step 7: Update providers.tf to Change Workspace Name

Update your providers.tf or equivalent configuration file to point to the new Terraform Cloud workspace. For example, change:

terraform {
  backend "remote" {
    organization = "your-organization"
    workspaces {
      name = "old-workspace"
    }
  }
}

to:

terraform {
  backend "remote" {
    organization = "your-organization"
    workspaces {
      name = "new-workspace"
    }
  }
}

Step 8: Push the State to the New Workspace

Now, push the modified state file to the new Terraform Cloud workspace:

terraform state push terraform.tfstate

Step 9: All Done

At this point, your state file should be successfully migrated to the new workspace. You can verify by running:

terraform plan

This will show you the current state and any differences detected.

Summary

Migrating Terraform state files between workspaces involves a series of steps to ensure the state is accurately moved and updated. By following this guide, you ensure a smooth transition and maintain the integrity of your infrastructure's state.

• Authenticate with Terraform Cloud and GitHub.

• Initialize your configuration.

• Pull the current state and convert line endings if on Windows.

• Update your workspace name in providers.tf.

• Push the state file to the new workspace.

By carefully following these steps, you can confidently migrate your Terraform state files between workspaces.