Read and Manage the Terraform State File Created by consul-terraform-sync – HashiCorp Help Center

Introduction

By default, Consul-Terraform-Sync (CTS) stores the Terraform state for each task in the Consul KV store using the consul backend. This configuration enables Terraform's state sharing and locking capabilities, which is essential when running multiple CTS instances in a high availability (HA) configuration.

The state files are stored in Consul under the consul-terraform-sync/ KV prefix. Each task's state key follows this format:

consul-terraform-sync/terraform-env:<task_name>

In this example, route53-dns-sync is the name of a task defined in the CTS configuration.

$ consul kv get -keys consul-terraform-sync/
consul-terraform-sync/terraform-env:route53-dns-sync

Problem

By default, CTS compresses the state file with Gzip before writing it to Consul (gzip = true). While this practice reduces storage usage, attempting to read the state file directly using consul kv get returns unreadable binary data.

$ consul kv get consul-terraform-sync/terraform-env:route53-dns-sync

## Binary gzip output...
�D���� E�~����3T�WJ)3!�e�nB���.�<�\�.��7qIy/���+1c���
�Az/�	W��v\�F�>��]0��|�ʌ�� �De����G�|?r��V

This guide provides several methods to read and manage the Terraform state file created by a CTS task.

Solutions

Here are four options for accessing human-readable data from Terraform state managed by CTS.

Option 1: Decode the State File On-the-fly

You can decompress the state file by piping the output of the consul kv get command to the gunzip utility.

$ consul kv get consul-terraform-sync/terraform-env:route53-dns-sync | gunzip

Option 2: Use the Terraform CLI in the Task Workspace

CTS maintains a full Terraform working directory for each task, typically located at sync-tasks/<task_name>/. You can navigate to this directory and use standard terraform commands to inspect the state.

Change into the specific task's working directory.
```
$ cd sync-tasks/route53-dns-sync
```

Use terraform commands to view the state content.

## View the entire state file in a readable format
$ terraform show

## List all resources tracked in the state file
$ terraform state list

Option 3: Disable Gzip Compression in CTS

If you prefer to store the state as plaintext JSON in Consul, you can disable Gzip compression in the driver block of your CTS configuration file.

driver "terraform" {
  backend "consul" {
    gzip = false
  }
}

After restarting CTS with this configuration, new state files will be written to Consul KV as uncompressed JSON.

Option 4: Switch to a Local Backend

To store state files on the local filesystem instead of in Consul KV, you can configure CTS to use the local backend.

driver "terraform" {
  backend "local" {}
}

After restarting CTS, each task will create a readable terraform.tfstate file in its working directory. Note that using the local backend prevents state sharing and locking, which is critical for HA deployments. This option is best suited for single-instance installations or for debugging purposes.

Additional Information