/writing-infrastructure-code

name: writing-infrastructure-code
description: Managing cloud infrastructure using declarative and imperative IaC tools. Use when provisioning cloud resources (Terraform/OpenTofu for multi-cloud, Pulumi for developer-centric workflows, AWS CDK for AWS-native infrastructure), designing reusable modules, implementing state management patterns, or establishing infrastructure deployment workflows.

Infrastructure as Code

Provision and manage cloud infrastructure using code-based automation tools. This skill covers tool selection, state management, module design, and operational patterns across Terraform/OpenTofu, Pulumi, and AWS CDK.

When to Use

Use this skill when:

• Provisioning cloud infrastructure (compute, networking, databases, storage)
• Migrating from manual infrastructure to code-based workflows
• Designing reusable infrastructure modules
• Implementing multi-cloud or hybrid-cloud deployments
• Establishing state management and drift detection patterns
• Integrating infrastructure provisioning into CI/CD pipelines
• Evaluating IaC tools (Terraform vs Pulumi vs CDK)

Common requests:

• "Create a Terraform module for VPC provisioning"
• "Set up remote state with locking for team collaboration"
• "Compare Pulumi vs Terraform for our use case"
• "Design composable infrastructure modules"
• "Implement drift detection for existing infrastructure"

Core Concepts

Infrastructure as Code Fundamentals

**Key Principles:** 1. **Declarative vs Imperative** - Describe desired state (Terraform) or program infrastructure (Pulumi) 2. **Idempotency** - Same input produces same output, safe to re-run 3. **Version Control** - Infrastructure changes tracked in Git 4. **State Management** - Track actual infrastructure state 5. **Module Composition** - Reusable, versioned infrastructure components

**Benefits:**

• Reproducibility (same code = same infrastructure)
• Auditability (Git history shows all changes)
• Collaboration (code reviews for infrastructure changes)
• Automation (CI/CD deploys infrastructure)
• Disaster recovery (rebuild from code)

Tool Selection Framework

Choose IaC tools based on team composition and cloud strategy:

**Terraform/OpenTofu** - Declarative, HCL-based

• Multi-cloud and hybrid-cloud deployments
• Operations/SRE teams prefer declarative approach
• Largest provider ecosystem (AWS, GCP, Azure, 3000+ providers)
• Mature module registry and community

**Pulumi** - Imperative, programming language-based

• Developer-centric teams familiar with TypeScript/Python/Go
• Complex logic requires programming constructs (loops, conditionals, functions)
• Native unit testing using familiar test frameworks
• Strong typing and IDE support

**AWS CDK** - AWS-native, programming language-based

• AWS-only infrastructure
• Tight integration with AWS services
• L1/L2/L3 construct abstractions
• CloudFormation under the hood

**Decision Tree:**

Multi-cloud required?
├─ YES → Team composition?
│  ├─ Ops/SRE focused → Terraform/OpenTofu
│  └─ Developer focused → Pulumi
└─ NO → AWS only?
   ├─ YES → Language preference?
   │  ├─ HCL/declarative → Terraform
   │  ├─ TypeScript/Python → AWS CDK
   │  └─ YAML/simple → CloudFormation
   └─ NO → GCP/Azure only?
      └─ Terraform or Pulumi

State Management Architecture

Remote state with locking enables team collaboration:

**Backend Selection:**

| Cloud Provider | Recommended Backend | Locking Mechanism | |----------------|---------------------|-------------------| | AWS | S3 + DynamoDB | DynamoDB table | | GCP | Google Cloud Storage | Native | | Azure | Azure Blob Storage | Lease-based | | Multi-cloud | Terraform Cloud/Enterprise | Built-in | | Pulumi | Pulumi Service | Built-in |

**State Isolation Strategies:**

1. **Directory Separation** (recommended for most teams)

• Separate directories per environment (`prod/`, `staging/`, `dev/`)
• Complete state file isolation
• No risk of cross-environment contamination

2. **Workspaces**

• Single codebase, multiple environments
• Shared state backend, environment namespacing
• Risk: accidental cross-environment operations

3. **Layered Architecture**

• Separate state files for networking, compute, data layers
• Blast radius reduction
• Cross-layer references via remote state data sources

**Critical State Management Rules:**

• Always use remote state for team environments
• Enable state file encryption at rest
• Enable versioning on state storage
• Use state locking to prevent concurrent modifications
• Never commit state files to Git
• Mark sensitive outputs as `sensitive = true`

Module Design Patterns

**Composable Module Structure:**

modules/
├── vpc/              # Network foundation
├── security-group/   # Reusable security group patterns
├── rds/              # Database with backups, encryption
├── ecs-cluster/      # Container orchestration base
├── ecs-service/      # Individual microservice
└── alb/              # Application load balancer

**Module Versioning:**

• Pin module versions in production (`version = "5.1.0"`)
• Use semantic versioning for internal modules
• Test module updates in non-prod first
• Maintain CHANGELOG for module releases

**Module Design Principles:**

• Clear input contract (required vs optional variables)
• Documented outputs (what consumers can reference)
• Sane defaults where possible
• Validation rules for inputs
• Examples directory showing usage

**When to Create a Module:**

• Resource group is reused 3+ times
• Clear boundaries and responsibilities
• Stable interface contract
• Team has module maintenance capacity

**When to Keep Monolithic:**

• One-off infrastructure
• Rapid prototyping phase
• High coupling between resources
• Small team, simple infrastructure

Quick Reference

Terraform/OpenTofu Commands

# Initialize providers and backend
terraform init

# Plan changes (preview)
terraform plan

# Apply changes
terraform apply

# Destroy infrastructure
terraform destroy