4.5 KiB
Build plan
Working order for terraform/. Each step ends in something verifiable; do not
start the next one until the check passes.
Goal: terraform apply + kubectl apply -k deploy/ rebuilds the whole system
on an empty machine. See OKF_CV_Website/architecture/terraform.md.
Open decisions
- Where does the server come from? Proxmox VM on the home server, or a
cloud VM. Sets the provider, the key mechanism, and whether
server_hostis known beforeapplyor produced by it. -> Server comes from Hetzner - Does Terraform create the VM, or only bootstrap it? Creating it makes
server_hostan output instead of an input. -> creates a server at hetzner not a vm (yes i know they will use a virtualizer but you understand) - Provisioning mechanism:
remote-execover SSH, or provideruser_data/cloud-init. cloud-init is idempotent at boot and needs no SSH; provisioners are whatvariables.tfis currently shaped for. Pick one before writingmain.tf. -> depends i don't know the tradeoffs
Steps
1. Server source
Decide the two open questions above. Write them into this file so later steps have a fixed target.
Check: one sentence answers "what does apply create?".
2. SSH key — done
~/.ssh/cv_infra and ~/.ssh/cv_infra.pub exist. The public half goes onto the
server during creation (step 6), not after.
Check: ssh-keygen -y -f ~/.ssh/cv_infra prints the public key.
3. Provider and versions
Uncomment versions.tf, set required_version and the provider(s), run
terraform init. Commit .terraform.lock.hcl is currently ignored — decide
whether that stays.
Check: terraform init succeeds, .terraform.lock.hcl exists.
4. Inputs
Copy terraform.tfvars.example to terraform.tfvars, fill server_host,
domain, cloudflare_zone_id, and set
ssh_private_key_path = "~/.ssh/cv_infra". Export CLOUDFLARE_API_TOKEN.
Check: terraform validate passes.
5. DNS first
Write dns.tf: one cloudflare_record for the apex A record. Smallest real
resource, and it exercises provider, token and zone ID with no server involved.
Check: terraform apply creates the record, dig +short <domain> returns the
server IP.
6. Server creation
Add the server resource with the SSH public key attached at creation.
Check: terraform apply creates it, ssh -i ~/.ssh/cv_infra <user>@<host>
works without a password.
7. Connection skeleton
One null_resource with a connection block that runs uname -a. Sort out
host key handling here (host_key pinned vs. insecure_ignore_host_key) and
the wait-for-port-22 problem.
Check: terraform apply returns the remote uname -a output.
8. Base system
Packages, 2 GB swapfile, containerd, then kubeadm/kubelet/kubectl. Every command must be safe to re-run — provisioners have no state tracking.
Check: swapfile active, containerd and kubelet enabled, kubeadm version
matches the design.
9. Control plane
kubeadm init with --pod-network-cidr for Calico, then install the kubeconfig
on the local machine (never in Git).
Check: kubectl get nodes shows the control plane Ready once Calico is in.
10. Addons
Calico, metrics-server, local-path provisioner — bootstrap only, never reconciled after this.
Check: kubectl top nodes returns data, a test PVC binds.
11. Caddy
Install Caddy, template the Caddyfile with reverse_proxy 127.0.0.1:8080. DNS
record must be DNS-only at Cloudflare (grey cloud) or ACME fails.
Check: curl -I https://<domain> returns a valid certificate; 502 is fine at
this point because nothing is listening yet.
12. Outputs
Add the kubeconfig path next to the placeholder in outputs.tf:13-14.
Check: terraform output shows server_ip, proxy_url, kubeconfig path.
13. Workloads in deploy/
Namespace cv, quota, gateway Service on NodePort 8080, then the site
workloads. Applied with kubectl apply -k deploy/, not Terraform.
Check: site loads over HTTPS.
14. Acceptance test
terraform destroy && terraform apply
kubectl apply -k deploy/
Check: site back up from nothing, no manual steps in between. This is the only test that matters; everything above is scaffolding for it.
Notes
- State is local and Git-ignored on purpose; a lost state file means rebuild.
- Terraform manages nothing inside the cluster beyond bootstrap.
- A partial
remote-execfailure leaves a half-configured server and a state file that thinks it succeeded. When step 8 misbehaves,terraform taintis the escape hatch.