Files
OKF_CV_Website/knowledge/architecture/chapter-service.md
T

1.8 KiB

type, title, description, tags, status, generated
type title description tags status generated
Service Chapter service One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
architecture
go
k3s
stable
by at
claude-code/claude-opus-5-5 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.
  • Tight resource limits on every chapter (for example 10m CPU, 16Mi memory). 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.