46 lines
1.8 KiB
Markdown
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.
|
|
- 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.
|