cabbagecluster

A highly reliable, self-hosted Kubernetes home lab built with Talos Linux and managed via private remote operations through Tailscale.

Documentation Index

• Project Specification: Purpose, goals, and constraints.
• Documentation Hub: Index of architecture, operations, and runbooks.
• Architecture Overview: Topology, networking, and storage design.
• Bootstrap Sequence: How to build the cluster from scratch.
• Full Cluster Rebuild: Zero-node rebuild and restore using GitHub, encrypted secrets, and B2.
• Talos Lifecycle: Upgrade, drift-check, and health verification workflow.
• OpenClaw Cluster Gateway: In-cluster OpenClaw setup and operations.
• Monitoring And Alerting: Prometheus, Alertmanager, Grafana, and OpenClaw health checks.
• Postgres Platform: CloudNativePG platform pattern, Forgejo DB cutover, and restore model.
• Forgejo Actions Backup CI: Backup Forgejo workflow contract, package bootstrap, and image publication path.
• Desktop Node Setup: Run OpenClaw on your desktop, connected to the cluster.

Repository Structure

• clusters/: Flux cluster definitions and entrypoints.
  • clusters/cabbagecluster/inventory.yaml: Canonical cluster identity, node names, and management IP inventory.
  • clusters/cabbagecluster/recovery.yaml: Canonical protected PVC and rebuild-empty recovery inventory.
• kubernetes/:
  • base/: Shared infrastructure components (metrics-server, local-path-provisioner, tailscale-operator).
  • apps/: Workload definitions (Forgejo, OpenClaw gateway, media, etc.).
• infrastructure/: Config templates and runtime files for non-Kubernetes infrastructure.
  • infrastructure/openclaw/desktop-node/: OpenClaw node config and systemd service templates.
• talos/: Talos Linux machine configurations and patches.
• secrets/: Encrypted SOPS secrets (requires age key to decrypt).
• .artifacts/runtime/: Ignored local runtime outputs such as decrypted Talos patches and talosconfig.
• scripts/: Automation for bootstrap, reset, maintenance, and desktop node setup.
  • scripts/desktop-node/: OpenClaw desktop node installation scripts.
  • scripts/dr/: Zero-node rebuild, B2 rehydrate, and workload restore helpers.

Quick Start

1. Ensure prerequisites are met: ./scripts/check-prereqs.sh
2. Decrypt local secrets: ./scripts/decrypt-secrets.sh
3. Bootstrap the cluster: ./scripts/bootstrap-cluster.sh --controlplane-node <IP> --worker-node <IP> ...
4. Bootstrap Flux: ./scripts/bootstrap-flux.sh

Security & Reliability

• All management and service exposure is restricted to the Tailscale tailnet.
• Nodes are managed with Talos Linux for a minimal attack surface and immutable operations.
• GitOps-driven reconciliation via Flux.
• OpenClaw runs as a private, Tailscale-only in-cluster gateway.
• Desktop nodes can connect to the cluster gateway for remote operations and agent execution.

Desktop Node Integration

Run OpenClaw as a daemon on your Fedora desktop to enable remote task execution through the cluster gateway.

Quick Start:

# Get gateway token from cluster secret
export OPENCLAW_GATEWAY_TOKEN="<token-from-cluster>"

# Run automated setup
cd ~/git/cabbagecluster
sudo -E bash scripts/desktop-node/install-huginn.sh

See Desktop Node Setup for complete guide.