--- title: "How to Migrate Existing Terraform State into Terraform Cloud" description: "Learn how to migrate your existing Terraform state files into Terraform Cloud, and never worry about losing changes in your state file in this step-by-step tutorial!" canonical: "https://adamtheautomator.com/terraform-state/" --- # How to Migrate Existing Terraform State into Terraform Cloud > Learn how to migrate your existing Terraform state files into Terraform Cloud, and never worry about losing changes in your state file in this step-by-step tutorial! Source: https://adamtheautomator.com/terraform-state/ --- ATA Learning Tap to hide [ ATA Learning ](/) * [Home](/) * [Tutorials](/tutorials/) * [Instructors](/author/) * [Advertising](/advertising/) * [Recommended Resources](/resources/) * [About Adam](/about-adam/) Search for: * [](https://twitter.com/adbertram) * [](https://github.com/Adam-the-Automator) * [](https://www.linkedin.com/company/adam-the-automator-llc) * [](/feed/) ![How to Migrate Existing Terraform State into Terraform Cloud](https://adamtheautomator.com/wp-content/uploads/2022/01/How-to-Migrate-Existing-Terraform-State-into-Terraform-Cloud.jpg) # How to Migrate Existing Terraform State into Terraform Cloud [![](https://secure.gravatar.com/avatar/2788bb1a3f735603f81eca51d68daec56a9d97e805a10268fb2c20afcc76b81b?s=192&d=mm&r=g)Nicholas Xuan Nguyen](https://adamtheautomator.com/author/nicholas-xuan-nguyen/)26 January 20228 min. read Categories: [IT Ops](/category/it-ops/) Tags:[AWS](/tag/aws/)[Terraform](/tag/terraform/) Table of Contents * [Prerequisites](#prerequisites) * [Setting up a Local Environment](#setting-up-a-local-environment) * [Setting up a Terraform Cloud Environment](#setting-up-a-terraform-cloud-environment) * [Setting up a Terraform Cloud Backend](#setting-up-a-terraform-cloud-backend) * [Applying the Backend Configuration](#applying-the-backend-configuration) * [Conclusion](#conclusion) Managing Terraform state files manually, especially migrating between on-premise and cloud-based environments can be a huge pain. But lucky for you, [Terraform Cloud](https://cloud.hashicorp.com/products/terraform) can solve this problem. Terraform Cloud lets you manage your Terraform state file in the cloud, so the changes in your infrastructure are tracked and can be viewed in the web-based user interface. In this tutorial, you’ll learn how to migrate your existing Terraform state file into Terraform Cloud. Doing so lets you manage your state file on your local machine and use Terraform Cloud to access it seamlessly. Get your hands dirty and jump right in! ## Prerequisites This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have the following: * A [Terraform Cloud account](https://learn.hashicorp.com/tutorials/terraform/cloud-sign-up). * An EC2 instance with [Terraform installed](https://learn.hashicorp.com/tutorials/terraform/install-cli). Related:[How to Install Terraform on Linux and Windows](https://adamtheautomator.com/install-terraform/) * An [Admin user](https://www.techrepublic.com/article/how-to-create-an-administrator-iam-user-and-group-in-aws/) with admin privileges. * AWS CLI [installed](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [configured](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) on the EC2 instance. * A Linux machine – This demo uses Amazon Linux 2, but any Linux distribution will work. Related:[How to Install Ubuntu 20.04 \[Step-by-Step\]](https://adamtheautomator.com/install-ubuntu/) ## Setting up a Local Environment Kick-off this tutorial by setting up a local environment. Why? You will want to maintain your local state file and not depend on Terraform Cloud all the time. With a local environment set up, you can revert to your local state file for testing or if you’re not connected to the Internet. 1\. SSH into your EC2 instance, open your terminal and run the [`yum`](https://www.linuxfordevices.com/tutorials/centos/yum-command) command below to install [`git`](https://www.atlassian.com/git/tutorials/what-is-git) on your system. You will later use Git to clone the main Terraform Cloud Git repo. ```bash sudo yum install git -y ``` ![installing git on your system](https://adamtheautomator.com/wp-content/uploads/2022/01/image-310.png) installing git on your system 2\. Next, run the `git clone` command below to clone the Terraform cloud repository to your current directory. ```bash sudo git clone https://github.com/Adam-the-Automator/terraform-state.git ``` ![Cloning the Terraform cloud repository](https://adamtheautomator.com/wp-content/uploads/2022/01/image-311.png) Cloning the Terraform cloud repository 3\. Run the `ls` command to list files and directories in the current directory. ```bash ls ``` As you see below, you have a new directory called _migrate-state_. This directory will be the directory you use to follow this tutorial. ![listing all the new directory](https://adamtheautomator.com/wp-content/uploads/2022/01/image-312.png) listing all the new directory 4\. Now, run the following commands to switch (`cd`) to `migrate-state` directory and list (`ls`) all the files and directories. ```bash cd migrate-state && ls ``` Below, you can see that this directory contains a _main.tf file._ All Terraform projects have a _main.tf_ file, which is the entry point to your infrastructure. So, when you run `terraform apply`, the Terraform engine runs the code in this file. ![Previewing the migrate-state directory](https://adamtheautomator.com/wp-content/uploads/2022/01/image-313.png) Previewing the migrate-state directory 5\. Open the _main.tf_ in your favorite text editor. Change the highlighted value below with your EC2 instance’s [ami](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html) and [subnet\_id](https://docs.aws.amazon.com/managedservices/latest/userguide/find-subnet.html), then save the changes and close the editor. ![Replacing your on resources](https://adamtheautomator.com/wp-content/uploads/2022/01/image-314.png) Replacing your on resources 6\. Now run the [`terraform init`](https://www.terraform.io/cli/commands/init) command to initialize your working directory. This command reads all the files in the current directory, determines which are Terraform configuration files, and translates them into a dependency graph. `sudo terraform init` ```bash sudo terraform init ``` > _You can repeatedly run the `terraform init` command without any harm to pull changes from the configuration files._ ![Initializing your working directory](https://adamtheautomator.com/wp-content/uploads/2022/01/image-315.png) Initializing your working directory Finally, run the [`terraform apply`](https://www.terraform.io/cli/commands/apply) command below to apply your changes to the working directory. Type **Y** and press **Enter** when prompted. You will run this command every time you make a change and wish to push your changes to the cloud. `terraform apply` ```bash terraform apply ``` ![Applying changes](https://adamtheautomator.com/wp-content/uploads/2022/01/image-316.png) Applying changes ## Setting up a Terraform Cloud Environment Now that your local environment is ready, it’s time to set up your Terraform Cloud environment. Setting up a Terraform Cloud Environment enables you to access the remote state storage and sync it with various providers and your local state files. 1\. Open your preferred web browser and log in to the AWS IAM dashboard with your Admin user account. Click on the **Users** menu at the left panel and click on your admin account from the list of users to access the account’s information. The admin account is named **cloud\_user for this demo**, as shown below. Related:[Learning Identity and Access Management (IAM) AWS Through Examples](https://adamtheautomator.com/iam-aws/) ![Accessing Admin Account Information](https://adamtheautomator.com/wp-content/uploads/2022/01/image-317.png) Accessing Admin Account Information 2\. Next, click on the **Security Credentials** tab, and click on **Create** **Access Key** to create an access key. An access key allows you to enable Terraform Cloud service to communicate with your [AWS](https://adamtheautomator.com/iam-aws/) account. ![Creating your Admin user Access Key ](https://adamtheautomator.com/wp-content/uploads/2022/01/image-318.png) Creating your Admin user Access Key Below, you can see the admin user’s credentials (**Access key ID** and **Secret access key**). Save these credentials as you will need them later. ![Previewing your Admin user Access Key](https://adamtheautomator.com/wp-content/uploads/2022/01/image-319.png) Previewing your Admin user Access Key 3\. Navigate to your Terraform Cloud dashboard, and click on **Create an** **organization**. Creating a new organization will help you organize your Terraform Cloud resources and users under a single organization. ![Creating an organization on the Terraform Cloud](https://adamtheautomator.com/wp-content/uploads/2022/01/image-320.png) Creating an organization on the Terraform Cloud 4\. Provide your **Organization name** (**migrate-state**) and your **Email address**, then click on **Create organization**. You set the email address where Terraform Cloud will send email notifications about your organization (updates to your users, billing info, etc.). ![Providing your organization details](https://adamtheautomator.com/wp-content/uploads/2022/01/image-321.png) Providing your organization details 5\. Select the **CLI-driven workflow** option to have a command-line interface to your Terraform Cloud. The command-line interface can work with your existing CI/CD pipelines. ![Choosing your workflow](https://adamtheautomator.com/wp-content/uploads/2022/01/image-322.png) Choosing your workflow 6\. Provide your preferred **Workspace Name**, but the workspace name is **migrate-state for this demo**. Click on **Create workspace** to create the new workspace. ![Providing Workspace Name](https://adamtheautomator.com/wp-content/uploads/2022/01/image-323.png) Providing Workspace Name 7\. Now, click on the **Variables** tab in the workspace’s (**migrate-state**) settings page, and click **Add variable** to add variables. ![Adding variable](https://adamtheautomator.com/wp-content/uploads/2022/01/image-324.png) Adding variable 8\. Configure a variable for your access key ID with the following: * Enter a preferred name in the **Key** text box, but the variable name is set as **AWS\_ACCESS\_KEY\_ID for this demo.** * Enter the access key ID you noted in step two in the **Value** text box. * Tick the **Sensitive** box, and click on the **Save variable** to add the variable to your workspace. The **Sensitive** box’s state controls the visibility of the sensitive fields in your Terraform Cloud. > _Ticking the **Sensitive** box is recommended when creating keys and values. The sensitive fields will show in any UI like the Terraform Cloud dashboard. So, if a workspace is shared with other users, they will not see your keys and values._ ![Adding AWS\_ACCESS\_KEY\_ID variable](https://adamtheautomator.com/wp-content/uploads/2022/01/image-325.png) Adding AWS\_ACCESS\_KEY\_ID variable 9\. Repeat the steps (seven to eight) to add a variable for your admin user’s secret access key you noted in step two. But this time, enter a different name for the variable, like **AWS\_SECRET\_ACCESS\_KEY**. ![AWS\_SECRET\_ACCESS\_KEY variable ](https://adamtheautomator.com/wp-content/uploads/2022/01/image-326.png) AWS\_SECRET\_ACCESS\_KEY variable After adding the variables, you can see your keys in the list of variables. Related:[Utilizing Terraform Output Variables in Infrastructure Configuration](https://adamtheautomator.com/terraform-output-variables/) ## Setting up a Terraform Cloud Backend From creating your account on Terraform Cloud, it’s now time to set up your Terraform Cloud backend. Terraform Cloud Backend lets you centrally configure resources, variables, and back-end configurations. > _Terraform Cloud backend allows you to work with multiple teams or generate different configurations for different environments without hard coding the variable values._ But before you can set up your Terraform Cloud backend, you’ll first create a Terraform Cloud API token. You’ll use the API token to authenticate your Terraform Cloud backend. This token ensures that nobody else can access or change your infrastructure without permission. 1\. On your Terraform Cloud dashboard, click on your profile name on the top right corner, and choose **User Settings**. ![Accessing User Settings](https://adamtheautomator.com/wp-content/uploads/2022/01/image-327.png) Accessing User Settings 2\. Next, click on the **Tokens** tab on the **USER SETTINGS** page, then click on **Create an API token** to generate a new API Token. A new popup will open where you’ll create a new API Token (step three). ![Creating an API token](https://adamtheautomator.com/wp-content/uploads/2022/01/image-328.png) Creating an API token 3\. Provide a token name **(migrate-state**) in the **Description** text box, and click **Create API token** to finalize creating the token. ![Choosing a description for the API token](https://adamtheautomator.com/wp-content/uploads/2022/01/image-329.png) Choosing a description for the API token 4\. Copy and save your API Token in a secure place, then click on **Done**. ![Saving your API token](https://adamtheautomator.com/wp-content/uploads/2022/01/image-330.png) Saving your API token 5\. Return to your terminal, and run the [`terraform login`](https://www.terraform.io/cli/commands/login) command below to log in to Terraform Cloud from your command-line interface. Type **yes** and press Enter when prompted, as shown below. ```bash terraform login ``` ![Logging in to Terraform Cloud from your command-line interface.](https://adamtheautomator.com/wp-content/uploads/2022/01/image-331.png) Logging in to Terraform Cloud from your command-line interface. 6\. Enter your API token you saved earlier when prompted to **Enter a value.** ![Entering your API token ](https://adamtheautomator.com/wp-content/uploads/2022/01/image-332.png) Entering your API token You will get the following output if you have successfully logged in to Terraform Cloud. ![Confirming if you have successfully logged in to Terraform Cloud](https://adamtheautomator.com/wp-content/uploads/2022/01/image-333.png) Confirming if you have successfully logged in to Terraform Cloud 7\. Now, open the _main.tf_ file in your text editor and add the following backend codes at the beginning of the file’s content to set your backend provider. Replace the following values with your preferred values, and save the changes: * `YOUR_ORG_NAME` – The name of your Terraform Cloud organization. This demo uses **migrate-state** as the organization name. * `YOUR_WORKSPACE` – The workspace name you want to use for this project. Ensure that the value matches the name of the workspace you configured in your Terraform Cloud dashboard. This demo uses **migrate-state** as the workspace name. ```bash # Sets your backend provider terraform { backend "remote" { organization = "YOUR_ORG_NAME" workspaces { name = "YOUR_WORKSPACE" } } # This line is a required setting when you initialize a backend config. # You can set this multiple times to add additional providers. required_providers { # Sets your aws backend config. # You can also set custom providers like azurerm, gcp, and vsphere here. aws = { # Specifies the location of your config for this backend. source = "hashicorp/aws" # Specifies the version of your Backend Provider. version = "~> 3.27" } } } ``` Your _main.tf_ file’s content should look like the one below. ![Editing the main.tf Configuration File](https://adamtheautomator.com/wp-content/uploads/2022/01/image-334.png) Editing the _main.tf_ Configuration File ## Applying the Backend Configuration You’ve set up your backend configuration, but it’s not doing much right now unless you apply the backend configuration to your Terraform Cloud. 1\. Run the [`terraform fmt`](https://www.terraform.io/cli/commands/fmt) command to automatically format the source code in your _main.tf_ file to make it human-readable. `terraform fmt` ```bash terraform fmt ``` ![Formatting your main.tf file](https://adamtheautomator.com/wp-content/uploads/2022/01/image-335.png) Formatting your _main.tf_ file 2\. Next, run the `terraform init` command to initialize the working directory. Type **Y** and press Enter when prompted. ```bash terraform init ``` ![Initializing the working directory](https://adamtheautomator.com/wp-content/uploads/2022/01/image-336.png) Initializing the working directory 3\. Run the [`rm`](https://www.computerhope.com/unix/urm.htm) command to delete the existing state file. You will want to use a new state file generated by Terraform Cloud when applying the backend configuration. > _There is no risk of losing any changes when you run the `rm -rf terraform.tfstate` command since you have a backup copy of your state file. Terraform automatically creates the state file when you run the `terraform init` command._ ```bash rm -rf terraform.tfstate ``` ![deleting the existing state file](https://adamtheautomator.com/wp-content/uploads/2022/01/image-337.png) deleting the existing state file 4\. Now, run the `ls` command to list the files in your working directory to ensure that _terraform.tfstate_ is gone and the **backup** copy of your state file exists. ```bash ls ``` ![Verifying the backup copy of your state file is created](https://adamtheautomator.com/wp-content/uploads/2022/01/image-338.png) Verifying the backup copy of your state file is created 5\. Run the [`terraform apply`](https://www.terraform.io/cli/commands/apply) command below to apply the backend configuration. ```bash terraform apply ``` The command might take some time to complete since it’s calling the provider APIs. Once the process is complete, your backend configuration is applied. ![Applying the backend configuration](https://adamtheautomator.com/wp-content/uploads/2022/01/image-339.png) Applying the backend configuration 6\. Navigate back to your Terraform Cloud main page, then click on the workspace’s hyperlink to access your workspace overview. ![Accessing Workspace](https://adamtheautomator.com/wp-content/uploads/2022/01/image-340.png) Accessing Workspace 7\. Next, click on the **Runs** tab and see that your last run appears in your workspace, as shown below. ![Previewing your last run](https://adamtheautomator.com/wp-content/uploads/2022/01/image-341.png) Previewing your last run 8\. Navigate to the **States** tab, as shown below, and click on the state file to view the contents. ![Accessing State File ](https://adamtheautomator.com/wp-content/uploads/2022/01/image-342.png) Accessing State File Like in the image below, you can now view and confirm that you’ve successfully migrated your state file in your Terraform Cloud. ![Previewing your State File](https://adamtheautomator.com/wp-content/uploads/2022/01/image-343.png) Previewing your State File ## Conclusion Throughout this tutorial, you’ve learned how to migrate an existing Terraform state into your Terraform Cloud by setting up a Terraform Cloud environment and backend. At this point, you should have a fully functional backend configuration you can rely on migrating your Terraform state file in your Terraform Cloud. Now, how do you plan to build on this newfound knowledge? Why not [migrate all your Terraform state into Amazon S3](https://medium.com/dnx-labs/terraform-remote-states-in-s3-d74edd24a2c4)? Share this article [Share on X](https://twitter.com/intent/tweet?url=https%3A%2F%2Fadamtheautomator.com%2Fterraform-state%2F&text=How%20to%20Migrate%20Existing%20Terraform%20State%20into%20Terraform%20Cloud)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fadamtheautomator.com%2Fterraform-state%2F)[Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fadamtheautomator.com%2Fterraform-state%2F) ## Related Posts ![](https://adamtheautomator.com/wp-content/uploads/2022/07/How-to-Monitor-AWS-via-the-Terraform-Cloudwatch-Module.jpg) ### [Monitor AWS via the Terraform Cloudwatch Module](/terraform-cloudwatch/) Learn how to monitor and provision with the Terraform Cloudwatch module and keep your AWS infrastructure healthy and in check! ![](https://adamtheautomator.com/wp-content/uploads/2024/03/terragrunt.png) ### [Keeping Terraform Maintainable with Terragrunt](/terragrunt/) Discover Terragrunt and embrace the power to simplify Terraform workflows—Ensure maintainability and organization of your infrastructure today! ![](https://adamtheautomator.com/wp-content/uploads/2022/05/HMaster-Your-Data-with-AWS-Quicksight.jpg) ### [Make Data-Driven Decisions with AWS QuickSight Analytics](/aws-quicksight/) Struggling to make sense of your data? Discover how AWS QuickSight transforms data into actionable insights for smarter decision-making. ## Categories * [IT Ops](/category/it-ops/) * [Cloud](/category/cloud/) * [DevOps](/category/devops/) * [Home Ops](/category/home-ops/) * [Information Security](/category/infosec/) * [Software Development](/category/software-development/) ## Site * [Home](/) * [Tutorials](/tutorials/) * [Instructors](/author/) * [Advertising](/advertising/) * [Recommended Resources](/resources/) * [About Adam](/about-adam/) Copyright 2026© ATA Learning | [Privacy Policy](/privacy/)