The State File: JSON Schema, Lineage & Sensitive Values

The Big Idea

The single most important artifact in any Terraform project is the state file: terraform.tfstate. Without it, Terraform has zero memory of what it previously built, turning declarative convergence into impossible guesswork.

Cloud APIs do not know about your HCL code. When you run resource "aws_instance" "web" {}, AWS returns a physical ID like i-0a81f3b89c01. The state file is the authoritative ledger that maps the logical identifier aws_instance.web to the physical cloud ID i-0a81f3b89c01, along with all its current attributes.

There is a critical security truth that every DevOps engineer must know: Terraform state files store sensitive values in unencrypted plaintext JSON. If your configuration creates a Postgres database with a password variable or generates a TLS private key, those secrets are stored raw in the state file. Securing and encrypting state is non-negotiable.

Deconstructing the terraform.tfstate JSON Schema

{
  "version": 4,
  "terraform_version": "1.9.5",
  "serial": 14,
  "lineage": "9e2d3b4a-8c1f-4e7a-b9c2-5f6e8d1a3b5c",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "aws_vpc",
      "name": "core",
      "provider": "provider["registry.terraform.io/hashicorp/aws"]",
      "instances": [
        {
          "schema_version": 1,
          "attributes": {
            "arn": "arn:aws:ec2:us-east-1:123456789012:vpc/vpc-0a81b2c3d4e5f6g7",
            "cidr_block": "10.100.0.0/16",
            "enable_dns_hostnames": true,
            "id": "vpc-0a81b2c3d4e5f6g7",
            "tags": {
              "Environment": "production",
              "Name": "core-enterprise-vpc"
            }
          },
          "sensitive_attributes": []
        }
      ]
    }
  ]
}