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

1. Plan First: Always generate terraform plan and review carefully before changes
2. Modularize: Break down infrastructure into reusable and composable modules
3. Secure State: Use remote backends with locking to protect state file
4. Parameterize: Use variables and outputs for flexible and configurable infrastructure
5. 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.