K8s Homelab Knowledge Base¶
This directory is the operational source of truth for the homelab platform. It complements the repository workflow described in WORKFLOW.md and turns GitOps changes into durable, reviewable knowledge.
Documentation model¶
| Layer | Purpose | Primary audience | Required artifacts |
|---|---|---|---|
| Governance | Operating model, versioning, change approval, documentation rules | Platform owners | Blueprint, change-management policy, roadmap |
| Architecture layers | Shared platform design by technical domain | DevOps and platform engineering | Layer pages for infrastructure, cluster management, networking, storage, and applications |
| Service catalogue | Deployment-specific facts for each top-level workload | Operators and maintainers | One page per service using the application template |
| Runbooks | Repeatable response procedures for operations and incidents | On-call and maintainers | One runbook per operationally critical, recovery-sensitive, or security-sensitive service |
| Change history | Auditable record of platform changes | Reviewers and operators | changelogs/fragments plus generated root CHANGELOG.md |
Working rules¶
- Documentation lives in Git and changes in the same pull request as the manifests they describe.
- Every top-level deployment directory should eventually have a matching page under docs/services/.
- Every changed top-level deployment directory should have a useful local README.md that points at the matching service page and, when relevant, the runbook.
- Tier 0 or Tier 1, security-sensitive, shared stateful, or recovery-critical services also require a dedicated runbook under docs/runbooks/.
- Platform-level release notes are authored as antsibull fragments under changelogs/fragments/ and rendered to the root CHANGELOG.md.
- Documentation is reviewed with the same branch strategy already defined for GitOps changes: feature branch to dev, then dev to main.
Current coverage¶
As of 2026-07-02, the source docs contain 26 service pages and 23 runbooks. The validation script enforces all existing service pages and runbooks, while the remaining work is backfilling uncovered deployment directories and legacy/manual manifest areas.
Start here¶
- Read the platform blueprint for the target architecture and governance model.
- Use the change-management guide before recording upgrades, migrations, or hotfixes.
- Follow the implementation roadmap to prioritize service coverage.
- Create new service pages and runbooks from the standard templates.