Files
Infrastructure/terraform/plan.md
T

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_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

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