k3s is out. The cluster is upstream Kubernetes installed with kubeadm: containerd, single control-plane etcd, Calico for NetworkPolicy. - add the cluster decision and the FreeLens decision - move Terraform from the k3s service to kubeadm, Calico, metrics-server and the local-path provisioner - budget ~900 MB for the control plane and plan a bigger machine before 0.3.0 - note kubelet failSwapOn and containerd hosts.toml - rename 0.3.0 and commit the 0.2.0 done-when to the new stack - update the German learning plan
3.1 KiB
3.1 KiB
type, title, description, tags, status, generated
| type | title | description | tags | status | generated | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Architecture | System architecture | All runtime components of the v1 site and how a request and a knockdown flow through them. |
|
stable |
|
Components
| Component | Runs as | Job |
|---|---|---|
| Caddy (reverse proxy) | Terraform-installed, on the home server | Only way in from the internet. TLS automatic via ACME. Points at the gateway. |
| Gateway | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns, counts visits into SQLite. The only public service. |
| Frontend | Static files inside the gateway image | Nuxt, built with nuxt generate. |
| Chapter service | One Deployment or Job per chapter | Behaves healthy, not-ready, crashing, or completed, set by env. |
| Delivery | Gitea Actions on the home server | Test, scan, build, push, deploy, version. |
| FreeLens | Noel's laptop | Admin UI for the cluster over an SSH tunnel. Not part of the public site. |
Everything runs in one namespace: cv, capped at 384Mi memory in total, on a
2 vCPU, 4 GB server shared with Gitea. A machine with more RAM is planned
before 0.3.0, because the kubeadm control plane costs more than k3s did. See
server budget.
Images
Two images from one Go module:
cmd/gateway → image `gateway` (includes the Nuxt build)
cmd/chapter → image `chapter`
Flow: page load
- Visitor opens the apex domain. DNS points at the home server. Caddy (automatic HTTPS) forwards to the gateway Service.
- Gateway returns prerendered Nuxt HTML. The first screen works without JavaScript.
- The page opens
GET /api/events(SSE) and receives the current state of every chapter, then every change.
Flow: knockdown
- Visitor clicks "Push this chapter":
POST /api/fall/{chapter}. - Gateway checks the allowlist, the per-chapter cooldown, and the global rate limit.
- Gateway calls
http://chapter-{chapter}.cv.svc/fallover cluster DNS. - The chapter process exits. The kubelet restarts it,
restartCountgoes up. - Gateway sees the pod go not-ready, then ready again, and pushes both changes over SSE.
- Recovery time = Ready condition
lastTransitionTimeminus the fall time. - The page shows the story card with the measured seconds.
No visitor-facing step needs write access to the Kubernetes API.
Security boundaries
- Only the gateway is reachable from outside.
- Gateway ServiceAccount:
get/list/watchon pods, events and jobs incv. Nothing else. /fallis unauthenticated inside the cluster. A NetworkPolicy (Calico) restricts it to the gateway.- No visitor-supplied input reaches the cluster except a chapter name checked against an allowlist.
- Only Noel holds a kubeconfig. The API server listens on localhost; FreeLens reaches it through an SSH tunnel. See FreeLens.
Accepted risk
If the home server is down, the whole site is down. See accept downtime in v1.