docs(okf): add Terraform provisioning architecture and decision
This commit is contained in:
1 parent
3636053a35
commit
3940946448
2 files changed
+87
No files matched your search
@@ -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.
|
||||||
@@ -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).
|
||||||
Reference in new issue
Block a user