beatz174-bit
55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
# Terraform foundations
|
|
|
|
This directory introduces Terraform in a conservative, incremental way for this homelab repo.
|
|
|
|
## Purpose in this repository
|
|
|
|
Terraform is used here to **document and gradually adopt management** of existing infrastructure without disrupting running services.
|
|
|
|
Current intent:
|
|
- Start with imported live Docker resources so infrastructure is visible and reproducible in code.
|
|
- Add Proxmox inventory/configuration later once provider details and import IDs are confirmed.
|
|
- Keep this phase local-state and learning-oriented (no remote backend yet).
|
|
|
|
## Tool boundaries
|
|
|
|
- **Docker Compose**: day-to-day application/service runtime definitions already used by this repo.
|
|
- **Terraform**: infrastructure state capture and controlled resource management (starting with imports).
|
|
- **Ansible**: follow-on host/configuration management after Terraform inventory and targets are stable.
|
|
- **NixOS**: host OS/system-level declarative configuration, separate from per-service compose workflows.
|
|
|
|
## Layout
|
|
|
|
- `docker/`: Docker provider scaffold and incremental import workflow.
|
|
- `proxmox/`: placeholder scaffold for later Proxmox adoption.
|
|
- `modules/`: placeholder module directories for future shared patterns.
|
|
|
|
## Incremental adoption plan
|
|
|
|
1. Import Docker containers one-by-one into Terraform state.
|
|
2. Reconcile and stabilize Docker Terraform configuration until `terraform plan` is clean.
|
|
3. Add Proxmox inventory/configuration scaffolding and imports later.
|
|
4. Introduce Ansible workflow after Terraform-managed inventory is trustworthy.
|
|
|
|
|
|
## Plan-to-config helper script
|
|
|
|
Use `scripts/reconcile_from_plan.sh` to automate Terraform configuration generation from `terraform plan` output (via Terraform's `-generate-config-out`).
|
|
|
|
From a Terraform module directory (for example `infrastructure/terraform/docker`):
|
|
|
|
```bash
|
|
../../scripts/reconcile_from_plan.sh --output-file zz_generated_from_plan.auto.tf
|
|
```
|
|
|
|
Notes:
|
|
- Best used with an import-first workflow that already contains `import {}` blocks.
|
|
- The script writes generated config into a `.auto.tf` file and runs `terraform fmt` on it.
|
|
- Always review generated arguments before apply.
|
|
|
|
## Safety notes
|
|
|
|
- State files are intentionally gitignored for safety and portability.
|
|
- Do **not** run `terraform apply` until imported resources are fully reconciled and plan output is reviewed as no-op for intended targets.
|
|
- No remote backend is configured yet by design.
|