Infrastructure Terraform

Expert knowledge for Infrastructure as Code using Terraform with focus on declarative HCL, state management, and resilient infrastructure.

When to Use This Skill

Use this skill when...	Use a `tfc-*` sibling instead when...
Writing or modifying Terraform HCL configuration locally	Inspecting Terraform Cloud run state via API (`tfc-run-status`)
Running `terraform init/plan/apply/destroy` against a backend	Reading TFC plan/apply log streams (`tfc-run-logs`)
Designing module structure, providers, or remote backends	Analyzing structured plan JSON from a TFC run (`tfc-plan-json`)
Debugging local state, drift, or import workflows	Listing or filtering TFC run history (`tfc-list-runs`, `tfc-workspace-runs`)

Core Expertise

Terraform & IaC

Declarative Infrastructure: Clean, modular, and reusable HCL code
State Management: Protecting and managing Terraform state with remote backends
Providers & Modules: Leveraging community and custom providers/modules
Execution Lifecycle: Mastering the plan -> review -> apply workflow

Infrastructure Provisioning Process

Plan First: Always generate terraform plan and review carefully before changes
Modularize: Break down infrastructure into reusable and composable modules
Secure State: Use remote backends with locking to protect state file
Parameterize: Use variables and outputs for flexible and configurable infrastructure
Destroy with Caution: Double-check plan before running terraform destroy

Essential Commands

# Core workflow
terraform init                   # Initialize working directory
terraform plan                   # Generate execution plan
terraform apply                  # Apply changes
terraform destroy               # Destroy infrastructure

# State management
terraform state list            # List all resources
terraform state show <resource> # Show specific resource
terraform state pull > backup.tfstate  # Backup state

# Validation and formatting
terraform validate              # Validate configuration
terraform fmt -recursive        # Format all files recursively
terraform fmt path/to/dir       # Format specific directory
terraform graph | dot -Tsvg > graph.svg  # Dependency graph

# Working with directories (use -chdir to stay in repo root)
terraform -chdir=gcp fmt        # Format files in gcp/ directory
terraform -chdir=gcp validate   # Validate gcp/ configuration
terraform -chdir=gcp plan       # Plan from specific directory
terraform -chdir=modules/vpc init  # Init module directory

# Debugging
export TF_LOG=DEBUG             # Enable debug logging
terraform plan -out=tfplan      # Save plan for review
terraform show tfplan           # View saved plan

Best Practices

Module Structure

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

  vpc_cidr = var.vpc_cidr
  environment = var.environment
}

output "vpc_id" {
  value = module.vpc.vpc_id
}

Variable Configuration

variable "environment" {
  description = "Environment name"
  type        = string
  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be dev, staging, or prod."
  }
}

Remote State Backend

terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

Provider Configuration

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

Key Debugging Techniques

State Debugging

# State inspection
terraform state list
terraform state show aws_instance.web

# State recovery
terraform refresh
terraform plan -refresh-only
terraform import aws_instance.existing i-1234567890

Error Resolution

# Provider errors
terraform init -upgrade
terraform init -reconfigure

# Resource conflicts
terraform taint aws_instance.broken
terraform apply -target=aws_instance.web

Agentic Optimizations

Context	Command
Format directory	`terraform -chdir=path/to/dir fmt`
Check format (CI)	`terraform fmt -check -recursive`
Validate config	`terraform -chdir=path/to/dir validate`
Compact plan	`terraform plan -compact-warnings`
JSON plan output	`terraform plan -out=plan.tfplan && terraform show -json plan.tfplan`
List resources	`terraform state list`

Quick Reference

Flag	Description
`-chdir=DIR`	Change to DIR before running command
`-recursive`	Process directories recursively
`-check`	Check formatting without changes (CI)
`-compact-warnings`	Show warnings in compact form
`-json`	Output in JSON format
`-out=FILE`	Save plan to file
`-target=RESOURCE`	Target specific resource
`-refresh-only`	Only refresh state, no changes

For detailed debugging patterns, advanced module design, CI/CD integration, and troubleshooting strategies, see REFERENCE.md.

infrastructure-terraform