8. Store remote state.md

Store Remote State with HCP Terraform

Remote state storage is a critical feature for secure, collaborative, and scalable infrastructure management. This guide details how to use HCP (HashiCorp Cloud Platform) Terraform to securely store state remotely and run Terraform processes in a shared environment.

Prerequisites

Ensure you have the following:

1. Completed prior tutorials with a directory named terraform-aws-instance.
2. The main.tf configuration file in the directory.

main.tf Example

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.16"
    }
  }
  required_version = ">= 1.2.0"
}

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

resource "aws_instance" "app_server" {
  ami           = "ami-08d70e59c07c61a3a"
  instance_type = "t2.micro"
}

Initialize and apply the configuration locally to ensure your infrastructure is properly set up:

terraform init
terraform apply

Set Up HCP Terraform Integration

1. Add the Cloud Block to main.tf

Update main.tf to include the HCP Terraform cloud block. Replace "organization-name" with your HCP organization name.

terraform {
  cloud {
    organization = "organization-name"
    workspaces {
      name = "terraform-aws"
    }
  }

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

2. Log In to HCP Terraform

Log in to your HCP Terraform account using the CLI:

terraform login

Follow the instructions in the terminal and browser to authenticate. Terraform will generate and save an API token locally in ~/.terraform.d/credentials.tfrc.json.

Migrate Your State to HCP Terraform

Reinitialize your Terraform configuration to migrate your local state file to HCP Terraform:

terraform init

You will be prompted to confirm the migration of your existing state to the HCP Terraform workspace:

Do you wish to proceed?
...
Should Terraform migrate your existing state?
Enter a value: yes

After migration, delete the local state file for security:

rm terraform.tfstate

Set Workspace Variables in HCP

Navigate to your workspace (terraform-aws) in the HCP Terraform web UI. Under the Variables section:

1. Add AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as Environment Variables.
2. Mark these variables as Sensitive for secure storage.

Run Terraform Remotely

Trigger a Terraform run in HCP to confirm that the setup works:

terraform apply

If there are no changes to your configuration, you will see output similar to the following:

No changes. Your infrastructure matches the configuration.

Destroy Infrastructure via HCP

When cleaning up, you can destroy your infrastructure using the remote state:

terraform destroy

Terraform will execute the destroy process in HCP Terraform and stream the output to your terminal. Confirm the operation when prompted:

Do you want to perform these actions?
Enter a value: yes

Alternatively, you can confirm the operation directly in the HCP Terraform web UI.

Benefits of HCP Terraform

• Centralized State: Securely stores your state remotely, preventing local corruption or loss.
• Collaboration: Enables multiple team members to work on infrastructure with shared state.
• Secure Secrets: Stores sensitive values (e.g., API tokens) securely in HCP.
• Remote Execution: Allows Terraform to run remotely, ensuring a stable environment for long-running processes.

With your Terraform state now securely stored in HCP, your infrastructure management becomes more collaborative and resilient.