Terraform_state
Chapter 36: Terraform State
Section titled “Chapter 36: Terraform State”This chapter covers Terraform state management, remote backends, and state best practices.
What is Terraform State?
Section titled “What is Terraform State?”Terraform uses state to map your configuration to real-world resources.
┌─────────────────────────────────────────────────────────────────────────────┐│ Terraform State Purpose │├─────────────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────────────────────────────────────────────────────────────┐ ││ │ Terraform State │ ││ │ │ ││ │ Configuration Real World State │ ││ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ ││ │ │aws_vpc.main│ ←───▶ │ VPC │ ←───▶ │ vpc-id │ │ ││ │ │ cidr=10.0 │ │ 10.0.0.0/16│ │ cidr=10.0 │ │ ││ │ └───────────┘ └───────────┘ └───────────┘ │ ││ │ │ ││ └─────────────────────────────────────────────────────────────────────┘ ││ ││ State Functions: ││ ✓ Track resource ownership ││ ✓ Detect changes between config and reality ││ ✓ Improve performance (caches attribute values) ││ ✓ Collaborate across teams ││ │└─────────────────────────────────────────────────────────────────────────────┘Local State
Section titled “Local State”By default, Terraform stores state in a local file:
# Default locationterraform.tfstate
# View stateterraform show
# List resources in stateterraform state list
# Show specific resourceterraform state show aws_instance.web┌─────────────────────────────────────────────────────────────────────────────┐│ Local State Storage │├─────────────────────────────────────────────────────────────────────────────┤│ ││ Working Directory ││ ┌─────────────────────────────────────────────────────────────────────┐ ││ │ │ ││ │ main.tf │ ││ │ variables.tf │ ││ │ outputs.tf │ ││ │ terraform.tfstate ◄── Local state file │ ││ │ terraform.tfstate.backup ◄── Backup file │ ││ │ │ ││ └─────────────────────────────────────────────────────────────────────┘ ││ ││ Pros: Simple, no additional setup ││ Cons: Not shared, risk of data loss, conflicts in teams ││ │└─────────────────────────────────────────────────────────────────────────────┘State File Format
Section titled “State File Format”{ "version": 4, "terraform_version": "1.6.0", "serial": 1, "lineage": "a1b2c3d4-...", "outputs": {}, "resources": [ { "mode": "managed", "type": "aws_vpc", "name": "main", "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]", "instances": [ { "attributes": { "id": "vpc-0abc123", "cidr_block": "10.0.0.0/16", "enable_dns_hostnames": true, "tags": { "Name": "main-vpc" } } } ] } ]}Remote Backends
Section titled “Remote Backends”Remote backends store state in a shared location, enabling team collaboration.
┌─────────────────────────────────────────────────────────────────────────────┐│ Remote Backend Types │├─────────────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ S3 │ │ Azure │ │ GCS │ │ Terraform │ ││ │ (AWS) │ │ (Azure) │ │ (GCP) │ │ Cloud │ ││ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ││ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ Consul │ │ etcd │ │ PostgreSQL │ ││ └─────────────┘ └─────────────┘ └─────────────┘ ││ ││ Key features to consider: ││ ✓ State locking - prevents concurrent modifications ││ ✓ Encryption at rest - security for sensitive data ││ ✓ Versioning - state file history ││ ✓ Accessibility - team access controls ││ │└─────────────────────────────────────────────────────────────────────────────┘S3 Backend Configuration
Section titled “S3 Backend Configuration”terraform { backend "s3" { bucket = "my-terraform-state" key = "prod/networking/terraform.tfstate" region = "us-east-1" encrypt = true dynamodb_table = "terraform-locks" }}┌─────────────────────────────────────────────────────────────────────────────┐│ S3 Backend with DynamoDB │├─────────────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────────────────────────────────────────────────────────────┐ ││ │ S3 + DynamoDB Backend │ ││ │ │ ││ │ ┌───────────────┐ DynamoDB Table │ ││ │ │ │ ┌───────────────┐ │ ││ │ │ S3 │◄──────────────────────│ LockID │ │ ││ │ │ Bucket │ State Files │ Digest │ │ ││ │ │ (encrypted) │ │ LockExpires │ │ ││ │ │ │ └───────────────┘ │ ││ │ └───────────────┘ │ │ ││ │ │ │ │ ││ │ │ State locking │ │ ││ └──────────┼───────────────────────────────────────┘───────────────────┘ ││ │ ││ ▼ ││ ┌──────────────────────┐ ││ │ Terraform CLI │ ││ └──────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────────────────┘Creating DynamoDB Table for Locking
Section titled “Creating DynamoDB Table for Locking”# Create DynamoDB table for state lockingaws dynamodb create-table \ --table-name terraform-locks \ --attribute-definitions AttributeName=LockID,AttributeType=S \ --key-schema AttributeName=LockID,KeyType=HASH \ --billing-mode PAY_PER_REQUEST \ --region us-east-1Azure Backend
Section titled “Azure Backend”terraform { backend "azurerm" { resource_group_name = "terraform-state" storage_account_name = "terraformstate123" container_name = "tfstate" key = "prod.terraform.tfstate" }}GCS Backend (Google Cloud)
Section titled “GCS Backend (Google Cloud)”terraform { backend "gcs" { bucket = "my-terraform-state" prefix = "prod/networking" }}Terraform Cloud Backend
Section titled “Terraform Cloud Backend”terraform { backend "remote" { organization = "my-org"
workspaces { name = "prod-networking" # or prefix = "prod-" } }}State Management Commands
Section titled “State Management Commands”# Pull state (download to local)terraform state pull > terraform.tfstate
# Push state (upload local to backend)terraform state push terraform.tfstate
# List resourcesterraform state list
# Show resource detailsterraform state show aws_instance.web
# Rename resourceterraform state mv aws_instance.web aws_instance.app
# Remove resource from state (without destroying)terraform state rm aws_instance.old
# Move state to new resource (when replacing)terraform state mv aws_instance.old aws_instance.new
# Backup state before modificationsterraform state backup backup.tfstateState Locking
Section titled “State Locking”State locking prevents concurrent modifications:
┌─────────────────────────────────────────────────────────────────────────────┐│ State Locking Mechanism │├─────────────────────────────────────────────────────────────────────────────┤│ ││ User A: terraform apply ││ ┌─────────────────┐ ││ │ Acquire Lock │────────────────┐ ││ └─────────────────┘ │ ││ ▼ ││ ┌─────────────┐ ││ │ DynamoDB/ │ ││ │ Consul/ etcd │ ││ │ Lock │ ││ └─────────────┘ ││ │ ││ User B: terraform apply │ ││ ┌─────────────────┐ │ ││ │ Wait... │◀───────────────┘ ││ └─────────────────┘ │ ││ │ ││ User A: completes ▼ ││ ┌─────────────────┐ ┌─────────────┐ ││ │ Release Lock │─────▶│ Unlock │ ││ └─────────────────┘ └─────────────┘ ││ ││ Error without locking: ││ Error: Error acquiring the state lock ││ │└─────────────────────────────────────────────────────────────────────────────┘State Security
Section titled “State Security”┌─────────────────────────────────────────────────────────────────────────────┐│ State Security Best Practices │├─────────────────────────────────────────────────────────────────────────────┤│ ││ 1. Encryption at Rest ││ ✓ S3: Enable server-side encryption ││ ✓ Azure: Enable Storage Account encryption ││ ✓ GCS: Enable default encryption ││ ││ 2. Access Control ││ ✓ Use IAM policies to restrict access ││ ✓ Principle of least privilege ││ ✓ Enable versioning for audit trail ││ ││ 3. Sensitive Data ││ ✓ Use -var for sensitive values ││ ✓ Use sensitive variables in outputs ││ ✓ Consider using Vault for secrets ││ ││ 4. State Files Contain: ││ ✗ Resource IDs ││ ✗ Configuration values ││ ✗ Potentially: secrets passed as variables ││ │└─────────────────────────────────────────────────────────────────────────────┘Workspace Management
Section titled “Workspace Management”Workspaces allow you to manage multiple environments from the same configuration:
┌─────────────────────────────────────────────────────────────────────────────┐│ Terraform Workspaces │├─────────────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────────────────────────────────────────────────────────────┐ ││ │ Workspace Structure │ ││ │ │ ││ │ terraform.workspace │ ││ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ││ │ │ default │ │ staging │ │ prod │ │ ││ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ││ │ │ ││ │ Each workspace = separate state file │ ││ │ └─ s3://bucket/staging/terraform.tfstate │ ││ │ └─ s3://bucket/prod/terraform.tfstate │ ││ │ │ ││ └─────────────────────────────────────────────────────────────────────┘ ││ ││ Use cases: ││ ✓ Multiple environments (dev, staging, prod) ││ ✓ Feature branches ││ ✓ Isolated infrastructure ││ │└─────────────────────────────────────────────────────────────────────────────┘Workspace Commands
Section titled “Workspace Commands”# List workspacesterraform workspace list
# Create workspaceterraform workspace new staging
# Select workspaceterraform workspace select staging
# Show current workspaceterraform workspace show
# Delete workspace (must be non-current)terraform workspace delete staging
# Workspace in configurationresource "aws_instance" "web" { ami = "ami-0c55b159cbfafe1f0"
# Use workspace in resource naming tags = { Name = "web-${terraform.workspace}" }
# Conditional based on workspace count = terraform.workspace == "prod" ? 3 : 1}Importing Existing Resources
Section titled “Importing Existing Resources”# Import existing AWS VPC into Terraform stateterraform import aws_vpc.main vpc-0abc123
# Import into specific moduleterraform import module.vpc.aws_vpc.main vpc-0abc123
# Import into workspaceterraform workspace select staging && terraform import aws_vpc.main vpc-0abc123Import Block
Section titled “Import Block”# In Terraform 1.5+import { to = aws_vpc.main id = "vpc-0abc123def456"}Summary
Section titled “Summary”In this chapter, you learned:
- What is State: How Terraform tracks resources
- Local State: Default file-based storage
- Remote Backends: S3, Azure, GCS, Terraform Cloud
- State Locking: Preventing concurrent modifications
- State Security: Encryption, access control
- Workspaces: Managing multiple environments
- Import: Bringing existing resources under Terraform management