# Terraform Proxmox Inventory Layer

This directory codifies existing Proxmox infrastructure using an import-first reconciliation model.

## Purpose

- Track existing Proxmox VMs in Terraform.
- Reconcile imported VM configuration into maintainable, explicit files.
- Represent physical host metadata as structured Terraform locals/outputs.
- Support documentation inventory and future downstream tooling.

## Current repository status

This directory already contains imported/reconciled VM resources (for example `docker`, `server-nixos`, `nix-cache`, `pbs`, `pihole`) plus host metadata locals/outputs.

This means it is no longer just a scaffold; treat it as active infrastructure inventory code.

## Workflow standard (brownfield)

1. Import one existing VM at a time.
2. Confirm provider-specific import ID format.
3. Inspect state/plan details.
4. Keep hand-maintained `.tf` files focused and readable.
5. Use `ignore_changes` only where drift noise is unavoidable.
6. Stop when plan is sane/no-op for intended scope.

## File organization expectations

- Prefer one-resource-per-file patterns when practical.
- Keep shared metadata in `locals`/outputs with clear descriptions.
- Keep generated comments/config under ongoing cleanup rather than assuming generated output is final.

## Safety notes

- Do not run broad applies casually.
- Do not commit real credentials or `.tfstate*`.
- Keep changes incremental and reviewable.

## Related docs

- [../README.md](../README.md)
- [../../../docs/source-of-truth.md](../../../docs/source-of-truth.md)
- [../../../docs/terraform-workflows.md](../../../docs/terraform-workflows.md)
- [../../../docs/infrastructure-inventory.md](../../../docs/infrastructure-inventory.md)