beatz174-bit
94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# 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.
|
|
|
|
|
|
## Dynu DNS workflow
|
|
|
|
Directory: `infrastructure/terraform/dynu/`
|
|
|
|
Use for existing Dynu domains and DNS records.
|
|
|
|
1. Add or confirm the documentation catalog entry for one hostname.
|
|
2. Confirm the provider resource type and import ID format.
|
|
3. Import one existing domain or DNS record at a time.
|
|
4. Inspect state with `terraform state show`.
|
|
5. Reconcile only stable, meaningful attributes into hand-maintained `.tf`.
|
|
6. Keep record IDs, dynamic DNS targets, and provider-computed values out unless intentionally required.
|
|
7. Re-run plan until intended scope is clean.
|
|
|
|
## 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)
|