cabbagecluster

The "cabbagecluster" is my attempt at spinning up high-fidelity home infrastructure without the headache of full-scale commercial cloud management. It's a k0s-based homelab Kubernetes cluster, managed strictly via GitOps (Flux), tunneled through Tailscale for sanity, and designed with one primary goal: making sure I can actually rebuild the whole damn thing from code if I have to.

Where to start?

Feeling lost in the directory structure is part of the experience, but here's how to find your way back depending on what you’re trying to do right now:

Task	Read first	Then read
"What is this thing?"	PROJECT_SPEC.md	docs/architecture/cluster-overview.md
"I want to build it."	docs/operations/pre-bootstrap-checklist.md	docs/operations/bootstrap-sequence.md
"Everything crashed."	docs/runbooks/full-cluster-rebuild.md	docs/runbooks/disaster-recovery.md
"I need my data back."	docs/runbooks/disaster-recovery.md	docs/operations/postgres-platform.md
"Where is everything?"	AGENTS.md (Repository layout)	docs/README.md

The Cluster (The Topology)

I've named the nodes as best I could to reflect their roles:

• skragg: The brain. This handles the control plane and does all the thinking.
• grubnuk: Muscle & Storage. Worker with local disks and an Intel GPU for handling the heavy lifting.
• mugruk: Mirror muscle/storage. Basically a twin to grubnuk, rounding out our throughput with another Intel GPU.
• muninn: The Media Beast. Dedicated to media workflows; it carries its own muninn-local storage plus both Intel and NVIDIA GPUs because why not?

Traffic stays tidy over Tailscale. We keep the desired state in clusters/ and kubernetes/, while all secrets are tucked away in secrets/.

Note on Env: If you use direnv, .envrc keeps a paranoid watch on .artifacts/. It’ll yell at your terminal if things like .artifacts/kubeconfig vanish—which they will eventually do.

How to navigate this repo

• clusters/cabbagecluster/: The Flux entrypoints and node inventory. This is the "on" switch for the cluster.
• kubernetes/base/: The foundation—shared infra, storage definitions, and the stuff that doesn't change often.
• kubernetes/apps/: Where the actual workloads live (the fun stuff).
• secrets/kubernetes/: SOPS-encrypted secrets (don't peek at these in plaintext unless you want to feel uncomfortable).
• scripts/: Homemade helper scripts for bootstrapping, restores, validation, and general ops.
• docs/: The source of truth. Seriously, read these before poking things.

Core Commands

1. Check if we're sane (Prerequisites)

./scripts/check-prereqs.sh --mode bootstrap

Look for: prereqs-ok

2. Pull the "Keys" from the vault

./scripts/decrypt-secrets.sh --force

This writes local runtime secrets to .artifacts/runtime/.

3. The Big Bang (Bootstrap)

./scripts/bootstrap_cluster.py

Generates artifacts, triggers k0sctl, and spits out a new .artifacts/kubeconfig.

4. Activate Flux

./scripts/bootstrap-flux.sh --kubeconfig .artifacts/kubeconfig

This turns on the Flux controllers and starts reconciling your Git state into reality.

5. Before you push

pre-commit install
./scripts/validate-repo.sh
uv run pytest tests/ -q

GitHub validation is manually triggered; the Forgejo mirror runs on pushes and pull requests.

The Documentation Index

• Project Spec - The Why
• Docs Index - The Map
• AGENTS.md - Rules for AI agents (and a decent cheat sheet for humans)
• Cluster Overview - High-level view
• Bootstrap Sequence - The How
• k0s Lifecycle - Managing the core
• Full Cluster Rebuild - The scorched earth policy
• Disaster Recovery - For when things get real