The Assignment
The Assignment
The Situation
Chapter 18 built display names behind a flag: every release since writes the name a user registers with, and FEATURE_DISPLAY_NAME decides whether sign-up and sign-in return it. Chapter 18’s lab switched it on in develop and off again; staging and production have never had it. The product team now wants it for everyone - staging this week, then production.
The change is yours. You are not alone in the repository: a colleague is cleaning things up at the same time, and their pull requests pass the same checks as yours. At the end of the week someone else takes the platform over, and all they will have is what you write down.
Goal
Display names on in staging, then in production: a user who signs up with a display name gets it back when signing in - in each environment, proven on the users’ path.
Constraints
- Everything through Git. A branch, a pull request, its checks, a merge - and Flux applies it. Read anything you like;
flux reconcileto make Flux look now is fine. Nokubectl apply,edit,patch,setorrollout restarton what Flux manages: Flux would undo it, and the next person would not know it happened (Chapter 03). A Kustomization you suspend is resumed before you finish. - Staging first. Production changes only after staging is proven on the users’ path - and production gets the same change, not a different one. An environment whose release is older than Chapter 18’s flag fix gets the newer release first, the Chapter 10 way: the image tested in staging, by digest, never rebuilt.
- No guardrail switched off. No PolicyException, no NetworkPolicy wider than the one path it is for, no check skipped or disabled. If a guardrail is in the way, it is telling you something.
- One failure domain per pull request. Changes that can fail on their own go into separate pull requests - one that changes two such things cannot be reverted for one of them. Changes that cannot work without each other go together, with one way back (Chapter 01).
- Your AI agent may help - under the rules of
docs/agent-rules.mdAdvanced, and what it proposes, you decide (Chapter 14). - kind only. Nothing on Hetzner.
Acceptance Criteria
make capstone-check checks the first seven against Git and the running cluster - its 7 of 7 proven. is criteria 1-7, not the whole capstone. Criteria 8-10 are in the handover, for a reader to judge.
| # | Criterion | Checked by |
|---|---|---|
| 1 | Flux applies origin/main: every Kustomization Ready on that revision, none suspended | make capstone-check |
| 2 | Display names in staging: the rollout is complete, the pods get the flag, the release reads it | make capstone-check, and the users’ path below |
| 3 | Display names in production - the same, after staging | make capstone-check, and the handover: staging’s proof on the users’ path is older than production’s merge |
| 4 | The colleague’s change is fixed in every environment - through Git | make capstone-check, and the handover: symptom, evidence, cause, fix |
| 5 | No guardrail switched off: no PolicyException, every enforcing admission policy still denies, default-deny-all in every application namespace, no egress rule open to any destination or port | make capstone-check checks the state now; the way there - switched off and back on, a rule wider than its one path - is in the handover and git log |
| 6 | The platform passes its smoke test | make capstone-check |
| 7 | The handover is on main, every placeholder replaced | make capstone-check, and a reader |
| 8 | On the users’ path, in staging and in production: five sign-ups with a display name, then a sign-in that returns it - every request succeeds (201, then 200), each in under a second | the handover: the probe’s output, with status, time and when it ran |
| 9 | The AI agent’s proposal is decided, with a reason grounded in evidence or a rule | the handover |
| 10 | Beyond this platform: for another team’s manifest (the lab’s C1), what can break, what you would check first, and the smallest change to make first - each with its reason | the handover |
Each criterion ends proven, proven with a hint or not proven yet (the chapter page explains the three). Criterion 8 is the one that matters most and the only one no script can give you: a green rollout is the platform’s opinion; a sign-in that returns the name in under a second is the user’s.
What You Get
make capstone-fault- the colleague’s pull request, merged in your repository. It does not say what it changed.make capstone-check- criteria 1-7, eachPROVENorNOT PROVEN YETwith what is missing. Run it as often as you like; it changes nothing but a short-lived smoke-test pod.docs/handover-template.md- the handover’s structure.- The lab’s hints - closed until you open one. Open one when you are stuck; write down which.
What You Do Not Get
Commands for the change, the diagnosis or the fix. The flag’s path is Chapter 18’s lab; what Flux does with a change, Chapter 03; how to find what is wrong without guessing, the runbooks of Chapters 15-22. If you catch yourself changing things to see what happens, stop and write down what you know and what you are assuming - that is the handover’s first draft anyway.