Cluster Management Layer

Scope

The cluster-management layer explains how the homelab is controlled, promoted, and reconciled. This is where operators should look to understand GitOps ownership, cluster registration, branch strategy, and namespace governance.

Components that belong here

• fleet for primary GitOps deployment to managed clusters
• argocd for the alternate GitOps controller branch
• rancher for cluster administration and Fleet visibility
• devtron or other higher-level delivery tooling when it controls deployment behavior

Mandatory topics

• Branch promotion path from feature to dev to main
• Which controller is authoritative for each cluster or branch
• How clusters are onboarded into Fleet or other GitOps controllers
• Namespace ownership and responsibility model
• Secret-management boundaries and what is committed versus injected at runtime
• How to pause, resume, or safely override reconciliation during incidents

Required artifacts

• Control-plane component map
• Cluster-to-controller matrix
• Namespace model and ownership table
• Emergency GitOps bypass guidance
• Rollback model for failed promotions

Operational questions this layer must answer

1. Which branch change will reach which cluster?
2. Where is the first place to look when reconciliation fails?
3. How is drift handled after a manual emergency action?
4. What must be restored first after a control-plane outage?