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

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, k3s]
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.
- 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.