Version remote state with the HCP Terraform API

13min
|
HCP Terraform
Terraform

The Terraform state file is the source of truth for your infrastructure. Protecting and backing up this file is critical for practitioners who use Terraform in production. Remote state storage with HCP Terraform offers fail-safes for your infrastructure in the event of disaster-recovery situations and local file corruption. Although Terraform takes steps to prevent state errors, your state file can get corrupted due to partial apply operations or incorrectly running terraform import or terraform taint. Using the HCP Terraform API, you can safely download, modify, and upload your state file to an HCP Terraform workspace.

In this tutorial, you will generate a state file by deploying an AWS instance with web access using the Terraform CLI. Then, you will download your remote state file and use the Terraform API to create a new state version.

Prerequisites

For this tutorial you will need:

The Terraform CLI 0.15.0+ installed locally.
Access to HCP Terraform or Enterprise.
An AWS account with credentials configured for Terraform.
The awscli configured.
jq installed.

Note

Windows users must install Windows Subsystem for Linux and start this tutorial in the Linux terminal.

Clone the example configuration

Clone the example GitHub repository.

$ git clone https://github.com/hashicorp-education/learn-tfc-state-api

Change into the repository directory.

$ cd learn-tfc-state-api

Open the main.tf file to review the configuration. The main resources in this configuration are an AWS EC2 instance and a security group with port 8080 access.

Next, open the terraform.tf file to configure your HCP Terraform organization. Replace <ORGANIZATION-NAME> with your HCP Terraform organization name.

terraform.tf

terraform {
  required_version = "~> 1.10"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.82.2"
    }
  }

  cloud {
    organization = "<ORGANIZATION_NAME>"
    workspaces {
      name = "learn-terraform-state-api"
    }
  }
}

Save your changes.

Run the terraform login subcommand, and follow the prompts to authenticate to HCP Terraform.

$ 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/<YOU>/.terraform.d/credentials.tfrc.json

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

  Enter a value: yes


---------------------------------------------------------------------------------

Terraform must now open a web browser to the tokens page for app.terraform.io.

If a browser does not open this automatically, open the following URL to proceed:
    https://app.terraform.io/app/settings/tokens?source=terraform-login


---------------------------------------------------------------------------------

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 use by subsequent commands:
    /Users/<YOU>/.terraform.d/credentials.tfrc.json

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


Retrieved token for user <YOU>


---------------------------------------------------------------------------------

                                          -
                                          -----                           -
                                          ---------                      --
                                          ---------  -                -----
                                           ---------  ------        -------
                                             -------  ---------  ----------
                                                ----  ---------- ----------
                                                  --  ---------- ----------
   Welcome to HCP Terraform!                       -  ---------- -------
                                                      ---  ----- ---
   Documentation: terraform.io/docs/cloud             --------   -
                                                      ----------
                                                      ----------
                                                       ---------
                                                           -----
                                                               -


   New to HCP Terraform? Follow these steps to instantly apply an example configuration:

   $ git clone https://github.com/hashicorp/tfc-getting-started.git
   $ cd tfc-getting-started
   $ scripts/setup.sh

For more detailed instructions on logging in, reference the Authenticate the CLI with HCP Terraform tutorial.

After authenticating, initialize your Terraform configuration.

$ terraform init

Initializing HCP Terraform...
Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Installing hashicorp/aws v5.82.2...
- Installed hashicorp/aws v5.82.2 (signed by HashiCorp)

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.

Add AWS credentials to workspace variables

Navigate to HCP Terraform and select your learn-terraform-state-api workspace. Click on "Variables" and add your region variable as a Terraform variable. Add your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables as environment variables. Be sure to mark the AWS credentials environment variables as sensitive