# 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](source-of-truth.md)
- [docs/infrastructure-inventory.md](infrastructure-inventory.md)
- [infrastructure/terraform/README.md](../infrastructure/terraform/README.md)