diff --git a/architecture/terraform.md b/architecture/terraform.md new file mode 100644 index 0000000..9dc9603 --- /dev/null +++ b/architecture/terraform.md @@ -0,0 +1,53 @@ +# Server provisioning + +Terraform owns everything outside the cluster: packages, swap, k3s itself, +the reverse proxy, and DNS records. Rebuilding the server from nothing is two +commands. + +## Scope + +| Layer | Managed by | Examples | +|---|---|---| +| Server, packages, swap, k3s install | Terraform (SSH provisioner, cloud-init or shell) | `fallocate`, `mkswap`, k3s service with trimmed config | +| DNS records | Terraform provider for the DNS zone | A/AAAA record for the apex domain | +| Reverse proxy | Terraform-installed nginx + certbot, config templated | server block to the gateway | +| Workloads inside k3s | kustomize, applied by CI or hand | Namespace `cv`, Deployments, Jobs, Services, quota | + +Terraform does not manage anything inside the cluster. Kubernetes already +describes its own state; Terraform and kubectl would fight over it. + +## Files + +``` +terraform/ + main.tf server: packages, swap, k3s, nginx, certbot + dns.tf A record for the apex domain + variables.tf server IP, SSH key, domain + outputs.tf server IP, proxy URL +``` + +Plan output for one run: + +``` ++ swapfile 2 GB ++ k3s service (traefik, servicelb disabled) ++ nginx server block -> http://127.0.0.1:8080 (gateway NodePort) ++ certbot certificate for noelsabia.dev +``` + +## Why + +- The server became disposable: `terraform destroy && terraform apply` plus + `kubectl apply -k deploy/` returns the whole system. That is the fastest + possible disaster recovery and the clearest possible demo. +- Proxmox and cloud names change; code does not. The same Terraform targets the + home server now and a VM later. +- Home IP changes: the DNS provider has an A record the server can update. + Terraform manages the record; a small script re-sets it if the IP moves. + +## Constraints + +- **Terraform is new tooling** for Noel and needs approval under the stack + rule. Worth it: infrastructure as code is a core work skill. +- State file: local, not in Git. Nothing secret in the config itself. +- Changing a completed chapter or a Job is a delete plus apply, documented. diff --git a/decisions/provision-with-terraform.md b/decisions/provision-with-terraform.md new file mode 100644 index 0000000..9a35e12 --- /dev/null +++ b/decisions/provision-with-terraform.md @@ -0,0 +1,34 @@ +--- +type: Decision +title: Provision the server with Terraform +description: Packages, swap, k3s, nginx and DNS are Terraform code; workloads inside the cluster stay with kustomize. +tags: [decision, terraform, infra] +status: stable +generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z } +verified: { by: human:noel, at: 2026-10-14T00:00:00Z } +--- + +# Decision + +Terraform owns everything outside k3s: server packages, swap, the k3s +install, nginx and certbot, and the DNS record. Nothing inside the cluster. + +# Why + +- The whole system becomes rebuildable from nothing: `terraform destroy` + then `terraform apply`, then `kubectl apply -k deploy/`. +- Infrastructure as code is a core work skill; the playground is the place to + learn it on a real, cheap target. +- The same files target the home server now and any cloud VM later. + +# Rejected + +| Option | Why not | +|---|---| +| Ansible | Fine, but Terraform also covers DNS and is the more common hire signal | +| Terraform for k8s workloads | kubectl/helm already own cluster state; two owners fight | +| Manual server setup | Works once, impossible to demo or recover | + +# Details + +See [terraform provisioning](/architecture/terraform.md).