Learning bite
Documentation and support boundaries
Write a small operating guide that lets a learner start, diagnose, resume, and stop a lab.
On this page
A runbook is a decision aid
A runbook is a short operating procedure for a known task or symptom. It should say when it applies, what to inspect, how to interpret the result and when to stop. A list of commands without those decisions leaves the reader guessing.
Keep start, resume and reset separate. Starting an empty lab creates dependencies; resuming should preserve the existing data; resetting deliberately removes selected state. A learner trying to resume should not accidentally follow a clean-install procedure.
Documentation is part of the interface
A platform should tell a developer what it supports and what happens outside that boundary. For this path, the supported runtime is the existing disposable local kind cluster. Cloud planning and portal scaffolding can be completed separately. On the 16 GB Mac, run only the components needed for the current exercise.
Write instructions in the order someone encounters the system: prerequisites, first request, expected result, common failure, recovery, and cleanup. Keep explanatory Markdown next to the configuration it describes. A screenshot of a successful run should supplement, not replace, the commands and evidence needed to repeat it.
Define resume behavior
“Start” should not delete old data. “Resume” must check the selected cluster, current controller owner, available images, dependency readiness, and saved case. “Reset” is a separate deliberate operation with a stated data-loss boundary. A fresh successful deposit is not proof that yesterday's data survived.
For the platform exercises, use the existing kind-microbank-advanced context and one active application owner. Stop optional local synthetic schedules before changing controller ownership. Record which local port-forwards need restarting after Pod replacement.
Read a small runbook before writing one
Use this paper exercise: a local change was merged, but the old Deployment annotation remains. No incident is being claimed; the observations below are an example to reason through.
| Check | Example observation | Interpretation and next step |
|---|---|---|
| Which Application owns Ledger? | The platform Application | Inspect that object; do not create a second one |
| Which revision does it request? | The earlier pinned commit | The merge alone cannot move a pinned revision |
| Is the new commit reviewed? | Checks and review refer to the merged commit | Propose updating the Application revision, then inspect its diff |
| Did sync finish? | Not yet requested | Use the lab's manual sync process |
| Did the annotation change? | Yes, images unchanged | Integration step worked; run the saved transaction check separately |
A useful stop condition is “The observed Application or namespace differs from the documented local target.” That is a reason to reconcile your notes, not to paste the command into another cluster.
Now write the same table for one actual failure you encountered. Include the command's context, expected observation and the point where you would ask for help. If you have not encountered it, label the procedure a rehearsal rather than a resolved incident.
Try it
Write a short runbook for one actual failure you observed previously. Include the symptom, two observations that distinguish likely causes, the smallest recovery action, and the same-case verification step. Add a fallback for portal unavailability: the reviewed Git and CLI workflow must remain available to the appropriate operator.
Review it without executing destructive actions. Could someone distinguish a stale status display, a failed controller sync, and a business transaction failure?
Checkpoint and revision
List what your platform supports today, what is an exercise, and what remains unimplemented. A runbook is a testable operating procedure; a roadmap is a statement of future work.
Compare your reasoning
If Git is unavailable but the Pods are still serving, preserve the healthy workload while repairing delivery access. If the data is missing, restoring Argo configuration is not enough. The runbook should lead the reader to the failing dependency rather than make every symptom a restart procedure.
Sources
Your notes and evidence
Record observations, questions, or links to your work. Keep credentials out of your notes.
Back up or restore this path
Progress and notes stay in this browser. A backup contains only this learning path.