Skip to content

Module Template#

Every deep module uses the same layout, so readers always know where to find the theory, the reasoning, the code, and the proof.

<module>/
├── index.md             what it is, why it matters, where it sits in the stack
├── concepts.md          how it works
├── design.md            trade-offs, decision records, "when to use X vs Y"
├── implementation.md    walkthrough of the manifests and scripts
├── testing.md           how to prove it works, with expected output
├── troubleshooting.md   failure modes and the diagnostic path
├── diagrams/            Mermaid or draw.io sources plus exported SVG
├── manifests/           Kubernetes YAML, Helm values, Kustomize overlays
└── scripts/             install, verify and test scripts

Front matter#

---
title: GPU Operator
layer: cp                # 1-9, storage, cp, or a list; drives the layer bar
maturity: implemented    # concept | implemented | lab-tested | gpu-validated
stub: true               # optional; marks outline-only pages
---

Script conventions#

  • Each script opens with a header stating READ-ONLY or CHANGES CLUSTER.
  • Scripts that change state print what they will change and ask for confirmation (skip with AUTO_APPROVE=1).
  • Long waits print a progress indicator, so a slow step is distinguishable from a hang.
  • Versions come from a pinned versions.env, never latest.