Lab Solution Migration to Terraform Cloud

Many teams begin with Terraform Open Source and later want to move their existing infrastructure into Terraform Cloud without destroying or recreating resources. This guide walks through migrating a local Terraform workspace (the HashiCat AWS example) to Terraform Cloud while preserving state and enabling remote runs. Overview

Clone the HashiCat repository
Validate the configuration and provision locally with Terraform Open Source
Add a Terraform Cloud cloud block to your configuration
Authenticate the CLI and run terraform init to migrate state
Perform post-migration tasks: workspace variables, team access, and a remote apply
Remove local state files after verifying the migration

This lesson demonstrates copying an existing local state into a newly created Terraform Cloud workspace. During the migration prompt you can choose to copy the state or activate the remote workspace without copying state—pick the option that matches your workflow.

Prerequisites

A Terraform Cloud account and organization
Terraform CLI installed
AWS credentials with permissions to create the HashiCat resources
Basic familiarity with Terraform commands: init, plan, apply, and show

Useful references:

1. Clone the HashiCat repository

Get the example repository that contains the Terraform configuration:

git clone https://github.com/hashicorp/hashicat-aws.git

Example output:

Cloning into 'hashicat-aws'...
remote: Enumerating objects: 368, done.
remote: Total 368 (delta 0), reused 0 (delta 0), pack-reused 368
Receiving objects: 100% (368/368), 311.96 KiB | 7.25 MiB/s, done.
Resolving deltas: 100% (215/215), done.

2. Export AWS credentials

Set AWS credentials in your shell so Terraform can provision resources:

export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY"

Replace the placeholder values with your credentials, or use another supported authentication method (environment variables, AWS CLI profile, or instance profile).

3. Inspect the configuration

Open the repository to review the Terraform configuration. The example includes required_providers and an aws provider:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "=3.42.0"
    }
  }
}

provider "aws" {
  # provider configuration (region, etc.)
}

Confirm any required variables, providers, modules, or provisioners so you understand what the state contains before migrating.

4. Initialize and apply locally (optional verification)

Change into the project directory and run the standard lifecycle commands to validate the configuration and create resources locally (using Terraform Open Source):

cd hashicat-aws
terraform init
terraform plan

You may be prompted for required variables (for example var.prefix):

var.prefix
  This prefix will be included in the name of most resources.

Enter a value: meow

If the plan shows resources to add, apply them:

terraform apply

Example summary:

Plan: 12 to add, 0 to change, 0 to destroy.

Apply complete! Resources: 12 added, 0 changed, 0 destroyed.

Outputs:
catapp_ip = "http://3.236.1.255"
catapp_url = "http://ec2-3-236-1-255.compute-1.amazonaws.com"

You might see provisioner logs (e.g., remote-exec) during apply. Confirm the application is reachable via the catapp_url output.

5. Add a Terraform Cloud block

To move state to Terraform Cloud, add a terraform cloud block in a file such as backend.tf:

terraform {
  cloud {
    organization = "Mastering-Terraform-Cloud"
    workspaces {
      tags = ["hashicat", "apps"]
    }
  }
}

Notes:

If you want to bind this configuration to a specific existing workspace, include name = "workspace-name" inside workspaces.
If you omit name, the migration flow will prompt you to create or provide a workspace during terraform init.

6. Authenticate the Terraform CLI with Terraform Cloud

Log the CLI into Terraform Cloud so Terraform can manage the remote workspace and state:

terraform login

This will open a browser or provide a token URL. Follow the prompts to generate and store an API token locally for the CLI.

7. Initialize and migrate state with terraform init

Run:

terraform init

Terraform will detect the cloud block and the Terraform Cloud organization and workspace configuration. During initialization you’ll be prompted whether to migrate the existing local state into the configured Terraform Cloud workspace:

Initializing Terraform Cloud...
Do you wish to proceed?
  As part of migrating to Terraform Cloud, Terraform can optionally copy your
  current workspace state to the configured Terraform Cloud workspace.

Answer "yes" to copy the latest state snapshot to the configured
Terraform Cloud workspace.

Answer "no" to ignore the existing state and just activate the configured
Terraform Cloud workspace with its existing state, if any.

Should Terraform migrate your existing state? Enter a value: yes

Terraform Cloud requires all workspaces to be given an explicit name.
Please provide a new workspace name (e.g. dev, test) that will be used
to migrate the existing default workspace.

Enter a value: devops-aws-hashicat-dev

Choosing yes copies your local state snapshot to Terraform Cloud and creates (or activates) the workspace you specify.
Choosing no will activate the workspace without copying local state (useful if you want to start with an empty or existing remote state).

After a successful migration, you should see:

Terraform Cloud has been successfully initialized!
You may now begin working with Terraform Cloud.

At this point the workspace devops-aws-hashicat-dev exists in the Mastering-Terraform-Cloud organization with your migrated state.

8. Verify remote state

To confirm the state is now in Terraform Cloud:

View the Workspace → States in the Terraform Cloud UI: https://app.terraform.io
Or run:

terraform show

The CLI will read the remote state and print outputs and resource information. Example JSON excerpt (remote state snapshot):

{
  "version": 4,
  "terraform_version": "1.2.7",
  "serial": 0,
  "lineage": "fb7ba970-ad4c-30ed-09c8-5dab0f1204bf",
  "outputs": {
    "catapp_ip": {
      "value": "http://3.236.1.255",
      "type": "string"
    },
    "catapp_url": {
      "value": "http://ec2-3-236-1-255.compute-1.amazonaws.com",
      "type": "string"
    }
  }
}

9. Configure workspace variables and team access

Set required variables in the Terraform Cloud workspace UI to prevent interactive prompts during runs. For example, add prefix = meow as a workspace variable. Manage access:

Create a team (e.g., HashiCat Devs) under Organization → Teams
Grant the team appropriate access (e.g., write) to the devops-aws-hashicat-dev workspace

10. Trigger a remote apply (Terraform Cloud run)

With variables set and the workspace active, running terraform apply from your local machine will trigger a remote plan and apply in Terraform Cloud. The CLI will stream the run output back to your terminal:

terraform apply

Example streamed output:

Running apply in Terraform Cloud. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.

Preparing the remote apply...

To view this run in a browser, visit:
https://app.terraform.io/app/Mastering-Terraform-Cloud/devops-aws-hashicat-dev/runs

Waiting for the plan to start...

Terraform v1.2.7
on linux_amd64
Initializing plugins and modules...
...
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Note: This example includes a null_resource that uses a timestamp() trigger; that can cause a small change and result in a single resource being changed during the remote apply. Example null_resource excerpt:

resource "null_resource" "configure-cat-app" {
  depends_on = [aws_eip_association.hashicat]

  triggers = {
    build_number = timestamp()
  }

  provisioner "file" {
    source      = "files/"
    destination = "/home/ubuntu/"

    connection {
      type        = "ssh"
      user        = "ubuntu"
      private_key = tls_private_key.hashicat.private_key_pem
      host        = aws_eip.hashicat.public_ip
    }
  }

  provisioner "remote-exec" {
    inline = [
      "sudo apt -y update",
      "sleep 15",
      "sudo apt -y install apache2",
      "sudo systemctl start apache2",
      "sudo chown -R ubuntu:ubuntu /var/www/html",
      "chmod +x *.sh",
      "sudo apt -y install cowsay",
      "cowsay Moooooooooooo!"
    ]
  }
}

You can always view the run and logs directly in the Terraform Cloud UI.

Only delete local state files after you have verified the workspace exists in Terraform Cloud and that terraform show reads the remote state correctly. Removing local state prematurely can make recovery more difficult.

11. Clean up local state files

After confirming state is managed remotely, remove the local state files to avoid confusion:

rm -f terraform.tfstate terraform.tfstate.backup

From this point forward, your state is stored in Terraform Cloud and you should use the remote workspace and Terraform Cloud workflows.

Quick reference: key commands and files

Action	Command / File
Clone repo	`git clone https://github.com/hashicorp/hashicat-aws.git`
Initialize (local or after adding cloud block)	`terraform init`
Validate / plan	`terraform plan`
Apply (triggers remote run when using cloud block)	`terraform apply`
Show current state	`terraform show`
Configure Terraform Cloud block	`backend.tf` (or any `.tf` file with the `terraform { cloud { ... } }` block)

Links and further reading

Congratulations — you’ve migrated a Terraform Open Source workspace and its state into Terraform Cloud, configured workspace variables and access, and verified remote applies.

A screenshot of the HashiCorp Terraform Cloud "Workspaces" page listing four workspaces (devops-aws-hashicat-dev and three devops-aws-myapp environments). Each workspace shows a green "Applied" run status, repo names, and recent change timestamps.

Introduction

Introduction to Terraform Cloud

Terraform Cloud Setup

Terraform Cloud Workspaces

Securing Variables with Terraform Cloud

Terraform Cloud Workflows

Terraform Cloud Private Module Registry

Terraform Cloud Team

Migrating to Terraform Cloud

Policy as Code - Sentinel and OPA

Advanced Topics

Lab Solution Migration to Terraform Cloud

Prerequisites

1. Clone the HashiCat repository

2. Export AWS credentials

3. Inspect the configuration

4. Initialize and apply locally (optional verification)

5. Add a Terraform Cloud block

6. Authenticate the Terraform CLI with Terraform Cloud

7. Initialize and migrate state with terraform init

8. Verify remote state

9. Configure workspace variables and team access

10. Trigger a remote apply (Terraform Cloud run)

11. Clean up local state files

Quick reference: key commands and files

Links and further reading

Watch Video

Practice Lab

​Prerequisites

​1. Clone the HashiCat repository

​2. Export AWS credentials

​3. Inspect the configuration

​4. Initialize and apply locally (optional verification)

​5. Add a Terraform Cloud block

​6. Authenticate the Terraform CLI with Terraform Cloud

​7. Initialize and migrate state with terraform init

​8. Verify remote state

​9. Configure workspace variables and team access

​10. Trigger a remote apply (Terraform Cloud run)

​11. Clean up local state files

​Quick reference: key commands and files

​Links and further reading

Watch Video

Practice Lab

Prerequisites

1. Clone the HashiCat repository

2. Export AWS credentials

3. Inspect the configuration

4. Initialize and apply locally (optional verification)

5. Add a Terraform Cloud block

6. Authenticate the Terraform CLI with Terraform Cloud

7. Initialize and migrate state with terraform init

8. Verify remote state

9. Configure workspace variables and team access

10. Trigger a remote apply (Terraform Cloud run)

11. Clean up local state files

Quick reference: key commands and files

Links and further reading