docs(okf): write overview, architecture, decisions and roadmap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
987a5efba1
commit
557ac1985b
20 files changed
+750
-16
No files matched your search
@@ -0,0 +1,45 @@
|
||||
---
|
||||
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.
|
||||
Reference in new issue
Block a user