Terraform Infrastructure as Code

Terraform is the de-facto standard for declarative infrastructure provisioning. This skill covers the complete lifecycle - project setup, module design, remote state management, multi-environment strategy, and keeping real infrastructure aligned with declared configuration. Designed for engineers who know basic Terraform and need opinionated guidance on structure, safety, and production practices.

---

When to use this skill

Trigger this skill when the user:

• Writes or reviews Terraform HCL for any cloud provider (AWS, GCP, Azure)
• Designs reusable Terraform modules or a module registry structure
• Sets up or migrates remote state backends (S3, GCS, Terraform Cloud)
• Manages multiple environments (dev/staging/prod) with Terraform
• Diagnoses drift between actual infrastructure and Terraform state
• Runs or interprets terraform plan, terraform apply, or terraform import
• Handles state operations: state mv, state rm, taint, untaint

Do NOT trigger this skill for:

• Kubernetes manifest authoring (use a kubernetes/helm skill instead)
• Application-level configuration management (Ansible, Chef, Puppet)

---

Key principles

1. Declarative over imperative - Describe the desired end state, not the steps to get there. If you find yourself writing null_resource with provisioners to run shell scripts, stop and ask whether the provider has a proper resource for this.

2. Modules for every reusable pattern - Any configuration block you copy between environments or projects is a module waiting to be written. Extract early; the cost of refactoring into a module grows with usage.

3. Remote state always - Local state is only acceptable for throwaway experiments. Production state lives in a versioned, locked backend (S3 + DynamoDB, GCS, or Terraform Cloud) from day one. State is your source of truth.

4. Plan before apply, in CI - terraform apply without a reviewed plan is the infrastructure equivalent of deploying untested code. Always run terraform plan -out=tfplan and review the diff before applying. Automate this in CI pipelines.

5. Least privilege for providers - The IAM role or service account Terraform uses must have only the permissions needed for that specific configuration. Never use AdministratorAccess or Owner roles for provider credentials.

---

Core concepts

Providers - Plugins that translate HCL into API calls for a cloud or service. Always pin provider versions in required_providers. Unpinned providers break on provider releases.

Resources - The fundamental unit. Each resource block declares one infrastructure object (aws_vpc, google_container_cluster, etc.).

Data sources - Read-only lookups of existing infrastructure not managed by this configuration. Use data blocks to reference shared resources (AMIs, existing VPCs, DNS zones) without importing them into state.

Modules - Containers for multiple resources that are used together. A module is a directory with .tf files. Modules accept variable inputs and expose output values to callers.

State - A JSON file that maps declared resources to real infrastructure objects. Terraform uses state to calculate diffs. Never edit state manually - use terraform state commands.

Workspaces - Named state instances within a single backend configuration. Useful for short-lived feature environments; not recommended for long-lived environment separation (use separate root modules instead).

Backends - Configuration for where and how state is stored and locked. Locking prevents concurrent applies from corrupting state.

---

Common tasks

Set up a project with S3 backend

Structure every Terraform project with these three foundational files before writing any resources.

versions.tf - Pin everything. Unpinned versions cause silent breakage.

terraform {
  required_version = ">= 1.6.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  backend "s3" {
    bucket         = "my-org-terraform-state"
    key            = "services/my-service/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"
  }
}

providers.tf - One provider block, no credentials hardcoded.

provider "aws" {
  region = var.aws_region

  default_tags {
    tags = {
      ManagedBy   = "terraform"
      Environment = var.environment
      Service     = var.service_name
    }
  }
}

variables.tf - Declare all inputs with descriptions and sensible defaults.

variable "aws_region" {
  description = "AWS region to deploy into"
  type        = string
  default     = "us-east-1"
}

variable "environment" {
  description = "Deployment environment (dev, staging, prod)"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be one of: dev, staging, prod"
  }
}

variable "service_name" {
  description = "Name of the service owning this infrastructure"
  type        = string
}

Create the S3 bucket and DynamoDB table for the backend manually (or with a separate bootstrap Terraform config) before running terraform init. You cannot manage the state backend with the same configuration that uses it.

---

Write a reusable module

A module is a directory with main.tf, variables.tf, and outputs.tf. Modules should express one cohesive infrastructure concern. All inputs are declared with descriptions in variables.tf; all outputs expose only what callers need in outputs.tf.

Calling a module from a root configuration:

module "vpc" {
  source = "../../modules/vpc"

  name                 = "my-service-${var.environment}"
  availability_zones   = ["us-east-1a", "us-east-1b", "us-east-1c"]
  public_subnet_cidrs  = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  private_subnet_cidrs = ["10.0.11.0/24", "10.0.12.0/24", "10.0.13.0/24"]
}

See references/module-patterns.md for complete module templates, versioning, and monorepo layout.

---

Manage environments with workspaces

Workspaces share a single backend and configuration. Use them for ephemeral feature environments; prefer separate state files (separate key paths) for permanent environments like staging and prod.

# Create and switch to a feature workspace
terraform workspace new feature-xyz
terraform workspace select feature-xyz

# Reference workspace name in configuration to vary resource names/sizes
resource "aws_instance" "app" {
  instance_type = terraform.workspace == "prod" ? "t3.large" : "t3.micro"
  tags          = { Environment = terraform.workspace }
}

# Clean up the workspace when done
terraform workspace select default
terraform destroy
terraform workspace delete feature-xyz

For prod/staging: use separate backend key paths or separate AWS accounts with separate root modules. Workspaces with a single state key per environment mean a bad apply in one workspace can corrupt state for others.

---

Import existing resources into state

When infrastructure was created outside Terraform and you need to manage it.

# Terraform 1.5+: use import blocks (preferred, reviewable in plan)
# Add this to your .tf file temporarily:
import {
  to = aws_s3_bucket.my_bucket
  id = "my-existing-bucket-name"
}

# Run plan to preview what will be generated
terraform plan -generate-config-out=generated.tf

# Review generated.tf, copy the resource block into your main config, remove
# the import block, then apply
terraform apply

For older Terraform versions (pre-1.5), use the CLI:

terraform import aws_s3_bucket.my_bucket my-existing-bucket-name

After importing, always run terraform plan to verify zero diff before continuing. A non-empty plan after import means your HCL does not match the real resource - fix the HCL, do not apply the diff blindly.

---

Handle state operations safely

State operations modify which resources Terraform tracks. Always take a state backup first.

# Backup state before any manual operation
terraform state pull > backup-$(date +%Y%m%d-%H%M%S).tfstate

# Rename a resource (e.g., after refactoring module structure)
terraform state mv aws_instance.old_name aws_instance.new_name

# Move a resource into a module
terraform state mv aws_s3_bucket.logs module.logging.aws_s3_bucket.logs

# Remove a resource from state without destroying it
# (when you want Terraform to stop managing it)
terraform state rm aws_instance.temporary

# Mark a resource for replacement on next apply
# (forces destroy + recreate even if config unchanged)
terraform taint aws_instance.app
# Terraform 0.15.2+ preferred syntax:
terraform apply -replace="aws_instance.app"

state rm does NOT destroy the real infrastructure. The resource will simply become unmanaged. If you want it gone, destroy first, then remove from state.

---

Detect and fix drift

Drift occurs when real infrastructure diverges from Terraform state (e.g., manual console changes, external automation).

# Step 1: Refresh state against real infrastructure
terraform refresh

# Step 2: Run plan to see what Terraform would change to correct drift
terraform plan

# Step 3a: If drift is unintentional - apply to correct it
terraform apply

# Step 3b: If drift is intentional - update HCL to match reality,
# then verify plan shows no changes
terraform plan  # should output: "No changes. Infrastructure is up-to-date."

# For a targeted drift check on one resource:
terraform plan -target=aws_security_group.app

In CI, detect drift on a schedule:

# Run as a daily cron job - alert if exit code is 2 (changes detected)
terraform plan -detailed-exitcode
# Exit 0: no diff  |  Exit 1: error  |  Exit 2: diff detected

---

Use data sources and dynamic blocks

Data sources look up existing infrastructure without managing it:

# Look up the latest Amazon Linux 2 AMI - never hardcode AMI IDs
data "aws_ami" "amazon_linux" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

resource "aws_instance" "app" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = var.instance_type
}

# Reference an existing VPC not managed by this config
data "aws_vpc" "shared" {
  tags = { Name = "shared-services-vpc" }
}

Dynamic blocks eliminate repetitive nested blocks:

variable "ingress_rules" {
  type = list(object({
    from_port   = number
    to_port     = number
    protocol    = string
    cidr_blocks = list(string)
  }))
}

resource "aws_security_group" "app" {
  name   = "app-sg"
  vpc_id = data.aws_vpc.shared.id

  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      from_port   = ingress.value.from_port
      to_port     = ingress.value.to_port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
    }
  }
}

---

Error handling

Error	Root cause	Fix
Error acquiring the state lock	Another apply is running, or a previous run crashed without releasing the lock	Wait for concurrent run; if stale: terraform force-unlock <LOCK_ID> (verify no concurrent apply first)
Error: inconsistent result after apply	Provider returned a different value than what was planned (often eventual consistency)	Add depends_on or increase retry logic; file a provider bug if persistent
Error: Resource already exists	Trying to create a resource that exists but is not in state	Use terraform import to bring it under management before applying
Error refreshing state: AccessDenied	Provider credentials lack read permissions on existing resources	Expand IAM policy to include Describe* / Get* / List* for affected services
Error: Cycle detected	Circular dependency between resources (A depends on B, B depends on A)	Break the cycle with depends_on or restructure - often caused by security group self-references
Plan shows replacement for unchanged resource	A computed attribute (e.g., an ARN or auto-generated field) changed externally	Run terraform refresh then re-plan; if persistent, check for provider version changes

---

Gotchas

1. You cannot manage the S3 backend bucket with the config that uses it - The backend must exist before terraform init runs. Bootstrap the state bucket and DynamoDB lock table with a separate configuration (or manually). Attempting to create both in the same root module causes a chicken-and-egg failure.

2. terraform destroy in a workspace also destroys shared resources - If your module references shared infrastructure (e.g., a VPC created in another root module), and you run destroy in a feature workspace, any shared resources included via data sources will not be destroyed - but any created by this config will. Audit what belongs to the workspace before destroying.

3. Unpinned provider versions cause silent breakage on upgrades - Without version = "~> 5.0" in required_providers, a provider major version bump in the registry can change resource schemas and break existing configs on the next terraform init. Always pin providers; update versions deliberately.

4. terraform state rm does not destroy the real resource - It only removes Terraform's tracking entry. The resource continues running and accumulating cost. If you want the resource gone, run terraform destroy -target=<resource> first, then remove from state if needed.

5. Workspaces share a backend - a corrupted state affects all workspaces - Using workspaces with separate state keys in the same S3 bucket means a misconfigured state mv or force-unlock at the wrong key can corrupt a different environment's state. Prefer separate AWS accounts or separate state buckets for prod/staging separation.

---

References

For detailed patterns and implementation guidance, read the relevant file from the references/ folder:

• references/module-patterns.md - module composition, factory pattern, versioning, monorepo layout

Only load a references file if the current task requires it - they are detailed and will consume context.