139 lines
4.8 KiB
Markdown
139 lines
4.8 KiB
Markdown
# 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 — done
|
|
|
|
`main.tf` creates `server0` as a Hetzner `hcloud_server` (`cx22`, `ubuntu-24.04`)
|
|
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.server0.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
|
|
|
|
```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.
|