Terraform Generator

---
name: terraform-gen
description: |
  Trigger when the user asks to write Terraform, provision infrastructure,
  or turn manual cloud setup into IaC. Phrases: "Terraform module",
  "provision", "infrastructure as code", "AWS Terraform", "import existing".
allowed-tools:
  - Read
  - Write
  - Bash(terraform *)
---

# Terraform Generator

Write Terraform that's maintainable: modular, variable-driven, with state
stored remotely and a clear import path for existing resources.

## Prerequisites

- Cloud provider credentials configured
- Terraform 1.7+ installed
- Target cloud identified (AWS, GCP, Azure)

## Steps

1. **Structure the repo:**
   ```
   terraform/
     environments/
       prod/
         main.tf
         terraform.tfvars
         backend.tf
       staging/
         ...
     modules/
       vpc/
       ecs-service/
       rds/
   ```
   Never put raw resources in `environments/`. Environments compose modules.

2. **Remote state from day one.** Local state breaks the moment a second
   person touches the infra. Use S3 + DynamoDB for AWS, GCS for GCP:
   ```hcl
   terraform {
     backend "s3" {
       bucket         = "company-tf-state"
       key            = "prod/terraform.tfstate"
       region         = "us-east-1"
       dynamodb_table = "terraform-locks"
     }
   }
   ```

3. **Write modules that are self-describing.** Every module has:
   - `main.tf` - resources
   - `variables.tf` - inputs with descriptions and types
   - `outputs.tf` - what the module exposes
   - `README.md` - usage example

4. **Import existing resources** instead of recreating. Terraform 1.5+
   supports `import` blocks in code:
   ```hcl
   import {
     to = aws_s3_bucket.logs
     id = "existing-bucket-name"
   }
   ```

5. **Always `plan` before `apply`.** In CI, require a plan artifact for
   review before any apply runs. Automated apply from a PR merge is
   acceptable only for low-blast-radius envs.

6. **Version-lock providers** and Terraform itself in the top-level config.
   A provider minor version can change resource attributes.

## Patterns to follow

- Variables typed and described. `variable "instance_type" {}` alone is lazy.
- Outputs marked sensitive when they are.
- Tags applied at the provider level where possible, not per-resource.
- `terraform fmt` and `terraform validate` in CI.

## Anti-patterns

- One giant `main.tf` with 2000 lines
- Hardcoded environment values (account IDs, regions) in module code
- Using `count` for conditional resources; `for_each` is almost always better
- State file in git (even encrypted)

## Output

- Module(s) with inputs, outputs, and README
- Remote backend configured and initialized
- `terraform plan` runs clean
- At least one env has resources under management