# 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 - [X] **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 - [X] **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) - [X] **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 ` 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 @` 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://` 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 ```sh 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.