Files
Noel Sabia e022c30527 feat(okf): run on full Kubernetes with FreeLens for admin
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
2026-10-24 19:02:17 +02:00

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.
architecture
kubernetes
go
nuxt
stable
by at
claude-code/claude-opus-5-5 2026-10-11T12:15:30Z

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

  1. Visitor opens the apex domain. DNS points at the home server. Caddy (automatic HTTPS) forwards to the gateway Service.
  2. Gateway returns prerendered Nuxt HTML. The first screen works without JavaScript.
  3. The page opens GET /api/events (SSE) and receives the current state of every chapter, then every change.

Flow: knockdown

  1. Visitor clicks "Push this chapter": POST /api/fall/{chapter}.
  2. Gateway checks the allowlist, the per-chapter cooldown, and the global rate limit.
  3. Gateway calls http://chapter-{chapter}.cv.svc/fall over cluster DNS.
  4. The chapter process exits. The kubelet restarts it, restartCount goes up.
  5. Gateway sees the pod go not-ready, then ready again, and pushes both changes over SSE.
  6. Recovery time = Ready condition lastTransitionTime minus the fall time.
  7. 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/watch on pods, events and jobs in cv. Nothing else.
  • /fall is 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.