Cluster Management¶

Documentation for Kubernetes cluster configuration, GitOps setup, and cluster-level components.

🚀 Cluster Components¶

Flux System — GitOps controller for declarative cluster management
K3s Config — K3s Kubernetes distribution configuration
Local Cluster — Development cluster setup
Production Cluster — Production environment configuration

🏗️ Architecture Overview¶

┌─────────────────────────────────────────┐
│       Kubernetes Cluster (k3s)          │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────────────────────────┐  │
│  │    Flux System (GitOps)          │  │
│  │  - Monitors git repository       │  │
│  │  - Reconciles cluster state      │  │
│  │  - Auto-deploys on changes       │  │
│  └──────────────────────────────────┘  │
│                 │                       │
│                 ├─► Infrastructure     │
│                 ├─► Applications       │
│                 └─► Configurations     │
│                                         │
└─────────────────────────────────────────┘

📋 Cluster Environments¶

Local Development¶

Single-node or multi-node k3d cluster
Faster iteration and testing
Local storage
No HA requirements

Production¶

Multi-node k3s cluster
High availability setup
Remote storage (Longhorn/SAN)
Observability and monitoring
Backup and recovery procedures

🔄 GitOps Workflow¶

Write Manifests — Create/update YAML in git
Commit to Repository — Push changes
Flux Detects — Within ~1 minute
Reconciliation — Cluster state updated
Observe — Check status and results

🛠️ Key Management Tasks¶

Installing Flux¶

flux bootstrap github \
  --owner=<username> \
  --repo=homelab \
  --path=clusters/production

Viewing Cluster Status¶

flux get all
kubectl get nodes
kubectl get all -A

Manual Reconciliation¶

# Reconcile Flux
flux reconcile all --with-source

# Apply specific manifest
kubectl apply -k apps/production

📊 Cluster Topology¶

Cluster	Nodes	Storage	HA	Purpose
Local	1-3	Local	No	Development
Production	3+	Longhorn	Yes	Production

🔐 Security¶

Pod Security Standards
Network Policies
RBAC (Role-Based Access Control)
Sealed Secrets for sensitive data
Regular security updates

📚 Configuration & Customization¶

See individual component documentation: - Flux System — GitOps configuration - K3s Config — Kubernetes settings - Local Cluster — Development environment - Production Cluster — Production setup

🚨 Troubleshooting¶

Check Flux Status¶

flux logs --all-namespaces --follow

Verify Kustomizations¶

kubectl get kustomizations -A
kubectl describe kustomization apps-local

View Event Logs¶

kubectl describe pod <pod-name> -n <namespace>