How to backup your state file from HCP Terraform for disaster recovery

Introduction

HCP Terraform stores infrastructure state in a secure, remote backend. In cases of accidental workspace deletion or other human error, having a backup of the state file is a critical component of a disaster recovery strategy. This guide provides a procedure for programmatically downloading state files from your HCP Terraform organization using its API.

Prerequisites

Before you begin, you will need the following:

• An HCP Terraform API token with permissions to read workspace state. You can generate a token from your user settings.
• Your HCP Terraform organization name.
• The curl and jq command-line utilities installed on your local machine.

Procedure

Follow these steps to identify and download the current state file for a workspace.

1. List all workspace IDs in your organization.

   Execute the following command, replacing <ORG_NAME> with your organization's name and $TOKEN with your API token. This command retrieves a list of all workspace IDs.

   $ curl \
     --header "Authorization: Bearer $TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     https://app.terraform.io/api/v2/organizations/<ORG_NAME>/workspaces | jq -r '.data [].id'

2. Get the state file download URL.

   Using a workspace ID from the previous step, run the next command to retrieve a pre-signed URL for downloading its current state version. Replace <WORKSPACE_ID> with the target workspace ID.

   $ curl \
     --header "Authorization: Bearer $TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     https://app.terraform.io/api/v2/workspaces/<WORKSPACE_ID>/current-state-version | jq -r '.data.attributes."hosted-state-download-url"'

3. Download the state file.

   Use the download URL obtained in the previous step to download the state file and save it locally as terraform.tfstate. Note that the URL in the example below is a placeholder; you must use the one generated by the previous command.

   $ curl -L -o terraform.tfstate \
     https://app.terraform.io/api/state-versions/<STATE_VERSION_ID>/hosted_state

   You can automate this process in a script to regularly back up the state files for all critical workspaces to a secure storage location.