First time at Zeet?

2 Apr
min read

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.

Jack Dwyer

Platform Engineering + DevOps

Share this article

If you're wondering what Terraform Migrate State is and how it can help you, you're in the right place! Whether you're new to Terraform or a seasoned user, you can benefit from learning more about Terraform Migrate State. By understanding what is Terraform Migrate State, you can efficiently manage infrastructure changes and updates, ensuring your projects run smoothly. Let's take a closer look at what Terraform Migrate State is and how you can use it in your projects.

Understanding Terraform State

An illustration of changing Terraform Migrate State

Terraform state is a crucial aspect of managing infrastructure as code with Terraform. It keeps track of the resources that Terraform manages and their current state. Terraform uses this state to create plans and make changes to infrastructure. Terraform must store state about your managed infrastructure and configuration. This state is used by Terraform to map real-world resources to your configuration, keep track of metadata, and to improve performance for large infrastructures. 

The Importance of Terraform Migrate State

Migrating Terraform State can be beneficial for various reasons. One common use case for migrating state between workspaces is when transitioning resources from one environment to another. This could be necessary when moving resources from a staging workspace to a production workspace, for example. Another common use case is when consolidating resources from multiple workspaces into a single workspace. 

The Concept of Migrating Terraform State Between Workspaces

The process of migrating the Terraform state file from one workspace to another is straightforward and involves two primary steps. The state file must be moved to the target workspace, and second, the state file must be updated in the Terraform configuration to reference the new location. By following these steps, the resources managed by the state file are effectively moved from one workspace to another, enabling you to manage them together with other resources in the target workspace.

Related Reading

Reasons for Migrating State Between Workspaces

junior devs in a meeting with lead dev - Terraform Migrate State

Reasons for Terraform State Migration

Enhanced Organization

Migrating state between workspaces allows for better organization of infrastructure resources. It enables users to segregate resources based on environments or configurations, leading to a more structured and manageable setup.

Improved Security

By moving state files between workspaces, users can enhance security by restricting access to specific environments. This segregation helps in controlling who can modify resources in different workspaces, reducing the risk of unauthorized changes.

Simplified Management

Migrating state between workspaces simplifies the management of infrastructure resources. It streamlines the process of updating, tracking, and maintaining resources by providing a clear separation between different environments or projects.

Scenarios Requiring State Migration

Environment Segregation

When managing multiple environments such as development, staging, and production, migrating state between workspaces helps in isolating resources specific to each environment. This segregation ensures that changes made in one environment do not impact others.

Project Isolation

In scenarios where different projects or teams are working on distinct sets of resources, migrating state between workspaces allows for project isolation. Each project can have its dedicated workspace, facilitating independent management and updates.

Resource Reorganization

When restructuring infrastructure resources or redefining configurations, migrating state between workspaces is essential. It enables users to reorganize resources efficiently without affecting the existing setup, ensuring a smooth transition.

Benefits of Separate Workspaces for Different Environments

Isolation of Changes

Separate workspaces for different environments prevent changes made in one environment from affecting others. This isolation ensures that modifications and updates are contained within the intended environment, reducing the risk of errors.

Enhanced Collaboration

Maintaining separate workspaces facilitates collaboration among team members working on different environments or projects. It allows teams to work independently on their resources while ensuring a cohesive infrastructure setup.

Efficient Resource Management

By using separate workspaces, users can manage resources more efficiently. It provides a clear delineation between environments, making it easier to track changes, troubleshoot issues, and maintain consistency across different setups.

Zeet Terraform and Helm Product Overview

How To Prepare for Terraform State Migrate

man prepared for Terraform Migrate State

Steps to take before initiating the state migration process

1. Ensure that all necessary permissions and credentials are in place for both the source and destination workspaces.

2. Verify that the Terraform configurations, variables, and settings are consistent between the original and destination workspaces.

3. Download the same version of Terraform used in both organizations to ensure compatibility during the migration process.

4. Create a file for the original organization locally, ensuring not to commit this file to version control.

5. Log in to the Terraform API from the command line using Terraform login and follow the prompts to authenticate with the user API token.

Considerations for ensuring a smooth transition between workspaces

  • Confirm that the hostname attribute in the file is set to the appropriate Terraform Cloud or Terraform Enterprise URL.
  • Establish communication between the original and destination organizations by running Terraform init to ensure a seamless transition.
  • Verify the existence of the destination organization and workspace; create them if they do not already exist before proceeding with the migration.
  • Modify the file to point to the destination organization and workspace to facilitate the migration process effectively.
  • Execute Terraform init -migrate-state to trigger communication with the destination organization and prompt the copying of the state file to the new workspace.
  • Check the destination organization workspace for the new state file and ensure that the migration was successful.

Optimize Cloud and Kubernetes Investments with Zeet

Zeet helps you to get more from your cloud, Kubernetes, and Terraform investments and helps your engineering team become strong individual contributors through our CI/CD & deployment platform. 

Contact Zeet to learn more about how Zeet helps you get seamless cloud deployments every time, and helps your team to become a top-performing engineering team.

Executing Terraform Migrate State

implementation of Terraform Migrate State

Ensure a Smooth Migration of Terraform State with These Steps

Update Backend Configuration

Begin by updating the backend configuration in your Terraform files to point to the new workspace where you want to migrate the state.

Initialize Terraform

Run Terraform init with the -migrate-state flag to initiate the state migration process. This command will prompt Terraform to communicate with the new workspace.

Confirm Migration

Verify that Terraform has successfully migrated the state file to the new workspace by checking the state file location in the destination workspace.

Test Infrastructure Changes

Make a minor change to your infrastructure configuration and apply it using Terraform apply to ensure that the new workspace is correctly managing the state.

Command and Best Practices for a Successful Migration

Terraform init -migrate-state

This command initializes Terraform and triggers the state migration process from the current workspace to the specified destination workspace.

Terraform state pull

Use this command to pull the current state from the source workspace before migrating it to the new workspace. This can help in troubleshooting any issues during the migration process.

Backup State Files

Before initiating the migration, it is advisable to create backups of the state files to prevent data loss in case of any unexpected issues during the migration.

Version Control

Ensure that your Terraform configurations are under version control to track changes and revert to previous states if needed.


Communicate with team members or stakeholders about the state migration process to avoid conflicts and ensure everyone is aware of the changes.

Get More From Your Cloud, Kubernetes, and Terraform Investments with Zeet

Zeet helps you to get more from your cloud, Kubernetes, and Terraform investments and helps your engineering team become strong individual contributors through our CI/CD & deployment platform. 

Contact Zeet to learn more about how Zeet helps you get seamless cloud deployments every time, and helps your team to become a top-performing engineering team.

Related Reading

Verifying the State Migration

team doing resource validation - Terraform Migrate State

Resource Validation

It's crucial to validate that all resources from the original workspace are present and correctly configured in the new workspace. This step ensures that nothing was left behind or omitted during the migration process.

To check for resource validation, users can run Terraform plan to verify that all resources are correctly configured according to the desired state. This effectively confirms that the resources have been successfully migrated to the new workspace without any loss or misconfiguration.

Error Handling

During the migration process, it's essential to monitor for any error messages or warnings that may arise. Addressing these promptly is crucial to prevent any issues post-migration. By keeping a keen eye on potential errors and warnings and resolving them as they occur, users can ensure a smooth migration process without any lingering issues that could affect the integrity of the infrastructure resources.

State Consistency

Ensuring that the state file in the new workspace accurately reflects the desired state of the infrastructure resources is key to a successful migration process. Any discrepancies between the desired state and the actual state of the resources can lead to unexpected behavior and issues down the line. 

By double-checking the state file's consistency and cross-referencing it with the desired state, users can confirm that the migration was completed successfully and that the new workspace is managing the resources accurately and efficiently.

Best Practices and Tips for Optimizing State Management in Terraform

Recommendations for Optimizing State Management in Terraform

1. Use Multiple State Files

When working with Terraform, consider using multiple state files to logically separate resources and give them their own state file. This approach helps in organizing and managing infrastructure components more effectively. 

By assigning distinct state files to different sets of resources, it becomes easier to work with specific parts of the infrastructure without having to traverse through a single, large state file.

2. Remote State Storage

Storing state files remotely ensures data integrity and accessibility. Remote state storage provides a centralized location for managing state files and facilitates collaboration among team members. 

By storing state files in a remote location, the risk of data loss or corruption is significantly reduced, and it becomes easier for team members to work on infrastructure configurations collectively.

3. Isolate State Files

Isolating state files for different environments helps prevent conflicts and ensures that changes made in one environment do not impact others. By segregating state files based on environments, it is easier to maintain the stability and consistency of infrastructure configurations. This approach also allows for maintaining separate configurations for development, testing, and production environments.

4. Leverage Terraform_remote_state

Utilize the Terraform_remote_state data source to reference outputs from state files. This allows for seamless integration of outputs from different configurations stored in separate state files. By leveraging Terraform_remote_state, resources can access outputs from other state files, enabling cross-referencing among different configurations.

5. Maintain Consistency

Ensure consistency in state management practices across different workspaces to avoid discrepancies and errors. Consistent naming conventions, version control, and documentation can help in maintaining a standardized approach to state management. By enforcing uniform practices across different workspaces, it becomes easier to manage state files and ensure a smooth workflow.

Tips for Maintaining Consistency and Efficiency when Migrating State between Workspaces

Plan Ahead

Before initiating the state migration process, carefully plan and document the steps involved to ensure a smooth transition between workspaces. By laying out a clear migration plan, potential challenges can be anticipated and mitigated beforehand.

Verify State Integrity

After migrating the state, verify the integrity of the state file by checking for any discrepancies or missing resources. Testing infrastructure changes post-migration can help confirm that the state has been migrated successfully without compromising any resources.

Backup State Files

Always create backups of state files before migrating to mitigate the risk of data loss or corruption during the migration process. By creating backups, you can always revert to the original state in case of any unforeseen issues during the migration.

Follow Terraform Best Practices

Adhere to Terraform best practices and recommended workflows when migrating state between workspaces to maintain consistency, efficiency, and data integrity. By following established best practices, you can ensure a structured and reliable state migration process.

How Can You Ensure That the Migrated Terraform State Is Compatible With the Target Environment

checking the compatibility of a resource - Terraform Migrate State

Verify Terraform CLI Version

Make sure the Terraform CLI version aligns with the target workspace. Consistent versions ensure the state file compatibility with the new environment.

Reinitialize Configuration

After migrating the state to Terraform Cloud, reinitialize configuration to update the backend. This step allows Terraform to detect the updated backend and confirm the migration of the state file to Terraform Cloud. It ensures alignment with the new environment.

Test Infrastructure Changes

Run Terraform plan to preview potential changes required for your infrastructure post-migration. Testing infrastructure changes after migration ensures that the state accurately reflects the desired configuration in the target environment.

Related Reading

Zeet Contact Us

Get Control of Your Releases With Zeet's CI/CD & Deployment Platform for Kubernetes and Terraform

Zeet helps you to get more from your cloud, Kubernetes, and Terraform investments and helps your engineering team become strong individual contributors through our CI/CD & deployment platform. 

Contact Zeet to learn more about how Zeet helps you get seamless cloud deployments every time, and helps your team to become a top-performing engineering team.

Subscribe to Changelog newsletter

Jack from the Zeet team shares DevOps & SRE learnings, top articles, and new Zeet features in a twice-a-month newsletter.

Thank you!

Your submission has been processed
Oops! Something went wrong while submitting the form.