Document contract
- Role: learning-system audit
- Scope: comprehension, reconstruction, evidence, learning mechanics, and certification-aligned breadth
- Truth boundary: repository audit and official certification domains observed on the audit date
- Last verified: 2026-07-26
This audit treats the vault as a system for a future human operator, not as storage for generated answers. The tests are whether someone can understand what was built, explain why, transfer the underlying concepts, and reconstruct useful behavior later.
Prerequisites: start-here, devata-system-map
Kubernetes certification domains are used as a breadth benchmark. They are not the purpose of the homelab, and a missing kubeadm lab should not force a Talos cluster to adopt kubeadm. The useful question is which transferable skill the benchmark reveals as missing.
Baseline: 5/10
The pre-overhaul vault was a strong archive of selected engineering work but not a coherent learning and reconstruction system.
| Dimension | Before | Evidence |
|---|---|---|
| Understand what was built | 5/10 | deep subsystem chapters, but no current whole-platform map |
| Understand why | 8/10 | strong tradeoffs, failure boundaries, and rejected alternatives |
| Learn concepts | 5/10 | strong GitOps, Cilium, observability, and incidents; shallow core workload, control-plane, storage, and security coverage |
| Reconstruct later | 4/10 | no end-to-end order; several historical chapters contradicted current state |
| Evidence boundaries | 6/10 | recent case studies were rigorous; older walkthroughs presented dated state as current |
| Learning mechanics | 5/10 | the Loki case used recall and proof well; most notes stopped after explanation and commands |
| References | 8/10 | many primary sources, but inconsistent links to exact implementation evidence |
Quantitatively, the repository had 71 Markdown files and about 75,000 words. Planning held roughly 46 percent of the prose. The public homepage exposed only nine entry articles. Reusable concepts had strong prerequisite linking, but only two durable notes used explicit recall or checkpoint sections. Diagram coverage was concentrated in observability and one storage case study. The repository README was still Quartz upstream text, and Talos, the defining OS choice, was an unpublished stub.
The largest risk was truth drift. GitOps pages still described an imperative cluster and three Argo applications. The bare-metal case study correctly recorded Longhorn as future work at its conclusion, but no current page explained that Longhorn, workload migration, and Velero were later completed.
What this overhaul changes
- a learner-oriented front door and explicit read, observe, explain, reconstruct loop;
- a durable architecture page connecting every control, trust, data, and recovery plane;
- an ordered reconstruction contract with gates and end-to-end proof;
- a complete Talos foundation and deeper Kubernetes controller model;
- a human concept map independent of physical file placement;
- dated-state banners and current-successor links on historical GitOps and storage chapters;
- a real repository README and authoring contract;
- diagrams distributed across foundations, architecture, recovery, and learning paths;
- a structural checker for dictionary targets, published stubs, and required metadata on system-level pages.
After this overhaul: 7.5/10
| Dimension | Before | After | Why it is not higher |
|---|---|---|---|
| Understand what was built | 5 | 9 | current architecture exists, but several components still need their own as-built chapters |
| Understand why | 8 | 9 | historical decisions are strong; some current choices lack ADR-linked explanations |
| Learn concepts | 5 | 7 | core platform model is clearer, while important Kubernetes and security topics remain absent |
| Reconstruct later | 4 | 7 | the order and proof contract exist, but a complete empty-site rebuild is not yet proven |
| Evidence boundaries | 6 | 8 | document roles and dated banners reduce drift; metadata is not yet consistent across every older note |
| Learning mechanics | 5 | 7 | start paths and recall improve, but older concept notes still need exercises and explain-back prompts |
| References | 8 | 8 | primary references remain good; more commit-pinned lab evidence would improve durability |
The score is intentionally below 8 until the reconstruction path has been exercised as a whole. Documentation can make a rebuild legible, but only a restore proves it.
CKA benchmark
The current CKA domains are architecture, installation and configuration; workloads and scheduling; services and networking; storage; and troubleshooting.
| Domain | Weight | Vault assessment after overhaul | Highest-value remaining gap |
|---|---|---|---|
| Architecture, installation, configuration | 25% | partial | control-plane recovery lab, upgrades, HA comparison, CRI and CSI ownership |
| Workloads and scheduling | 15% | weak | Deployments, rollouts, probes, requests, limits, affinity, taints, autoscaling |
| Services and networking | 20% | strongest | NetworkPolicy and systematic DNS failure drills; Gateway API and TLS now have a live lab |
| Storage | 10% | partial with strong real incidents | StorageClass mechanics, access modes, reclaim policies, dynamic provisioning lab |
| Troubleshooting | 30% | deep but narrow | repeatable node, control-plane, workload, scheduling, and network drills |
The vault is deeper than certification level in selected Cilium, GitOps, Loki, and storage incidents. It is much narrower than the benchmark across ordinary workload operations.
CKAD benchmark
The current CKAD domains expose a different gap: this platform documentation says little about building and operating applications on top of the cluster.
- Application design and build: init containers, multi-container patterns, Jobs, and image construction are thin or absent.
- Application deployment: rollout, rollback, Helm application delivery, and API deprecation need hands-on labs.
- Observability and maintenance: metrics and logs are strong, but probes and application debugging need coverage.
- Environment, configuration, and security: ConfigMaps and Sealed Secrets are present; SecurityContext, quotas, service accounts for apps, and resource policy remain weak.
- Services and networking: Services are strong; NetworkPolicy and application exposure policy are missing.
CKS benchmark
The current CKS domains show the largest breadth gap. Talos reduces the mutable-node attack surface and Sealed Secrets protects committed credentials, but those choices do not constitute a complete security curriculum.
Missing or thin areas include:
- cluster hardening and API exposure review;
- Pod Security Standards, SecurityContext, capabilities, seccomp, and workload isolation;
- NetworkPolicy and admission controls;
- image provenance, signing, scanning, SBOMs, and supply-chain policy;
- audit logs and runtime threat detection;
- a documented incident path for credential compromise.
Prioritized next closures
- Workloads and scheduling grounded in the real
helloand platform workloads. - Current Longhorn plus Velero architecture, migration, failure domains, and restore proof.
- NetworkPolicy and systematic DNS failure drills. Gateway API and TLS are now covered by tracing-lan-tls-through-cilium-gateway.
- Control-plane and etcd recovery in a disposable Talos cluster.
- Upgrade rehearsal with explicit version-skew and rollback gates.
- Security boundaries, workload hardening, supply-chain controls, and audit evidence.
- A complete destructive reconstruction game day using this runbook.