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

46 lines
1.8 KiB
Markdown

---
type: Service
title: Chapter service
description: One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
tags: [architecture, go, kubernetes]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Behavior
| `MODE` | Runs as | `/healthz` (liveness) | `/ready` (readiness) | Resulting state |
|---|---|---|---|---|
| `healthy` | Deployment | 200 | 200 | Running, Ready |
| `not-ready` | Deployment | 200 | 503 | Running, NotReady |
| `crash` | Deployment | n/a | n/a | Exits on start: CrashLoopBackOff |
| `complete` | Job | n/a | n/a | Prints a line, exits 0: Completed |
`CHAPTER` env var names the chapter. Used in logs only.
# Endpoints
- `GET /healthz` - liveness.
- `GET /ready` - readiness, depends on `MODE`.
- `POST /fall` - responds 202, then `os.Exit(1)`. The kubelet restarts the container and increments `restartCount`.
# Kubernetes details
- Each chapter gets a Deployment (1 replica) and a Service `chapter-{name}`.
- Services set `publishNotReadyAddresses: true`, otherwise a NotReady chapter
has no endpoints and the gateway cannot push it.
- Label every pod `cv.noelsabia.dev/chapter: {name}`. The gateway uses it to map pods to chapters.
- Limits per chapter: 10m CPU, 16Mi memory, `GOMEMLIMIT=12MiB`. See [server budget](/architecture/server-budget.md).
Crashing chapters back off on Kubernetes' default schedule, which caps at 5 minutes.
- Completed Jobs keep no `ttlSecondsAfterFinished`, so they stay visible as Completed.
- A CrashLoopBackOff chapter cannot be pushed; it is already down. The UI shows its lesson card instead.
# Manifests
Plain YAML, one file per chapter, applied with `kubectl apply -k` (kustomize is
built into kubectl). Copy-paste per chapter is fine at this size.
# Size
About 50 lines of Go, standard library only.