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

Import Docker containers one-by-one into Terraform state.
Reconcile and stabilize Docker Terraform configuration until terraform plan is clean.
Add Proxmox inventory/configuration scaffolding and imports later.
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):

../../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.

2.4 KiB Raw Blame History