Demo Migrating State to HCP Terraform

In this guide you’ll migrate a local Terraform configuration and its state file into an HCP Terraform workspace called hcp-demo. This walkthrough covers migrating state, configuring remote runs, and running plans/applies in HCP Terraform (Terraform Cloud) while streaming logs back to your terminal. What you’ll accomplish

Deploy a simple AWS VPC and two subnets locally with Terraform.
Add the HCP cloud block to target the hcp-demo workspace.
Authenticate the CLI with HCP Terraform and migrate local state into the workspace.
Configure workspace environment variables (AWS credentials) so remote runs can access AWS.
Run plans and applies from the CLI — executed remotely in HCP Terraform with streamed logs.

Prerequisites

Requirement	Notes
HCP Terraform organization	`krausen-hcp`
HCP Terraform workspace	`hcp-demo`
Local AWS credentials	Used for the initial local apply (or temporary STS tokens)
Terraform CLI	>= 1.2.2 (matches `required_version` below)

Recommended references

Local Terraform configuration

On your local machine, the demo folder contains these files:

main.tf — defines the VPC and two subnets (public + private)
providers.tf — provider and Terraform settings (initially local-only)
variables.tf — variable declarations with defaults

Files summary

File	Purpose
`main.tf`	Resources: `aws_vpc`, `aws_subnet` (private and public)
`providers.tf`	`required_providers`, `required_version`, and `provider "aws"`
`variables.tf`	Input variables used by `main.tf`

Example main.tf (resources)

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name = "dev-main-vpc"
  }
}

resource "aws_subnet" "private" {
  vpc_id            = aws_vpc.main.id
  cidr_block        = var.private_subnet_cidr
  availability_zone = var.private_subnet_az

  tags = {
    Name = "main-subnet"
  }
}

resource "aws_subnet" "public" {
  vpc_id = aws_vpc.main.id
  cidr_block = var.public_subnet_cidr
  availability_zone = var.public_subnet_az

  tags = {
    Name = "public-subnet"
  }
}

Example providers.tf (initial local-only configuration)

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.31.0"
    }
  }

  required_version = ">= 1.2.2"
}

provider "aws" {
  region = "us-east-2"
}

Initialize, plan, and apply locally (create resources and a terraform.tfstate file):

terraform init
terraform plan
terraform apply --auto-approve

After a successful local apply you should have three AWS resources (VPC + 2 subnets) and a terraform.tfstate file in your working directory.

Add the HCP cloud block to target the workspace

To point this configuration to the HCP workspace hcp-demo, add a cloud block under the top-level terraform block. This instructs Terraform to use remote execution and the specified workspace as the backend. Final providers.tf with HCP cloud configuration:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.31.0"
    }
  }

  required_version = ">= 1.2.2"

  cloud {
    organization = "krausen-hcp"
    workspaces {
      name = "hcp-demo"
    }
  }
}

provider "aws" {
  region = "us-east-2"
}

Format files if needed:

terraform fmt

This single configuration change is all that’s required to point your local directory at the HCP Terraform workspace.

Authenticate the CLI to HCP Terraform

Authenticate the Terraform CLI to HCP Terraform so it can create runs and upload state:

terraform login

This opens a browser to generate a token for app.terraform.io. You will be prompted to paste the token into the CLI:

Generate a token using your browser, and copy-paste it into this prompt.

Terraform will store the token in plain text in the following file for future commands:
/Users/<your-user>/.terraform.d/credentials.tfrc.json

Token for app.terraform.io:
Enter a value:

Paste the token and press Enter. After successful login, the CLI is authenticated to your HCP organization.

Initialize after changing the backend (migrate state)

Because you added the cloud block, run terraform init again. Terraform will detect remote execution and offer to copy your local workspace state to the selected HCP workspace.

terraform init

You will see a prompt like:

Initializing the backend...

Do you want to copy existing state to the new backend?
As part of migrating to HCP Terraform, Terraform can optionally copy your
current workspace state to the new workspace. To do that, answer "yes" to copy it.
If you don't want to do that and want to start from scratch, answer "no".

Answer yes to migrate the existing local state into the hcp-demo workspace. Terraform will complete initialization and upload the current state into HCP Terraform as the workspace’s initial state version.

When Terraform runs remotely in HCP, the execution occurs on HCP-managed workers. These remote workers cannot access your local environment variables, files, or credentials. Store any required secrets (for example, cloud provider credentials) in the workspace variables or use a supported authentication method for remote runs.

First remote plan: missing credentials error

If you run a plan now, Terraform will execute the plan on HCP’s remote workers and stream the output back. However, early in the run you may encounter an error because the remote worker lacks AWS credentials:

terraform plan

Example error:

Error: No valid credential sources found

with provider["registry.terraform.io/hashicorp/aws"]
on providers.tf line 18, in provider "aws":
provider "aws" {

Please see https://registry.terraform.io/providers/hashicorp/aws
for more information about providing credentials.

Error: failed to refresh cached credentials, no EC2 IMDS role found, operation error ec2imds: GetMetadata, exceeded maximum number of attempts, 3, request send failed, Get "http://169.254.169.254/latest/meta-data/iam/security-credentials/": dial tcp 169.254.169.254:80: connect: network is unreachable

This occurs because remote runs cannot see your local ~/.aws/credentials or environment variables. To allow remote workers to authenticate to AWS, add the AWS credentials as workspace environment variables in the HCP UI.

Add workspace environment variables (AWS credentials)

In the HCP Terraform workspace hcp-demo go to: Variables → Add variable(s). Add the following environment variables and mark them as sensitive:

AWS_ACCESS_KEY_ID (sensitive)
AWS_SECRET_ACCESS_KEY (sensitive)
AWS_SESSION_TOKEN (sensitive) — only if using temporary STS credentials

Mark each variable as sensitive so they remain write-only in the UI. After adding these, remote runs will have the credentials they need to authenticate to AWS. The workspace Variables page should look like this:

A screenshot of a Terraform Cloud workspace "Variables" page. It shows three sensitive workspace variables — AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN — marked as write-only and categorized as env.

Treat workspace credentials as secrets. Always mark provider credentials as sensitive in the workspace UI. Rotate keys regularly and prefer short-lived credentials (STS) where possible.

Run plan and apply remotely

With workspace credentials configured, run a plan again. This will trigger a remote run in HCP Terraform and stream logs to your terminal:

terraform plan

Example streaming output (abridged):

Running plan in HCP Terraform. Output will stream here. Pressing Ctrl-C will stop streaming the logs, but will not stop the plan running remotely.

Preparing the remote plan...
To view this run in a browser, visit:
https://app.terraform.io/app/krausen-hcp/hcp-demo/runs/<run-id>

Waiting for the plan to start...

If you update the configuration locally (for example, add a Tags entry to the VPC), the next terraform plan will show the expected change. Example main.tf VPC change (add a tag):

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name        = "dev-main-vpc"
    Environment = "development"
  }
}

Run plan to inspect the change:

terraform plan

Example plan output (abridged):

Terraform will perform the following actions:

  # aws_vpc.main will be updated in-place
  ~ resource "aws_vpc" "main" {
      id = "vpc-0078106452f9f1bed"
      ~ tags = {
          + "Environment" = "development"
            "Name" = "dev-main-vpc"
        }
      ~ tags_all = {
          + "Environment" = "development"
            # (1 unchanged element hidden)
        }
      # (19 unchanged attributes hidden)
    }

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

Apply the change remotely from the CLI:

terraform apply --auto-approve

The apply executes on HCP-managed workers. You can monitor progress in the HCP UI under Runs. After completion, the run summary shows what changed and a new state version is recorded in the workspace: Example run summary (abridged):

Apply finished a few seconds ago
Resources: 0 added, 1 changed, 0 destroyed

~ aws_vpc.main
Updated id=vpc-0078106452f9f1bed  1s

State versions created:
krausen-hcp/hcp-demo#sv-<state-version> (timestamp)

Workspace overview and resources

The HCP Terraform workspace Overview page displays:

Recent runs and their status
Run details and logs for each run
Resources managed by the workspace (for this demo: AWS VPC, private subnet, public subnet)
Provider versions and creation details

This UI provides quick verification that the migration and subsequent updates were successful.

Wrap-up

What you accomplished in this migration:

Deployed resources locally with Terraform and created a local terraform.tfstate.
Added a cloud block to target the hcp-demo workspace in HCP Terraform.
Authenticated the CLI with terraform login.
Migrated the local state to HCP via terraform init and copying state to the workspace.
Configured workspace environment variables for AWS credentials so remote runs can authenticate.
Executed remote terraform plan and terraform apply from the CLI and validated runs/state in the HCP UI.

Next steps and recommendations

Consider using remote state locking and versioning provided by HCP Terraform to collaborate safely.
Use short-lived credentials (STS) or an IAM role for better security posture.
Automate workspace variable creation via the HCP API or Terraform provider for reproducible CI/CD pipelines.

For more information:

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Demo Migrating State to HCP Terraform

Local Terraform configuration

Add the HCP cloud block to target the workspace

Authenticate the CLI to HCP Terraform

Initialize after changing the backend (migrate state)

First remote plan: missing credentials error

Add workspace environment variables (AWS credentials)

Run plan and apply remotely

Workspace overview and resources

Wrap-up

Watch Video

​Local Terraform configuration

​Add the HCP cloud block to target the workspace

​Authenticate the CLI to HCP Terraform

​Initialize after changing the backend (migrate state)

​First remote plan: missing credentials error

​Add workspace environment variables (AWS credentials)

​Run plan and apply remotely

​Workspace overview and resources

​Wrap-up

Watch Video

Local Terraform configuration

Add the HCP cloud block to target the workspace

Authenticate the CLI to HCP Terraform

Initialize after changing the backend (migrate state)

First remote plan: missing credentials error

Add workspace environment variables (AWS credentials)

Run plan and apply remotely

Workspace overview and resources

Wrap-up