atelier/domains/infrastructure-as-code/state.md

# State — Derived Rules

> Derives from `domains/infrastructure-as-code/first-principles.md`. State is the cross-cutting IaC concern: P3 (State is Truth) and P8 (Remote State with Locking) live here. Referenced by `terraform.md` and `opentofu.md`.

## Why State Matters (P3 State is Truth)

- The state file is the tool's memory. It records every resource it has claimed, every attribute it has set, and every dependency it has inferred.
- Without state, `plan` cannot compute a diff — it would have nothing to diff against. Lose state, lose the ability to reason about infrastructure safely.
- State can contain plaintext secrets (any sensitive resource attribute). Treat state as a secret-bearing artifact: encrypt at rest, restrict access, never commit it.

## Remote State is Mandatory (P8 Remote State with Locking)

- Local state (`terraform.tfstate` on disk) is acceptable only for a single developer on a throwaway sandbox. Any shared or production environment uses a remote backend.
- A remote backend provides: durability (state survives workstation loss), shared access (team members and CI read the same state), and locking (concurrent `apply` is serialized).
- No locking = data corruption. Two `apply` runs against the same unlocked state race; the loser's changes are silently overwritten.

## Backend Comparison (P8, C4 Locality)

| Backend | Locking | Encryption | Best for | Notes |
|---------|---------|------------|----------|-------|
| S3 + DynamoDB | DynamoDB | SSE-KMS | AWS-hosted | The canonical AWS backend; DynamoDB provides the lock |
| GCS | Built-in | CMEK | GCP-hosted | Native locking via GCS object versioning |
| Azure Blob | Lease | Customer key | Azure-hosted | Lease-based locking |
| HTTP (remote) | Server-side | Server-side | Self-hosted / on-prem | Requires a backend server (e.g., `terraform-backend`) |
| Local | None | None | Single-dev sandbox | Never for shared or prod |
| Consul | KV lock | — | Consul shops | Locking via Consul sessions |
| Postgres | TX | DB encryption | DBA-owned infra | Row-level locking |

- Pick one backend per environment family. Mixing backends across environments fragments operational knowledge (C4 Locality).
- The backend config is part of the configuration, not a runtime secret. Credentials for the backend are runtime secrets. The state file itself is a secret-bearing artifact — treat it per `domains/security/secrets.md`: encrypt at rest, restrict access, never commit it.

## State Isolation per Environment (P4 Plan Before Apply, C4 Locality)

- One state per environment. Never share a single state file across dev, staging, and prod. A `plan` against a shared state crosses environment boundaries — a prod change could appear in a dev plan.
- Isolation patterns: separate workspaces, separate state keys in the same backend, or separate backends entirely. Stricter isolation = safer (separate backends for prod vs non-prod).
- Name state keys by environment and stack: `env:/prod/Networking`, not `prod` or `state`.

## Locking Discipline (P8 Remote State with Locking)

- `terraform force-unlock` is for a stuck lock after a crashed run, not for impatience. Verify the run is actually dead before forcing.
- A forced unlock without verifying the other run is dead causes the corruption the lock prevents.
- In CI, set a lock timeout so a wedged job fails rather than hanging.

## Sensitive Values in State (P10 Secrets Never in Code)

- Any `sensitive = true` attribute is hidden from plan output but stored in state in plaintext (unless the provider encrypts it).
- Backends with at-rest encryption (S3 SSE-KMS, GCS CMEK) protect state at rest. Access to the state file itself is the boundary.
- Never log, print, or commit state. Never pipe `terraform show` to a public channel.

## State Commands (P3 State is Truth)

- `terraform state list` — enumerate resources in state. First step of any state investigation.
- `terraform state show <addr>` — inspect one resource's recorded attributes.
- `terraform state mv` — rename a resource's address without destroying and recreating it. Use when refactoring module structure.
- `terraform state rm` — stop managing a resource without destroying it. Use when handing a resource to another configuration.
- `terraform state pull` / `push` — export and import state. Used in migrations (see `opentofu.md`).
- `terraform import` — bring an existing resource under management by recording its state. The resource must already exist; `import` does not create.
- All `state` subcommands except `list` and `show` mutate state. Treat them as changes: review the intent, run in CI where possible, and commit the resulting config change that justifies the state move.

## Drift and Reconciliation (P9 Drift is Recoverable)

- `terraform plan` reports drift: resources that exist in state but were changed out-of-band, or resources in state that no longer exist in the provider.
- `terraform apply` reconciles drift by bringing reality back to the declared state.
- Manual changes to managed resources are the cause of drift. Treat a drift report as an incident: find who made the manual change and why, then close the access path or the gap that allowed it.
- `terraform plan -refresh=false` skips drift detection. Use only when you know state is current and you want a fast plan; never use it to hide drift.

## What Violates State Discipline

| Violation | Principle |
|-----------|-----------|
| Committed `terraform.tfstate` | P3 State is Truth, P10 Secrets |
| Local state in prod | P8 Remote State with Locking |
| `force-unlock` without verifying the dead run | P8 Remote State with Locking |
| Shared state across environments | P4 Plan Before Apply, C4 Locality |
| Unnamed state keys (`env:/prod`) | C4 Locality |
| Manual change to a managed resource | P9 Drift is Recoverable |
| `state rm` to "fix" a stuck resource | P3 State is Truth |