Files
Infrastructure/terraform/plan.md
T

4.8 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_host is known before apply or produced by it. -> Server comes from Hetzner
  • Does Terraform create the VM, or only bootstrap it? Creating it makes server_host an 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-exec over SSH, or provider user_data/cloud-init. cloud-init is idempotent at boot and needs no SSH; provisioners are what variables.tf is currently shaped for. Pick one before writing main.tf. -> depends i don't know the tradeoffs

Steps

1. Server source — done

main.tf creates cv-control-plane as a Hetzner hcloud_server (cpx32, debian-13) and registers ~/.ssh/cv_infra.pub as an hcloud_ssh_key, so the key is in authorized_keys before the machine boots. terraform.md and README.md still describe server_host as an input; they need updating.

Check: terraform output server_ip returns the address.

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 — done

versions.tf pins cloudflare 5.28.1 and hcloud 1.70.2; init and validate pass. required_version and a null provider still need adding before step 7.

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 — written

dns.tf creates cloudflare_dns_record.apex from hcloud_server.control_plane.ipv4_address, so the record can only be created after the server — one apply does both, in order. proxied = false is required for Caddy's ACME challenge.

Check: terraform apply creates the record, dig +short <domain> returns the server IP.

6. Server creation — written

main.tf creates the server with the SSH public key attached at creation.

Check: terraform apply creates it, terraform output ssh_command 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-exec failure leaves a half-configured server and a state file that thinks it succeeded. When step 8 misbehaves, terraform taint is the escape hatch.