# 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:

```plaintext
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:

```plaintext
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:

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

### **Step 4: Initialize Terraform**

Initialize your Terraform configuration:

```plaintext
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:

```plaintext
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:

```plaintext
((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`](http://providers.tf) to Change Workspace Name

Update your [`providers.tf`](http://providers.tf) or equivalent configuration file to point to the new Terraform Cloud workspace. For example, change:

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

to:

```plaintext
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:

```plaintext
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:

```plaintext
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`](http://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.