# Terraform - Core Examples

> Resource definitions, variables, outputs, locals, data sources, and provider configuration. See [SKILL.md](../SKILL.md) for pattern summaries and [reference.md](../reference.md) for decision frameworks.

**Additional Examples:**

- [modules.md](modules.md) - Module structure, composition, versioning
- [state.md](state.md) - Remote backends, state locking, moved/import/removed blocks
- [patterns.md](patterns.md) - for_each, dynamic blocks, lifecycle, conditions

---

## Pattern 1: Provider Configuration

### Basic Provider with Default Tags

```hcl
# providers.tf
provider "aws" {
  region = var.aws_region

  default_tags {
    tags = {
      Project     = var.project_name
      Environment = var.environment
      ManagedBy   = "terraform"
    }
  }
}
```

**Why good:** `default_tags` ensures every AWS resource gets baseline tags for cost allocation and compliance without repeating tags on every resource block.

### Provider Aliases for Multi-Region

```hcl
# providers.tf
provider "aws" {
  region = "us-east-1"
  alias  = "us_east"
}

provider "aws" {
  region = "eu-west-1"
  alias  = "eu_west"
}

# main.tf -- reference alias explicitly
resource "aws_s3_bucket" "us_logs" {
  provider = aws.us_east
  bucket   = "${var.project_name}-logs-us"
}

resource "aws_s3_bucket" "eu_logs" {
  provider = aws.eu_west
  bucket   = "${var.project_name}-logs-eu"
}
```

**Why good:** Aliases enable multi-region deployments from a single configuration. Resources without an explicit `provider` use the default (non-aliased) provider.

---

## Pattern 2: Resource Argument Ordering

Follow the official style guide ordering: meta-arguments first, resource arguments, nested blocks, lifecycle last.

### Good Example

```hcl
resource "aws_instance" "app" {
  for_each = var.app_instances  # 1. Meta-arguments first

  ami           = data.aws_ami.ubuntu.id  # 2. Resource arguments
  instance_type = each.value.instance_type
  subnet_id     = each.value.subnet_id

  tags = merge(
    { Name = "app-${each.key}" },
    var.extra_tags,
  )

  root_block_device {  # 3. Nested blocks
    volume_size = each.value.volume_size_gb
    encrypted   = true
  }

  lifecycle {  # 4. Lifecycle last
    create_before_destroy = true
  }
}
```

**Why good:** Consistent ordering makes resources scannable; meta-arguments at top tell you how many instances exist; lifecycle at bottom is where you look for special behavior.

### Bad Example

```hcl
resource "aws_instance" "app" {
  lifecycle {  # BAD: lifecycle buried at top
    create_before_destroy = true
  }

  tags = { Name = "app" }  # BAD: tags before core config

  ami           = "ami-12345678"  # BAD: hardcoded AMI
  for_each      = var.instances   # BAD: meta-argument after other args
  instance_type = "t3.micro"     # BAD: hardcoded instance type
}
```

**Why bad:** Inconsistent ordering forces readers to scan the entire block to understand meta-arguments and lifecycle; hardcoded values prevent reuse across environments.

---

## Pattern 3: Variables with Types and Validation

### Simple Variables

```hcl
# variables.tf
variable "environment" {
  type        = string
  description = "Deployment environment"

  validation {
    condition     = contains(["dev", "staging", "production"], var.environment)
    error_message = "Environment must be dev, staging, or production."
  }
}

variable "instance_count" {
  type        = number
  description = "Number of application instances"
  default     = 2

  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 10
    error_message = "Instance count must be between 1 and 10."
  }
}
```

### Complex Variable Types

```hcl
variable "ingress_rules" {
  type = list(object({
    from_port   = number
    to_port     = number
    protocol    = string
    cidr_blocks = list(string)
    description = string
  }))
  description = "List of ingress rules for the security group"
  default     = []
}

variable "app_instances" {
  type = map(object({
    instance_type  = string
    subnet_id      = string
    volume_size_gb = number
  }))
  description = "Map of application instance configurations keyed by name"
}
```

**Why good:** Structured types enforce shape at plan time. Map keys become stable `for_each` keys. Descriptions make modules self-documenting.

### Sensitive Variables

```hcl
variable "database_password" {
  type        = string
  description = "Database master password"
  sensitive   = true  # Redacted from plan/apply output

  validation {
    condition     = length(var.database_password) >= 16
    error_message = "Database password must be at least 16 characters."
  }
}
```

**Gotcha:** `sensitive = true` only redacts from CLI output. The value is still stored in plain text in state. For true secret protection, use state encryption (OpenTofu) or a secrets manager data source.

---

## Pattern 4: Outputs

```hcl
# outputs.tf
output "vpc_id" {
  value       = aws_vpc.main.id
  description = "ID of the VPC"
}

output "private_subnet_ids" {
  value       = [for s in aws_subnet.private : s.id]
  description = "List of private subnet IDs"
}

output "database_endpoint" {
  value       = aws_db_instance.main.endpoint
  description = "Database connection endpoint"
  sensitive   = true  # Contains host:port, may be sensitive
}
```

**Key rules:** Every output needs a `description`. Use `sensitive = true` for outputs containing connection strings, IPs, or credentials. Outputs are the module's public API -- treat them as a contract.

---

## Pattern 5: Locals for Derived Values

Use locals to name complex expressions and avoid repetition. Keep them deterministic -- they should not change between runs.

### Good Example

```hcl
locals {
  # Derived from variables -- deterministic
  name_prefix = "${var.project_name}-${var.environment}"

  # Common tags merged from variable + computed values
  common_tags = merge(
    var.extra_tags,
    {
      Project     = var.project_name
      Environment = var.environment
      ManagedBy   = "terraform"
    },
  )

  # Conditional logic named for clarity
  is_production = var.environment == "production"

  # Pre-computed map for for_each
  subnet_config = {
    for idx, cidr in var.private_subnet_cidrs :
    "private-${idx}" => {
      cidr              = cidr
      availability_zone = var.availability_zones[idx % length(var.availability_zones)]
    }
  }
}
```

**Why good:** Named locals make resource blocks readable. `is_production` is clearer than repeating `var.environment == "production"` in multiple resources. Pre-computed maps with `for` expressions keep `for_each` arguments clean.

### Bad Example

```hcl
locals {
  # BAD: Chained locals that are hard to follow
  step1 = [for x in var.items : x if x.enabled]
  step2 = [for x in local.step1 : merge(x, { processed = true })]
  step3 = { for x in local.step2 : x.name => x }

  # BAD: Local that should be a variable (caller-controlled)
  instance_type = "t3.micro"
}
```

**Why bad:** Deep local chains obscure what `step3` actually contains. If a value should be set by the caller, it belongs in a variable, not a local.

---

## Pattern 6: Data Sources

Data sources read existing infrastructure. They are evaluated during planning by default.

### Good Example

```hcl
# Fetch latest Ubuntu AMI
data "aws_ami" "ubuntu" {
  most_recent = true
  owners      = ["099720109477"]  # Canonical

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }
}

# Read existing VPC by tag
data "aws_vpc" "main" {
  filter {
    name   = "tag:Name"
    values = ["${var.project_name}-vpc"]
  }
}

# Reference in resources
resource "aws_instance" "web" {
  ami       = data.aws_ami.ubuntu.id
  subnet_id = data.aws_vpc.main.id
  # ...
}
```

**Why good:** Data sources reference existing infrastructure without managing it. AMI lookups always get the latest patched image. VPC lookup by tag is more resilient than hardcoded IDs.

### Gotcha: Data Source Timing

```hcl
# BAD: Data source depends on resource created in same apply
data "aws_instance" "web" {
  instance_id = aws_instance.web.id  # Not yet created during plan!
}

# GOOD: Use depends_on to defer the read
data "aws_instance" "web" {
  depends_on  = [aws_instance.web]
  instance_id = aws_instance.web.id
}
```

**Why:** Data sources run during planning. If they reference resources that don't exist yet, the plan fails. `depends_on` defers the read until after the dependency is created.

# Terraform - Module Examples

> Module structure, composition, versioning, and registry patterns. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for the module decision framework.

**Additional Examples:**

- [core.md](core.md) - Resource definitions, variables, outputs, locals, data sources
- [state.md](state.md) - Remote backends, state locking, moved/import/removed blocks
- [patterns.md](patterns.md) - for_each, dynamic blocks, lifecycle, conditions

---

## Pattern 1: Standard Module Structure

Every module follows the same file layout. `README.md` presence makes a nested module public-facing.

```
modules/
  vpc/
    main.tf           # Resource definitions
    variables.tf      # Input variables with type, description, validation
    outputs.tf        # Output values with description
    README.md         # Usage documentation (required for public modules)
    locals.tf         # Local values (optional, if complex)
    data.tf           # Data sources (optional, if needed)
```

### Module: variables.tf

```hcl
# modules/vpc/variables.tf
variable "cidr_block" {
  type        = string
  description = "CIDR block for the VPC"

  validation {
    condition     = can(cidrhost(var.cidr_block, 0))
    error_message = "Must be a valid CIDR block (e.g., 10.0.0.0/16)."
  }
}

variable "environment" {
  type        = string
  description = "Environment name used for resource naming and tagging"
}

variable "private_subnet_cidrs" {
  type        = list(string)
  description = "CIDR blocks for private subnets"
  default     = []
}

variable "public_subnet_cidrs" {
  type        = list(string)
  description = "CIDR blocks for public subnets"
  default     = []
}

variable "enable_nat_gateway" {
  type        = bool
  description = "Whether to create a NAT gateway for private subnet internet access"
  default     = false
}
```

### Module: main.tf

```hcl
# modules/vpc/main.tf
resource "aws_vpc" "this" {
  cidr_block           = var.cidr_block
  enable_dns_hostnames = true
  enable_dns_support   = true

  tags = {
    Name = "${var.environment}-vpc"
  }
}

resource "aws_subnet" "private" {
  for_each = {
    for idx, cidr in var.private_subnet_cidrs :
    "private-${idx}" => { cidr = cidr, az_index = idx }
  }

  vpc_id            = aws_vpc.this.id
  cidr_block        = each.value.cidr
  availability_zone = data.aws_availability_zones.available.names[
    each.value.az_index % length(data.aws_availability_zones.available.names)
  ]

  tags = {
    Name = "${var.environment}-${each.key}"
    Tier = "private"
  }
}

data "aws_availability_zones" "available" {
  state = "available"
}
```

### Module: outputs.tf

```hcl
# modules/vpc/outputs.tf
output "vpc_id" {
  value       = aws_vpc.this.id
  description = "ID of the created VPC"
}

output "private_subnet_ids" {
  value       = [for s in aws_subnet.private : s.id]
  description = "List of private subnet IDs"
}
```

**Why good:** Consistent file layout makes any module instantly navigable. Every variable has type + description + validation. Every output has a description. The module does one thing (VPC networking).

---

## Pattern 2: Root Module Composition

Root modules compose child modules. Keep the tree flat -- root calls modules directly, modules do not call other modules.

### Good Example

```hcl
# environments/production/main.tf
module "vpc" {
  source = "../../modules/vpc"

  cidr_block           = "10.0.0.0/16"
  environment          = "production"
  private_subnet_cidrs = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnet_cidrs  = ["10.0.101.0/24", "10.0.102.0/24"]
  enable_nat_gateway   = true
}

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

  environment    = "production"
  vpc_id         = module.vpc.vpc_id
  subnet_ids     = module.vpc.private_subnet_ids
  instance_type  = "t3.large"
  instance_count = 3
}

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

  environment = "production"
  vpc_id      = module.vpc.vpc_id
  subnet_ids  = module.vpc.private_subnet_ids
}
```

**Why good:** Flat composition. Root module is the orchestrator -- it wires outputs from one module to inputs of another. Each module is independently reusable.

### Bad Example

```hcl
# BAD: Module calling another module (nested)
# modules/app/main.tf
module "vpc" {
  source     = "../vpc"       # Module-to-module dependency
  cidr_block = var.cidr_block
}

module "compute" {
  source     = "../compute"
  vpc_id     = module.vpc.vpc_id  # Tight coupling
  subnet_ids = module.vpc.private_subnet_ids
}
```

**Why bad:** The `app` module now depends on both `vpc` and `compute` modules -- it can't be used without them. Debugging requires tracing through multiple module layers. The root module loses visibility into what's being created.

---

## Pattern 3: Module Versioning and Sources

### Registry Module (Versioned)

```hcl
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"  # Pin to major version

  name = "${var.environment}-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  enable_nat_gateway = true
}
```

### Git Source (Tag-Pinned)

```hcl
module "internal_module" {
  source = "git::https://github.com/org/terraform-modules.git//modules/vpc?ref=v2.1.0"

  cidr_block  = "10.0.0.0/16"
  environment = var.environment
}
```

### Local Source

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

  cidr_block  = "10.0.0.0/16"
  environment = var.environment
}
```

**Key rules:**

- Registry modules: always pin with `version = "~> X.Y"` (pessimistic constraint)
- Git sources: always pin with `?ref=vX.Y.Z` (exact tag)
- Local modules: no version pinning needed (changes apply immediately)
- Never use `ref=main` or `ref=HEAD` for git sources in production -- pins to a moving target

---

## Pattern 4: Module with Optional Features

Use `count` or `for_each` conditional patterns to make module features optional.

```hcl
# modules/vpc/main.tf

# NAT Gateway -- only when enabled
resource "aws_nat_gateway" "this" {
  count = var.enable_nat_gateway ? 1 : 0

  allocation_id = aws_eip.nat[0].id
  subnet_id     = values(aws_subnet.public)[0].id

  tags = {
    Name = "${var.environment}-nat"
  }
}

resource "aws_eip" "nat" {
  count = var.enable_nat_gateway ? 1 : 0

  domain = "vpc"
}

# Route table for private subnets -- conditional NAT route
resource "aws_route" "private_nat" {
  count = var.enable_nat_gateway ? 1 : 0

  route_table_id         = aws_route_table.private.id
  destination_cidr_block = "0.0.0.0/0"
  nat_gateway_id         = aws_nat_gateway.this[0].id
}
```

**Why good:** `count = var.enable_flag ? 1 : 0` is the standard pattern for conditional resource creation. Dev environments skip the NAT gateway (cost savings), production enables it.

# Terraform - Advanced Patterns

> for_each, dynamic blocks, lifecycle meta-arguments, custom conditions, and expressions. See [SKILL.md](../SKILL.md) for pattern summaries and [reference.md](../reference.md) for decision frameworks.

**Additional Examples:**

- [core.md](core.md) - Resource definitions, variables, outputs, locals, data sources
- [modules.md](modules.md) - Module structure, composition, versioning
- [state.md](state.md) - Remote backends, state locking, moved/import/removed blocks

---

## Pattern 1: for_each with Maps

### Good Example

```hcl
variable "buckets" {
  type = map(object({
    versioning = bool
    lifecycle_days = number
  }))
  description = "Map of S3 buckets to create, keyed by bucket purpose"
}

resource "aws_s3_bucket" "this" {
  for_each = var.buckets

  bucket = "${var.project_name}-${each.key}"

  tags = {
    Name    = each.key
    Purpose = each.key
  }
}

resource "aws_s3_bucket_versioning" "this" {
  for_each = { for k, v in var.buckets : k => v if v.versioning }

  bucket = aws_s3_bucket.this[each.key].id

  versioning_configuration {
    status = "Enabled"
  }
}
```

**Why good:** Map keys are stable identifiers. Removing a bucket from the map only destroys that specific bucket. The versioning resource uses a filtered `for` expression to only create for buckets with `versioning = true`.

### Calling with map variable

```hcl
# terraform.tfvars
buckets = {
  logs = {
    versioning     = true
    lifecycle_days = 90
  }
  artifacts = {
    versioning     = false
    lifecycle_days = 30
  }
}
```

---

## Pattern 2: for_each with toset

When you have a simple list of unique values (no complex object needed), convert to a set.

```hcl
variable "team_members" {
  type        = list(string)
  description = "List of IAM user names to create"
  default     = ["alice", "bob", "carol"]
}

resource "aws_iam_user" "team" {
  for_each = toset(var.team_members)

  name = each.value

  tags = {
    ManagedBy = "terraform"
  }
}
```

**Gotcha:** `toset()` deduplicates. If your list has `["alice", "alice", "bob"]`, only two users are created. This is silent -- no warning.

---

## Pattern 3: Conditional Resource Creation

Use `count = var.flag ? 1 : 0` for resources that should optionally exist.

```hcl
variable "enable_monitoring" {
  type        = bool
  description = "Whether to create monitoring resources"
  default     = false
}

resource "aws_cloudwatch_metric_alarm" "high_cpu" {
  count = var.enable_monitoring ? 1 : 0

  alarm_name          = "${var.project_name}-high-cpu"
  comparison_operator = "GreaterThanThreshold"
  evaluation_periods  = 2
  metric_name         = "CPUUtilization"
  namespace           = "AWS/EC2"
  period              = 300
  statistic           = "Average"
  threshold           = 80
  alarm_description   = "CPU utilization exceeds 80% for 10 minutes"
}

# Reference conditional resource carefully
output "alarm_arn" {
  value       = var.enable_monitoring ? aws_cloudwatch_metric_alarm.high_cpu[0].arn : null
  description = "ARN of the CPU alarm, null if monitoring disabled"
}
```

**Why good:** Boolean variable makes the feature toggle explicit. Output uses ternary to handle the case where the resource doesn't exist. `count = condition ? 1 : 0` is the standard Terraform pattern for conditional resources.

---

## Pattern 4: Dynamic Blocks

Generate repeated nested blocks from a variable-length collection.

### Good Example

```hcl
variable "ingress_rules" {
  type = list(object({
    from_port   = number
    to_port     = number
    protocol    = string
    cidr_blocks = list(string)
    description = string
  }))
  description = "Ingress rules for the security group"
}

resource "aws_security_group" "web" {
  name        = "${var.project_name}-web-sg"
  description = "Security group for web servers"
  vpc_id      = var.vpc_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
      description = ingress.value.description
    }
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
    description = "Allow all outbound traffic"
  }
}
```

**Why good:** Module callers can define as many ingress rules as needed. The egress block is static and written literally (not dynamic) because it's the same for every caller.

### When NOT to Use Dynamic Blocks

```hcl
# BAD: Dynamic block for a fixed set of 2 rules -- just write them out
dynamic "ingress" {
  for_each = [
    { port = 80,  desc = "HTTP" },
    { port = 443, desc = "HTTPS" },
  ]
  content {
    from_port   = ingress.value.port
    to_port     = ingress.value.port
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
    description = ingress.value.desc
  }
}

# GOOD: Write the two blocks literally -- clearer and easier to read
ingress {
  from_port   = 80
  to_port     = 80
  protocol    = "tcp"
  cidr_blocks = ["0.0.0.0/0"]
  description = "HTTP"
}

ingress {
  from_port   = 443
  to_port     = 443
  protocol    = "tcp"
  cidr_blocks = ["0.0.0.0/0"]
  description = "HTTPS"
}
```

**Why:** HashiCorp's own docs recommend writing nested blocks literally where possible. Dynamic blocks add indirection -- only use them in modules where the caller needs to control the set.

---

## Pattern 5: Lifecycle Meta-Arguments

### prevent_destroy for Critical Resources

```hcl
resource "aws_db_instance" "main" {
  identifier     = "${var.project_name}-db"
  engine         = "postgres"
  engine_version = "16.4"
  instance_class = var.db_instance_class
  # ...

  lifecycle {
    prevent_destroy = true
  }
}

resource "aws_s3_bucket" "terraform_state" {
  bucket = "myorg-terraform-state"

  lifecycle {
    prevent_destroy = true
  }
}
```

**Gotcha:** `prevent_destroy` only blocks `terraform destroy` while the resource block exists. If you remove the entire resource block from your `.tf` files, Terraform will destroy the resource regardless.

### create_before_destroy for Zero-Downtime

```hcl
resource "aws_launch_template" "app" {
  name_prefix   = "${var.project_name}-"
  image_id      = data.aws_ami.app.id
  instance_type = var.instance_type

  lifecycle {
    create_before_destroy = true
  }
}
```

**When to use:** Resources behind load balancers, ASG launch templates, TLS certificates, DNS records -- anything where destroying before creating causes downtime.

### ignore_changes for Externally Managed Attributes

```hcl
resource "aws_autoscaling_group" "app" {
  name                = "${var.project_name}-asg"
  desired_capacity    = var.initial_capacity
  min_size            = var.min_capacity
  max_size            = var.max_capacity
  launch_template {
    id = aws_launch_template.app.id
  }

  lifecycle {
    ignore_changes = [desired_capacity]  # Auto-scaling changes this
  }
}
```

**Why:** Without `ignore_changes`, every `terraform apply` resets `desired_capacity` to the Terraform-configured value, undoing auto-scaling decisions.

### replace_triggered_by

```hcl
resource "aws_instance" "app" {
  ami           = var.ami_id
  instance_type = var.instance_type

  lifecycle {
    replace_triggered_by = [
      aws_launch_template.app.latest_version,  # Force replacement on template change
    ]
  }
}
```

**When to use:** Force resource replacement when a dependency changes that Terraform's normal dependency graph does not detect.

---

## Pattern 6: Preconditions, Postconditions, and Checks

### Precondition (Validate Before Creation)

```hcl
data "aws_ami" "app" {
  most_recent = true
  owners      = ["self"]

  filter {
    name   = "name"
    values = ["${var.project_name}-*"]
  }
}

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

  lifecycle {
    precondition {
      condition     = data.aws_ami.app.architecture == "x86_64"
      error_message = "AMI must be x86_64 architecture for this instance type."
    }
  }
}
```

### Postcondition (Validate After Creation)

```hcl
resource "aws_db_instance" "main" {
  identifier     = "${var.project_name}-db"
  engine         = "postgres"
  instance_class = var.db_instance_class
  # ...

  lifecycle {
    postcondition {
      condition     = self.status == "available"
      error_message = "Database instance did not reach 'available' status."
    }
  }
}
```

### Check Block (Warnings, Non-Blocking)

```hcl
check "health_check" {
  data "http" "app_health" {
    url = "https://${aws_lb.app.dns_name}/health"
  }

  assert {
    condition     = data.http.app_health.status_code == 200
    error_message = "Application health check failed after deployment."
  }
}
```

**Key difference:**

- `precondition` -- blocks plan if condition fails (validate assumptions)
- `postcondition` -- blocks apply if condition fails (validate guarantees)
- `check` -- produces a warning but does NOT block plan or apply (informational)

---

## Pattern 7: For Expressions

Transform collections inline. Use for filtering, mapping, and restructuring data.

```hcl
# Filter a map -- only production instances
locals {
  prod_instances = {
    for name, config in var.instances : name => config
    if config.environment == "production"
  }
}

# Map transformation -- extract specific field
locals {
  instance_arns = [for inst in aws_instance.app : inst.arn]
}

# Restructure -- list of objects to map keyed by name
locals {
  user_map = {
    for user in var.users : user.name => user
  }
}

# Conditional values with ternary in for
locals {
  instance_types = {
    for name, config in var.instances : name => (
      config.environment == "production" ? "t3.large" : "t3.micro"
    )
  }
}
```

**Key syntax:** `{ for k, v in map : new_key => new_value if condition }` produces a map. `[ for v in list : expression ]` produces a list. Add `...` after the value to group by key: `{ for k, v in map : group_key => v... }`.

# Terraform - State Management Examples

> Remote backends, state locking, moved/import/removed blocks, and workspace patterns. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for state organization decision frameworks.

**Additional Examples:**

- [core.md](core.md) - Resource definitions, variables, outputs, locals, data sources
- [modules.md](modules.md) - Module structure, composition, versioning
- [patterns.md](patterns.md) - for_each, dynamic blocks, lifecycle, conditions

---

## Pattern 1: Remote Backend with State Locking

### S3 Backend (AWS)

```hcl
# backend.tf
terraform {
  backend "s3" {
    bucket         = "myorg-terraform-state"
    key            = "production/network/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-locks"
  }
}
```

**Why good:** S3 provides durable storage with versioning for rollback. DynamoDB table provides state locking -- prevents two people from running `terraform apply` simultaneously and corrupting state. `encrypt = true` encrypts state at rest.

### GCS Backend (Google Cloud)

```hcl
terraform {
  backend "gcs" {
    bucket = "myorg-terraform-state"
    prefix = "production/network"
  }
}
```

**Note:** GCS has built-in state locking -- no separate lock table needed.

### Azure Backend

```hcl
terraform {
  backend "azurerm" {
    resource_group_name  = "terraform-state-rg"
    storage_account_name = "myorgterraformstate"
    container_name       = "tfstate"
    key                  = "production/network/terraform.tfstate"
  }
}
```

---

## Pattern 2: Partial Backend Configuration

Backend blocks cannot use variables. Use partial configuration to keep environment-specific values out of code.

### Backend with Placeholders

```hcl
# backend.tf -- shared across environments
terraform {
  backend "s3" {
    # key is the only value that differs per environment
    # bucket, region, dynamodb_table passed via -backend-config
  }
}
```

### Config Files per Environment

```hcl
# config/production.hcl
bucket         = "myorg-terraform-state"
key            = "production/terraform.tfstate"
region         = "us-east-1"
encrypt        = true
dynamodb_table = "terraform-state-locks"
```

```hcl
# config/staging.hcl
bucket         = "myorg-terraform-state"
key            = "staging/terraform.tfstate"
region         = "us-east-1"
encrypt        = true
dynamodb_table = "terraform-state-locks"
```

### Usage

```bash
# Initialize with environment-specific backend config
terraform init -backend-config=config/production.hcl
terraform init -backend-config=config/staging.hcl
```

**Why good:** Backend configuration is separated from Terraform code. Same `.tf` files work for all environments. No secrets in version-controlled files.

---

## Pattern 3: State Organization by Layer

Split state by infrastructure layer to minimize blast radius and speed up plans.

```
infrastructure/
  network/              # VPC, subnets, route tables, NAT gateways
    backend.tf          # key = "prod/network/terraform.tfstate"
    main.tf
    outputs.tf          # Exports VPC ID, subnet IDs for other layers
  compute/              # Instances, ASGs, load balancers
    backend.tf          # key = "prod/compute/terraform.tfstate"
    main.tf
    data.tf             # Reads network outputs via terraform_remote_state
  data/                 # RDS, ElastiCache, S3 buckets
    backend.tf          # key = "prod/data/terraform.tfstate"
    main.tf
```

### Cross-Layer References with terraform_remote_state

```hcl
# compute/data.tf -- reads network layer's outputs
data "terraform_remote_state" "network" {
  backend = "s3"

  config = {
    bucket = "myorg-terraform-state"
    key    = "production/network/terraform.tfstate"
    region = "us-east-1"
  }
}

# compute/main.tf -- uses network outputs
resource "aws_instance" "app" {
  subnet_id = data.terraform_remote_state.network.outputs.private_subnet_ids[0]
  # ...
}
```

**Why good:** Changing a compute instance doesn't risk breaking the network layer. Each layer has a faster plan (fewer resources). Teams can work on different layers independently.

**Gotcha:** `terraform_remote_state` creates a hard coupling to the backend configuration of the source layer. If the source layer's state key changes, all consumers must be updated.

---

## Pattern 4: Moved Blocks for Refactoring

Use `moved` blocks to rename resources or extract them into modules without destroying infrastructure.

### Rename a Resource

```hcl
# Before: resource was named "web_server"
# After: renamed to "app_server"
moved {
  from = aws_instance.web_server
  to   = aws_instance.app_server
}

resource "aws_instance" "app_server" {
  # ... same configuration ...
}
```

### Move Resource into a Module

```hcl
# Before: resource was at root level
# After: moved into module "compute"
moved {
  from = aws_instance.app
  to   = module.compute.aws_instance.app
}

module "compute" {
  source = "./modules/compute"
  # ...
}
```

### Migrate from count to for_each

```hcl
# Before: count-based
# resource "aws_iam_user" "team" {
#   count = 3
#   name  = var.team_members[count.index]
# }

# After: for_each-based
moved {
  from = aws_iam_user.team[0]
  to   = aws_iam_user.team["alice"]
}

moved {
  from = aws_iam_user.team[1]
  to   = aws_iam_user.team["bob"]
}

moved {
  from = aws_iam_user.team[2]
  to   = aws_iam_user.team["carol"]
}

resource "aws_iam_user" "team" {
  for_each = toset(["alice", "bob", "carol"])
  name     = each.value
}
```

**Key rules:**

- Always run `terraform plan` after adding moved blocks -- verify "will be moved" messages
- Remove moved blocks after the migration is applied (they are one-time operations)
- Moved blocks are processed during plan/apply, not retroactively

---

## Pattern 5: Import Blocks for Adopting Existing Resources

Bring pre-existing infrastructure under Terraform management.

```hcl
# Import an existing S3 bucket
import {
  to = aws_s3_bucket.existing_logs
  id = "my-company-logs-bucket"
}

resource "aws_s3_bucket" "existing_logs" {
  bucket = "my-company-logs-bucket"

  tags = {
    Name      = "logs"
    ManagedBy = "terraform"
  }
}
```

**Workflow:**

1. Add the `import` block and matching `resource` block
2. Run `terraform plan` -- Terraform shows what it will import and any config drift
3. Adjust the resource block until the plan shows no changes after import
4. Run `terraform apply` to execute the import
5. Remove the `import` block (one-time operation)

**Gotcha:** You must write the resource block to match the existing resource's configuration, or Terraform will try to modify it on the next apply.

---

## Pattern 6: Removed Blocks

Remove a resource from Terraform management without destroying the actual infrastructure.

```hcl
# Stop managing this resource -- it was moved to another tool
removed {
  from = aws_instance.legacy_app

  lifecycle {
    destroy = false  # Keep the resource, just forget about it
  }
}
```

**When to use:** Migrating resources to another Terraform configuration, handing off management to another tool, or cleaning up state without destroying infrastructure.

---

## Pattern 7: Workspaces for Ephemeral Environments

Workspaces share the same `.tf` files but maintain separate state files. Best for environments that are structurally identical.

```hcl
# Use workspace name for environment-specific values
locals {
  environment = terraform.workspace

  instance_type = {
    dev        = "t3.micro"
    staging    = "t3.small"
    production = "t3.large"
  }
}

resource "aws_instance" "app" {
  instance_type = local.instance_type[local.environment]

  tags = {
    Environment = local.environment
  }
}
```

```bash
# Create and switch workspaces
terraform workspace new staging
terraform workspace select staging
terraform plan -var-file=staging.tfvars
terraform apply -var-file=staging.tfvars
```

**When to use:** Environments that differ only in variable values (instance size, count, domain). **When not to use:** Environments with different resources, providers, or Terraform versions -- use directory-based separation instead.

**Risk:** It's easy to forget which workspace is active. Always verify with `terraform workspace show` before applying.