From 15e55b99277a23dbe349a3f7bd80748b76c74336 Mon Sep 17 00:00:00 2001
From: File Magic <file_magic@protonmail.com>
Date: Fri, 17 Jul 2026 18:17:28 -0400
Subject: [PATCH] README.md [kubernetes/]: rewrite for Makefile-driven workflow

---
 kubernetes/README.md | 110 +++++++++----------------------------------
 1 file changed, 22 insertions(+), 88 deletions(-)

diff --git a/kubernetes/README.md b/kubernetes/README.md
index 8a48d55..0e7f86e 100644
--- a/kubernetes/README.md
+++ b/kubernetes/README.md
@@ -1,7 +1,7 @@
 # Kubernetes Cluster on NixOS + KVM/QEMU
 
 4-node cluster (1 master + 3 workers) managed by OpenTofu.
-Cilium CNI + Rook-Ceph storage (post-bootstrap).
+Cilium CNI + Rook-Ceph storage.
 
 ## Prerequisites
 
@@ -9,120 +9,54 @@ Cilium CNI + Rook-Ceph storage (post-bootstrap).
 - `libvirtd` running (`systemctl status libvirtd`)
 - OpenTofu 1.12+
 
-## Validate
+## Quick Start
 
 ```bash
 cd kubernetes
-nix flake check
+make up
 ```
 
-## Build Images
+This runs the full lifecycle: build images → deploy VMs → wait for SSH → install Cilium + Rook-Ceph → verify cluster health.
 
-```bash
-cd kubernetes
-
-# Build all 4 images at once
-nix build .#images
-
-# Output: /nix/store/...-k8s-images/
-# Contains: k8s-master-0.qcow2, k8s-worker-{0,1,2}.qcow2
-```
-
-The `result` symlink points to the build output.
-
-## Deploy VMs
-
-```bash
-cd kubernetes/tofu
-
-# First time only
-tofu init
-
-# Preview
-tofu plan \
-  -var "ovmf_code_path=$(nix eval --raw nixpkgs#OVMF.fd)" \
-  -var "image_dir=../result"
-
-# Create network + VMs
-tofu apply -auto-approve \
-  -var "ovmf_code_path=$(nix eval --raw nixpkgs#OVMF.fd)" \
-  -var "image_dir=../result"
-```
-
-## Wait for Boot + SSH In
+See `docs/resume-state.md` for all Makefile targets and options.
 
-```bash
-# Wait ~60s after tofu apply, then SSH into master
-SSH_KEY="$PWD/../ssh-key"
-SSH_AUTH_SOCK= ssh -i "$SSH_KEY" root@192.168.122.10
-```
+## What `make up` Does
 
-> **Note:** Bitwarden SSH agent blocks key auth. Always prefix with `SSH_AUTH_SOCK=` when using `-i`.
+1. **Build images** — `nix build .#images` creates QCOW2 images for all 4 nodes
+2. **Deploy VMs** — `tofu destroy` + `tofu apply` creates libvirt VMs from images
+3. **Wait for SSH** — Polls master until SSH is available
+4. **Install Cilium** — CNI with eBPF masquerade (replaces kube-proxy)
+5. **Install Rook-Ceph** — Storage operator, CephCluster, CSI driver, StorageClass
+6. **Verify** — Asserts all pods Running, all services Ready
 
-## Verify Master
+## SSH into Master
 
 ```bash
-# On master-0
-systemctl is-active kube-apiserver kubelet etcd
-ss -tlnp | grep 6443   # apiserver
+make ssh
 ```
 
-Workers automatically register once they can reach the master API server on port 6443.
-
-## Distribute Worker Certificates
-
-Workers need the cfssl API token from master to fetch their certificates:
-
-```bash
-# Get token from master
-SSH_AUTH_SOCK= ssh -i "$SSH_KEY" root@192.168.122.10 \
-  "cat /var/lib/kubernetes/secrets/apitoken.secret"
-
-# Distribute to each worker (replace TOKEN with actual value)
-for ip in 192.168.122.11 192.168.122.12 192.168.122.13; do
-  SSH_AUTH_SOCK= ssh -i "$SSH_KEY" root@$ip \
-    "echo '<token>' > /var/lib/kubernetes/secrets/apitoken.secret"
-  # certmgr will fetch certs and kubelet/kube-proxy will start
-done
-```
+> **Note:** Bitwarden SSH agent blocks key auth. The Makefile handles this with `IdentityAgent=none`.
 
 ## Verify Cluster
 
 ```bash
-# On master-0
-export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig
-kubectl get nodes -o wide
-# All 4 nodes should appear (NotReady until Cilium is installed)
+make verify
 ```
 
-## Install Cilium CNI
+## Clean Up
 
 ```bash
-# On master-0
-export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig
-
-helm repo add cilium https://helm.cilium.io/
-helm repo update
-
-helm install cilium cilium/cilium --version 1.16.5 \
-  --namespace kube-system \
-  --set kubeProxyReplacement=true
-
-# Wait ~30s, then verify
-cilium status
-kubectl get nodes -o wide   # All should be Ready
+make down
 ```
 
-## Destroy VMs
+## Environment Variables
 
 ```bash
-cd kubernetes/tofu
-tofu destroy \
-  -var "ovmf_code_path=$(nix eval --raw nixpkgs#OVMF.fd)" \
-  -var "image_dir=../result"
+CLUSTER_INDEX=1 make up   # Different cluster subnet (default: 0)
+WORKER_COUNT=5 make up    # More workers (default: 3)
 ```
 
-## Test Single Node (QEMU)
+## Single Node Testing (QEMU)
 
 ```bash
 cd kubernetes
-- 
2.51.2