HashiCorp Developer AI Private beta now available Sign up today
Terraform
CLI

Migrate state to HCP Terraform

  • 9min
  • |
  • Terraform Cloud
  • Terraform

When using Terraform Community Edition, you are responsible for maintaining a state file as the source of truth for your cloud infrastructure. Terrafrom Cloud offers secure remote state storage, make it easier to collaborate on infrastructure development. You can migrate your state to HCP Terraform without interrupting services or recreating your existing infrastructure.

In this tutorial, you will migrate a local state file to HCP Terraform.

Warning

When uploading a state file to HCP Terraform using the steps in this tutorial, always use the same version of the Terraform CLI you used to create the resources. Using a newer version of Terraform may update the state file and cause state file corruption.

Prerequisites

This tutorial assumes that you have the following:

Note

Terraform versions older than 1.1 use the remote backend block to configure the CLI workflow and migrate state.

Create state

Clone the example configuration for this tutorial. This configuration uses the random provider to generate a random pet name.

$ git clone https://github.com/hashicorp/learn-state-migration

Next, change into the directory.

$ cd learn-state-migration

Open main.tf to review the configuration. It uses an input varaible to determine the length of the generated string and outputs the value.

main.tf
terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "3.3.2"
    }
  }
  required_version = ">= 1.1.0"
}


variable "name_length" {
  description = "The number of words in the pet name"
  default     = "3"
}

resource "random_pet" "pet_name" {
  length    = var.name_length
  separator = "-"
}

output "pet_name" {
  value = random_pet.pet_name.id
}

Initialize the directory.

$ terraform init
Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/random from the dependency lock file
- Installing hashicorp/random v3.3.2...
- Installed hashicorp/random v3.3.2 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

Now apply the configuration, typing yes at the prompt to confirm the operation. 

$ terraform apply

Terraform used the selected providers to generate the following execution plan. Resource actions are
indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # random_pet.pet_name will be created
  + resource "random_pet" "pet_name" {
      + id        = (known after apply)
      + length    = 3
      + separator = "-"
    }

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

Changes to Outputs:
  + pet_name = (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

random_pet.pet_name: Creating...
random_pet.pet_name: Creation complete after 0s [id=mostly-joint-lacewing]

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

Outputs:

pet_name = "mostly-joint-lacewing"

Terraform displays the generated name in the outputs.

Configure HCP Terraform integration

Now that you have a local state file, you need to create a cloud code block in your configuration.

To use HCP Terraform as a backend for your configuration, you must include a cloud block in your configuration.

Add the cloud block to your configuration as shown below, replacing ORGANIZATION-NAME with your own HCP Terraform organization name.

main.tf
terraform {
  cloud {
    organization = "ORGANIZATION-NAME"
    workspaces {
      name = "learn-terraform-migrate"
    }
  }

  required_version = ">= 1.1.0"

  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "3.3.2"
    }
  }
}

While the organization defined in the cloud stanza must already exist, the workspace does not have to; HCP Terraform will create it if necessary. If you use an existing workspace, it must not have any existing states.

Note

HCP Terraform workspaces behave differently from Terraform CLI workspaces. Terraform CLI workspaces allow multiple state files to exist within a single directory, letting you use one configuration for multiple environments. HCP Terraform workspaces contain everything needed to manage a given set of infrastructure, and function like separate working directories.

Authenticate with HCP Terraform

After configuring your HCP Terraform integration, you must authenticate to HCP Terraform to use it for remote operations.

Run terraform login and follow the prompts to log in, typing yes at the confirmation prompt.

$ terraform login
Terraform will request an API token for app.terraform.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
    /Users/username/.terraform.d/credentials.tfrc.json

Do you want to proceed?
  Only 'yes' will be accepted to confirm.

  Enter a value:

For more detailed instructions on logging in, review the login tutorial.

Migrate the state file

To migrate your existing state file to HCP Terraform, you must reinitialize your configuration to update the backend.

Reinitialize your configuration. Terraform detects your updated backend and confirms that you wish to migrate your state file to HCP Terraform. Type yes to confirm the migration.

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

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

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

  Should Terraform migrate your existing state?

  Enter a value: yes


Initializing provider plugins...
- Reusing previous version of hashicorp/random from the dependency lock file
- Using previously-installed hashicorp/random v3.0.1

HCP Terraform has been successfully initialized!

You may now begin working with HCP Terraform. Try running "terraform plan" to
see any changes that are required for your infrastructure.

If you ever set or change modules or Terraform Settings, run "terraform init"
again to reinitialize your working directory.

Configure the HCP Terraform workspace

After migrating your state to HCP Terraform, log in to the HCP Terraform web UI and navigate to your learn-terraform-migrate workspace. Then, go to the workspace's States page. HCP Terraform lists the state you migrated to your new workspace.

A view of the "States" tab in the HCP Terraform workspace

Your configuration relies on an input variable. Navigate to the workspace's Variables page and create a new Terraform variable named name_length with a value of 5.

The HCP Terraform workspace's "Variables" tab with a variable added

If the configuration relied on a cloud provider, you would set the provider credentials on this page as well.

Initiate a run in the new workspace

After verifying that Terraform migrated your state to HCP Terraform, remove your local state file.

$ rm terraform.tfstate

Trigger a new run. Terraform will propose replacing your resource to reflect the update to the name_length input variable. Confirm the operation by typing yes. 

$ terraform apply
Running apply in HCP Terraform. 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/hashicorp-training/learn-terraform-migrate/runs/run-d7aKcNjPL5WjHwuR

Waiting for the plan to start...

Terraform v1.2.2
on linux_amd64
Initializing plugins and modules...
random_pet.pet_name: Refreshing state... [id=ghastly-supreme-tuna]

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # random_pet.pet_name must be replaced
-/+ resource "random_pet" "pet_name" {
      ~ id        = "ghastly-supreme-tuna" -> (known after apply)
      ~ length    = 3 -> 5 # forces replacement
        # (1 unchanged attribute hidden)
    }

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

Changes to Outputs:
  ~ pet_name = "ghastly-supreme-tuna" -> (known after apply)

Do you want to perform these actions in workspace "learn-terraform-migrate"?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

random_pet.pet_name: Destruction complete after 0s
random_pet.pet_name: Creating...
random_pet.pet_name: Creation complete after 0s [id=possibly-eminently-sadly-inspired-mongoose]

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

Outputs:

pet_name = "possibly-eminently-sadly-inspired-mongoose"

Terraform streams the logs to your local console, and also displays the run details in the workspace UI.

Image of a run waiting confirmation, the log states that the resource will be replaced

Destroy your infrastructure

Run terraform destroy to clean up your resources.

$ terraform destroy
Running apply in HCP Terraform. 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/hashicorp-training/learn-terraform-migrate/runs/run-StNegAY8UrBCT6FB

Waiting for the plan to start...

Terraform v1.2.2
on linux_amd64
Initializing plugins and modules...
random_pet.pet_name: Refreshing state... [id=possibly-eminently-sadly-inspired-mongoose]

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # random_pet.pet_name will be destroyed
  - resource "random_pet" "pet_name" {
      - id        = "possibly-eminently-sadly-inspired-mongoose" -> null
      - length    = 5 -> null
      - separator = "-" -> null
    }

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

Changes to Outputs:
  - pet_name = "possibly-eminently-sadly-inspired-mongoose" -> null

Do you really want to destroy all resources in workspace "learn-terraform-migrate"?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

random_pet.pet_name: Destruction complete after 0s

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

You may also optionally delete your HCP Terraform workspace from your workspace's settings page. Review the Destroy resources and workspace tutorial for detailed guidance.

Next steps

In this tutorial, you migrated a state file from your local machine to an HCP Terraform workspace. To learn more about related concepts and HCP Terraform features, review the following resources:

Previous

CLI log in

 Next

Troubleshooting

This tutorial also appears in:

  • 37 tutorials
    Terraform Associate (003) Tutorials
    Progress through these tutorials to prepare for the Terraform Associate (003) certification exam.
    • Terraform
  • 11 tutorials
    Manage Terraform State
    Manage Terraform state. Follow these tutorials to import existing infrastructure and manipulate state storage.
    • Terraform
  • 29 tutorials
    Collaborate using HCP Terraform
    Collaborate on infrastructure with HCP Terraform. Follow these tutorials to migrate state from local storage and take a deeper look at HCP Terraform operations, including VCS integration, workspace configuration, and remote runs.
    • Terraform