cfec11bb46
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
stop-slop, taste-skill, terrashark had embedded .git dirs causing Woodpecker clone to fail on submodule update.
68 lines
2.1 KiB
Markdown
68 lines
2.1 KiB
Markdown
# Terraform Structure and State Management
|
|
|
|
This guide covers how to choose repository shape, environment segmentation, and state boundaries for Terraform projects.
|
|
|
|
## Boundary Model
|
|
|
|
Define boundaries by three factors:
|
|
|
|
1. **Change cadence** — what changes together
|
|
2. **Blast radius** — what can fail together
|
|
3. **Ownership** — who approves and supports it
|
|
|
|
If those differ between components, split stacks.
|
|
|
|
## Root Module Patterns
|
|
|
|
| Pattern | Scope |
|
|
|---|---|
|
|
| **service-root** | One business service and its direct dependencies |
|
|
| **platform-root** | Shared platform primitives (network, identity, observability) |
|
|
| **bootstrap-root** | Backend/state prerequisites and foundational security controls |
|
|
|
|
Avoid monolithic roots that mix all three.
|
|
|
|
## Environment Isolation Options
|
|
|
|
| Option | Best For |
|
|
|---|---|
|
|
| **Separate root directories** per environment | Default choice, clearest isolation |
|
|
| **Workspace-per-environment** with strict policy | When governance is strong and access controls exist |
|
|
| **Separate repositories** | Hard regulatory segregation requirements |
|
|
|
|
Pick one and document why.
|
|
|
|
## State Backend Baseline
|
|
|
|
- Remote backend only for collaborative environments
|
|
- Lock protection for every apply path
|
|
- Encryption at rest and in transit
|
|
- Narrow IAM on state and lock stores
|
|
- Versioned backup with restore tested at least once
|
|
- Load [Backend State Safety](backend-state-safety.md) for backend-specific locking, access, and migration guardrails
|
|
|
|
## Cross-Stack Dependencies
|
|
|
|
Preferred order:
|
|
|
|
1. **Explicit module outputs** passed in the same root
|
|
2. **Published interface artifacts** (preferred at scale)
|
|
3. **`terraform_remote_state`** as last-resort coupling
|
|
|
|
If `terraform_remote_state` is used, version and ownership of the producer stack must be explicit.
|
|
|
|
## Apply Safety Gates
|
|
|
|
Minimum gates for any apply:
|
|
|
|
- `fmt` and `validate`
|
|
- Lint and security scan
|
|
- Policy checks
|
|
- Reviewed plan
|
|
- Approved apply
|
|
|
|
## Change Safety for State Evolution
|
|
|
|
- Use `moved` blocks for renames and address changes
|
|
- For imports, document source of truth and verify idempotency before apply
|
|
- For manual state operations, require peer review and rollback notes
|