Migrating State Files Between Terraform Cloud Workspaces

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.