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
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
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.
