docker/docs/terraform-workflows.md

Terraform Workflows (Brownfield / Reconciliation)

Terraform in this repository is primarily used for importing and reconciling existing infrastructure.

This is a brownfield workflow: real infrastructure exists first, then code/state are brought into alignment.

Core workflow pattern

1. Define/import one existing object.
2. Inspect current provider state.
3. Reconcile hand-maintained .tf configuration.
4. Use targeted ignore_changes only when necessary.
5. Iterate until plan is sane/no-op for intended scope.
6. Avoid casual apply operations.

Docker mirror workflow (documentation-oriented)

Directory: infrastructure/terraform/docker/

Use when intentionally mirroring selected running containers as structured documentation.

Steps

1. Add minimal docker_container resource block (or uncomment/import-ready block).
2. Add import {} block or run terraform import for the container.
3. Run plan and inspect generated/state values.
4. Keep only meaningful, maintainable arguments in hand-edited files.
5. Use generated files as draft input, not final truth.
6. Re-run plan until intended scope is clean.

Proxmox VM workflow

Directory: infrastructure/terraform/proxmox/

Use for existing Proxmox VMs and metadata reconciliation.

Steps

1. Add/import one VM resource at a time.
2. Confirm provider import ID format and vm/node mapping.
3. Inspect with terraform state show / plan output.
4. Move useful arguments into stable hand-maintained files.
5. Keep lifecycle ignore rules narrow and explicit.
6. Iterate per VM until plan stabilizes.

Physical host metadata workflow

Physical host metadata currently lives in Proxmox Terraform locals/outputs and is used as documentation inventory context.

When updating:

1. update locals with factual host metadata,
2. ensure outputs remain documentation-friendly,
3. avoid leaking sensitive internal data not needed for repository goals.

Generated config guidance

infrastructure/terraform/scripts/reconcile_from_plan.sh can generate Terraform draft configuration via -generate-config-out.

Treat generated files as:

• a starting point,
• reviewed manually,
• reduced to meaningful attributes,
• reformatted and split into maintainable files.

Safety reminders

• Do not commit .tfstate* or real .tfvars.
• Do not commit credentials.
• Do not run terraform apply/destroy casually.
• Keep changes incremental and reviewable.

Related docs

• docs/source-of-truth.md
• docs/infrastructure-inventory.md
• infrastructure/terraform/README.md