# Terraform in This Repository

Terraform here is used as a **structured inventory + reconciliation layer** for existing infrastructure.

It does **not** replace Docker Compose as runtime deployment authority.

## What Terraform is currently used for

- Proxmox VM import/reconciliation for existing VMs.
- Physical host metadata represented in Terraform locals/outputs.
- Select Docker container mirror resources for documentation-oriented tracking.
- Outputs that can support documentation and later downstream tooling.
- Dynu DNS domain/record import and documentation inventory.

## What Terraform is not used for (today)

- Replacing `services-up.sh` / Compose for day-to-day app runtime orchestration.
- Broad, immediate greenfield provisioning of the whole stack.
- Casual `apply` operations across all infrastructure.
- Replacing Dynu as DNS authority.
- Blindly recreating production DNS records without import/reconciliation.

## Directory map

- `proxmox/` — imported/reconciled VM resources and host metadata outputs.
- `docker/` — selective Docker container import/mirror resources.
- `dynu/` — Dynu DNS brownfield import/reconciliation and DNS documentation outputs.
- `bootstrap/` — backend/provider bootstrap scaffolding.
- `modules/` — placeholder module directories for future stable abstractions.
- `scripts/reconcile_from_plan.sh` — helper to convert generated plan config into reviewable draft files.

## Brownfield workflow standard

1. Import one existing object.
2. Inspect state/plan output.
3. Reconcile hand-maintained Terraform code.
4. Keep `ignore_changes` narrowly scoped.
5. Iterate to no-op/sane plan for intended scope.
6. Avoid casual apply.

See detailed steps in [../../docs/terraform-workflows.md](../../docs/terraform-workflows.md).

## Safe validation commands

From Terraform directories, preferred checks are:

```bash
terraform fmt -check -recursive
terraform init -backend=false -input=false
terraform validate
```

## Secrets and state safety

- Do not commit `.tfstate*`.
- Do not commit real `.tfvars` values.
- Keep credentials in local, untracked inputs only.

## Related docs

- [../../docs/source-of-truth.md](../../docs/source-of-truth.md)
- [../../docs/infrastructure-inventory.md](../../docs/infrastructure-inventory.md)
- [docker/README.md](docker/README.md)
- [proxmox/README.md](proxmox/README.md)