Terraform: Move State Between Workspaces?

Introduction
Step-by-Step Guide
Code Example
Additional Notes
Summary
Conclusion
References

Introduction

This guide outlines the steps to move your Terraform state and resources to a new workspace. This process is particularly useful when you want to restructure your project or isolate resources for different environments.

Step-by-Step Guide

Create a local backup of your Terraform state:
```
terraform state pull > default.tfstate
```
This will save the current state of your default workspace to a file named default.tfstate.
Switch to using a local backend:
- Comment out the backend block in your Terraform configuration file. This will temporarily disable the remote backend and make Terraform use a local backend.
Initialize Terraform with state migration:
```
terraform init -migrate-state
```
This command initializes Terraform and migrates the state from the previously configured backend to the local backend.
Verify the local state:
```
terraform state list
```
This command should list all the resources managed by Terraform in the local state.
Create a new workspace (if needed):
```
terraform workspace new <new_workspace_name>
```
Replace <new_workspace_name> with the desired name for your new workspace.

Switch to the new workspace:

terraform workspace select <new_workspace_name>

Initialize Terraform in the new workspace:
```
terraform init
```
This will initialize Terraform in the new workspace and create an empty state file.
Import the resources from the local state:
- For each resource you want to move, use the terraform import command:
```
terraform import <resource_type>.<resource_name> <resource_id>
```
  - Replace <resource_type> with the type of resource (e.g., aws_instance).
  - Replace <resource_name> with the name of the resource in your Terraform configuration.
  - Replace <resource_id> with the actual ID of the resource in your cloud provider.
Verify the state in the new workspace:
```
terraform state list
```
This should now list all the imported resources in the new workspace.
(Optional) Clean up the default workspace:

If you no longer need the resources in the default workspace, you can delete them using terraform destroy.
You can also delete the default workspace itself using terraform workspace delete default.

(Optional) Switch back to using a remote backend:

Uncomment the backend block in your Terraform configuration file.
Run terraform init to reinitialize Terraform with the remote backend.

(Optional) Migrate the state to the remote backend:

Follow the instructions provided by your remote backend provider to migrate the local state to the remote backend.

Code Example

This code provides a step-by-step guide for migrating Terraform resources from a default workspace with a remote backend to a new workspace with a local backend. It involves backing up the state, commenting out the backend configuration, initializing Terraform with state migration, creating a new workspace, importing resources from the local state, and optionally cleaning up the default workspace and switching back to the remote backend. The code includes commands for each step and emphasizes the importance of backing up state, using correct resource IDs, and consulting provider documentation.

This example demonstrates migrating resources from a "default" workspace with a remote backend to a new workspace named "development" using a local backend temporarily.

Assumptions:

You have a Terraform project with a remote backend configured.
You want to move all resources to a new workspace.

Steps:

Backup your Terraform state:
```
terraform state pull > default.tfstate
```
Comment out the backend block in your Terraform configuration file (e.g., main.tf).
Initialize Terraform with state migration:
```
terraform init -migrate-state
```
Verify the local state:
```
terraform state list
```
Create the new workspace:
```
terraform workspace new development
```
Switch to the new workspace:
```
terraform workspace select development
```
Initialize Terraform in the new workspace:
```
terraform init
```

Import resources from the local state:

Important: Replace placeholders with your actual resource types, names, and IDs.

# Example for an AWS instance
terraform import aws_instance.example i-0123456789abcdef0

# Repeat for each resource you want to move

Verify the state in the new workspace:
```
terraform state list
```
(Optional) Clean up the default workspace:

terraform workspace select default
terraform destroy -auto-approve
terraform workspace delete default

(Optional) Switch back to the remote backend:

Uncomment the backend block in your Terraform configuration file.
Run terraform init to reinitialize Terraform with the remote backend.

(Optional) Migrate the state to the remote backend:

Consult your remote backend provider's documentation for specific instructions.

Important Notes:

This example assumes you want to move all resources. You can selectively import specific resources if needed.
Ensure you have the correct resource IDs before importing.
Back up your state regularly, especially before and after significant changes.
This process might differ slightly depending on your chosen backend and cloud provider. Always refer to their documentation for specific instructions.

Additional Notes

Resource Dependencies: Be mindful of resource dependencies when importing. If resource "A" depends on resource "B", ensure you import "B" before "A".
Partial Migrations: You can choose to migrate only specific resources to the new workspace, leaving others in the original workspace.
State Locking: If your backend supports state locking (like S3), consider disabling it temporarily during the migration to avoid conflicts. Re-enable it after the migration is complete.
Remote Backend Migration: The process for migrating state to a remote backend varies depending on the provider. Refer to the provider's documentation for detailed instructions.
Terraform Version Compatibility: Ensure that the Terraform version used for the migration is compatible with both the source and destination backends.
Testing: After migrating, thoroughly test your infrastructure in the new workspace to ensure everything functions as expected.
Documentation: Document the migration process, including any specific steps or challenges encountered, for future reference.
Alternative Approach: Instead of migrating the entire state, you can also create a new Terraform configuration for the new workspace and manually provision the resources. This approach might be preferable for complex migrations or when starting fresh in a new environment.
Destroy with Caution: Be extremely cautious when using terraform destroy, especially in the default workspace. Ensure you have a backup of your state and understand the potential impact before deleting any resources.

Summary

This guide summarizes the steps to move your Terraform resources to a new workspace, with the option to also switch to a new backend.

1. Backup and Localize:

Create a local backup of your current Terraform state: terraform state pull > default.tfstate
Temporarily disable the remote backend by commenting out the backend block in your configuration.
Initialize Terraform and migrate the state to your local machine: terraform init -migrate-state
Verify the local state: terraform state list

2. Create and Populate the New Workspace:

Create a new workspace: terraform workspace new <new_workspace_name>
Switch to the new workspace: terraform workspace select <new_workspace_name>
Initialize Terraform in the new workspace: terraform init
Import each resource from the local state into the new workspace: terraform import <resource_type>.<resource_name> <resource_id>
Verify the state in the new workspace: terraform state list

3. Optional Cleanup and Backend Switch:

Clean up the default workspace (optional):
- Delete resources: terraform destroy
- Delete the workspace: terraform workspace delete default
Switch back to a remote backend (optional):
- Uncomment the backend block in your configuration.
- Reinitialize Terraform: terraform init
- Migrate the state to the remote backend following your provider's instructions.

This process allows you to safely move your Terraform resources to a new workspace, providing a clean slate for your infrastructure management.

Conclusion

By following these steps, you can effectively move your Terraform state and resources to a new workspace, enabling better project organization and environment separation. Remember to adapt the commands and procedures to your specific cloud provider and backend configuration, and always prioritize backing up your state before making any significant changes.

References

Moving resources from the default workspace to a new one on ... | If you started to use terraform as you learning it or were managing just one environment and now need to have multiple environments chances are you will need to move your resources from the default workspace to another one with a better name for each environment.
moving specific resources between workspaces : r/Terraform | Posted by u/co11egestuff - 2 votes and 3 comments
Way to move resources from one state to another. · Issue #32777 ... | Terraform Version any Use Cases Consider the problem of splitting up a monolithic terraform configuration into smaller root modules. This requires either splitting up the existing state, or tearing...
Migrate your Terraform State to Workspaces | by Andris Roling ... | When starting with Terraform most of you will most likely create your own local Terraform state. I will explain how to improve local state…
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.terraf...
How To Terraform Migrate State from One Workspace to Another ... | Need a Terraform migrate state from one workplace to another? Follow these easy steps to successfully migrate your state files.
How to change the name of a workspace - Terraform - HashiCorp ... | Hi all I have made a terrible choice naming my workspace, and would like to move all resources in it to a workspace with a better name. Is there a short way of doing this? My backend is S3, there is no state locking. I have considered, but not actually done, the following: backup the state (terraform state pull) – then what? import using legacy method? import resources the hard way 💀 ← I really don’t want to do that. What are you state ninjas doing when you need to move resources to ...
State: Workspaces | Terraform | HashiCorp Developer | The configuration still has only one backend, but you can deploy multiple distinct instances of that configuration without configuring a new backend or changing ...
How to Migrate Terraform State Between Different Backends | Migrate your Terraform state to a remote backend like Azure Storage Account or Amazon S3 and back to local. Init reconfigure vs migrate-state.