Introduction

Managing Terraform state files locally can lead to challenges in collaboration and state consistency. By default, Terraform stores your infrastructure state locally in a terraform.tfstate file. While this works fine for solo development or testing, local state quickly becomes problematic when multiple people need to collaborate on infrastructure.

To solve this, Terraform Cloud offers a remote backend for storing state securely and centrally. Migrating your state to Terraform Cloud enables better collaboration, version history, state locking, and seamless team workflows.

This guide walks you through how to migrate your local state to Terraform Cloud — step by step.

Prerequisites

Before getting started, ensure the following are set up:

Terraform installed on your local machine: You can install Terraform using Chocolatey (for Windows) or manually via the Terraform download page. Ensure it’s added to your system's PATH to access it from the terminal.
Azure CLI installed and configured: Follow the official instructions to install and configure Azure CLI. You’ll also need to authenticate with az login to connect your machine to your Azure subscription.
Visual Studio Code (VS Code): This is the recommended code editor for managing and writing your Terraform configurations.
Terraform Extension for VS Code: To enhance your Terraform workflow in VS Code, install the Terraform extension. This extension provides syntax highlighting, linting, and IntelliSense for Terraform code.
Azure Subscription: You’ll need an active Azure account. If you don’t have one, you can create one here.
Terraform Cloud Account: Sign up for a Terraform Cloud account if you haven’t already. Terraform Cloud will be used for remote state storage and workspace management.
GitHub Repository: While optional, it’s recommended to have a GitHub repository for version control of your Terraform configurations. You’ll need to clone this repository into your local machine to track your project and collaborate efficiently.

Step by Step guide

Create an Organization in Terraform Cloud:

Create a Workspace:

Within the organization, create a new workspace.
Choose "CLI-driven workflow" as the workflow type.

Open Your Local Project in VS Code

Navigate to your existing Terraform project — this should be the project that currently stores its state locally.

Open the folder in VS Code. You should see your existing Terraform files (main.tf, etc.) and, if you’ve already initialized Terraform, a .terraform folder and terraform.tfstate file.

Step 4: Authenticate Your CLI With Terraform Cloud

Before you can push your state to Terraform Cloud, the Terraform CLI needs to be authenticated.

To get started, go to your Terraform Cloud workspace:

Log in to Terraform Cloud.
Click your profile icon in the top-right corner.
Go to User Settings > Tokens.
Under API Tokens, generate a new token (copy it immediately — it won’t be shown again).

Generate a new API token and copy it.

Next, open your terminal in VS Code and type:

terraform login

Terraform will prompt you to input a value — this is where you paste the token you just copied.

Once you hit Enter, Terraform saves the token locally in a secure credentials file. This authentication process allows your local setup to communicate securely with Terraform Cloud.

This is what your output should look like.

Set Up Terraform Cloud Configuration:

After logging into Terraform Cloud and creating your workspace, the next step is to link your local project to that workspace.

Open your project folder in VS Code and inside it, create a main.tf file if you haven't already. Then, paste the following block at the top of your file:

In your local main.tf file, add the following configuration:

terraform { 
  cloud { 

    organization = "your-organization-name" 

    workspaces { 
      name = "your-workspace-name" 
    } 
  } 
}

Replace "your-organization-name" and "your-workspace-name" with your actual organization and workspace names.

This block tells Terraform to use your Terraform Cloud organization and to store state inside the specific workspace you just created.

Define Provider and Resource Configuration

Below the Terraform Cloud block, define the rest of your Terraform configuration. For example:

provider "azurerm" {
  features = {}
}

resource "azurerm_resource_group" "example" {
  name     = "example-resources"
  location = "East US"
}

This configuration will create a new resource group in Azure.

If you already have an existing Azure resource you want to manage with Terraform, instead of creating it from scratch:

Define the resource block in the same way — just like shown above — but use the actual name and location of the existing resource.

Go to the Azure Portal, find the resource, and copy its Resource ID under the Properties section.

Back in VS Code, run the terraform import command in the terminal:
terraform import azurerm_resource_group.example /subscriptions/.../resourceGroups/your-existing-rg
This links the Azure resource with the Terraform configuration.

This way, whether you're creating a new resource or importing an existing one, Terraform Cloud will manage its state.

Initialize Terraform with the New Backend:

With the remote backend configured, run the following command in your VS Code terminal:

terraform init

This command initializes the project and detects the change in backend.

Terraform will recognize that the backend has changed and ask if you want to migrate the existing state to the remote backend (Terraform Cloud).

Run Terraform Plan

After writing your configuration, run:

terraform plan

Terraform compares the current state (stored in Terraform Cloud) with your configuration and displays a preview of what it will do.

If this is your first run, the plan should show that it will create the resources.

Apply Your Configuration

To actually create the resources and push the state to Terraform Cloud, run:

terraform apply

Review the execution plan. When prompted to confirm, type yes. Terraform will proceed to create the infrastructure and push the state to the workspace in Terraform Cloud.

Verify Resource on Azure Portal

Log into the Azure Portal, go to Resource Groups, and confirm that a group with the specified name (e.g. example-resources) has been created.

Copy Resource ID

Click on the resource group, scroll to find the Resource ID, and copy it. This is useful if you need to reference it elsewhere (for example, in chained configurations or for debugging).

Verify the Remote State in Terraform Cloud

Go back to your Terraform Cloud dashboard. Inside your organization, navigate to the workspace you linked earlier (mimi-project or your chosen name).

Under the "States" tab, you’ll see the latest state file that includes the newly created resources. This verifies that your state is now being managed remotely and securely.

Verify State Migration:

Log in to Terraform Cloud.
Navigate
After initialization, check the Azure portal to ensure the terraform.tfstate file exists in the specified blob container.

Clean Up Local State Files

After a successful migration, it's good practice to remove the local state files to prevent confusion.

Delete Local State Files: Remove the terraform.tfstate and terraform.tfstate.backup files from your local directory.
Here's how:

rm terraform.tfstate terraform.tfstate.backup

This removes both the main Terraform state file and the backup copy from your local directory.

Conclusion

Moving the Terraform state file to Azure ensures safer and more collaborative infrastructure management. With everything set up, Terraform will now automatically use the remote state stored in Azure, making it easier to work across devices or with a team. From here, you can continue building confidently, knowing your infrastructure setup is a bit more secure and scalable.

Migrating Terraform State to Terraform Cloud