How-to Create a State Version Using the API

Introduction

This guide details how to use the HCP Terraform or Terraform Enterprise API to create a new state version by uploading a Terraform state file to a workspace. This procedure is often necessary when a state file becomes corrupted due to events like a partially applied operation, an incorrect terraform state push, or an unexpected Terraform CLI version change.

Prerequisites

Before you begin, you will need the following information. Replace the placeholder values with your specific details.

• HOSTNAME: The hostname of your Terraform Enterprise instance. Use app.terraform.io for HCP Terraform.
• TOKEN: A user API token for authentication.
• WORKSPACE_ID: The ID of the target workspace.

Procedure

Follow these steps to create a state version and upload a state file using the API.

1. Lock the Workspace: In the HCP Terraform or Terraform Enterprise UI, navigate to the desired workspace, go to Settings > Locking, and select the Lock button.
2. Retrieve Workspace ID: Find the Workspace ID by navigating to Settings > General.

3. Download the Current State File (Optional): If you need to modify the current state, download it first. If you already have the state file you intend to upload, you may skip to step 4.

   a. Retrieve the download URL for the current state file. The API response contains a hosted-state-download-url attribute.

   Shell

   $ curl \
     --header "Authorization: Bearer ${TOKEN}" \
     --header "Content-Type: application/vnd.api+json" \
     "https://${HOSTNAME}/api/v2/workspaces/${WORKSPACE_ID}/current-state-version"

   PowerShell

   $params = @{
     Uri = "https://${HOSTNAME}/api/v2/workspaces/${WORKSPACE_ID}/current-state-version"
     Headers = @{ 
       'Authorization' = "Bearer $TOKEN"; 
       'Content-Type' = "application/vnd.api+json" 
     }
     Method = 'GET' 
   }
   Invoke-RestMethod @params

   b. Use the hosted-state-download-url from the previous step to download the state file. This example saves it as state.tfstate.

   Shell

   $ curl -L \
     --header "Authorization: Bearer ${TOKEN}" \
     --header "Content-Type: application/vnd.api+json" \
     ${URL} > state.tfstate

   PowerShell

   $headers = @{ 
     Authorization = "Bearer $TOKEN";
     'Content-Type' = 'application/vnd.api+json'
   }
   Invoke-WebRequest -Uri $URL -Headers $headers -Method Get -OutFile 'state.tfstate'

4. Modify the State File: Open the downloaded state.tfstate file and make your desired changes. You must increment the serial attribute by one. Note the new serial value and the existing lineage value for the next steps.

5. Compute Checksum and Base64 Content: Generate the MD5 checksum and Base64-encoded content of the modified state.tfstate file.

   a. Compute the MD5 checksum.

   Shell

   $ md5sum state.tfstate

   PowerShell

   Get-FileHash .\state.tfstate -Algorithm MD5

   b. Compute the Base64 content.

   macOS / Linux

   ## On Linux, you may need to add the -w 0 flag to prevent line wrapping.
   $ base64 state.tfstate

   PowerShell

   $bytes = [System.IO.File]::ReadAllBytes("C:\path\to\state.tfstate")
   $encoded = [System.Convert]::ToBase64String($bytes)
   $encoded | Set-Content -Path "C:\path\to\state.tfstate.b64"
   Write-Host "ENCODED: $encoded"

6. Create the JSON Payload: Create a file named payload.json with the following content. Replace the bracketed placeholders with the values from the previous steps. The serial value must be a JSON number (not enclosed in quotes).

   {
     "data": {
       "type": "state-versions",
       "attributes": {
         "serial": <SERIAL>,
         "md5": "<MD5_CHECKSUM>",
         "lineage": "<LINEAGE>",
         "state": "<BASE64_CONTENT>"
       }
     }
   }

7. Upload the New State Version: Run the following command to create the new state version using your payload.json file.

   Shell

   $ curl \
     --header "Authorization: Bearer ${TOKEN}" \
     --header "Content-Type: application/vnd.api+json" \
     --request POST \
     --data @payload.json \
     "https://${HOSTNAME}/api/v2/workspaces/${WORKSPACE_ID}/state-versions"

   PowerShell

   $params = @{
     Uri = "https://${HOSTNAME}/api/v2/workspaces/${WORKSPACE_ID}/state-versions"
     Headers = @{ 
       'Authorization' = "Bearer $TOKEN"; 
       'Content-Type' = 'application/vnd.api+json' 
     }
     Method = 'POST'
     InFile = 'C:\path\to\payload.json'
   }
   Invoke-RestMethod @params

8. Finalize and Verify: After the API call succeeds, complete the process.
   • Verify that the new state file appears in the workspace's States tab in the UI.
   • Unlock the workspace by navigating to Settings > Locking and selecting Unlock.
   • Ensure the correct Terraform version is configured for the workspace.

Additional Information

• In recent versions of Terraform Enterprise, downloading a state file requires an authentication token, as documented in the article, 401 Unauthorized Error Downloading State from API.
• For more details on the API endpoint, refer to the official State Versions API documentation.