From 950d01bc102d1d06d3d3c62402c6f55d9269072b Mon Sep 17 00:00:00 2001
From: File Magic <file_magic@protonmail.com>
Date: Fri, 17 Jul 2026 18:17:21 -0400
Subject: [PATCH] resume-state.md [kubernetes/docs/]: update cluster state and
 add Makefile documentation

---
 kubernetes/docs/resume-state.md | 79 +++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/kubernetes/docs/resume-state.md b/kubernetes/docs/resume-state.md
index 1b20020..6613555 100644
--- a/kubernetes/docs/resume-state.md
+++ b/kubernetes/docs/resume-state.md
@@ -80,3 +80,82 @@ $TOFU apply -auto-approve -var "image_dir=../result"
 $TOFU destroy -auto-approve && \
 $TOFU apply -auto-approve -var "image_dir=../result"
 ```
+
+## Makefile Usage
+
+The Makefile provides a complete lifecycle for managing the cluster. All targets are available via `make <target>`.
+
+### Quick Reference
+
+| Target | Description |
+|--------|-------------|
+| `make help` | Show available targets with descriptions |
+| `make up` | **Full lifecycle**: build images → deploy VMs → wait for SSH → run Ansible |
+| `make build` | Build NixOS VM images only |
+| `make deploy` | Destroy old VMs and create new ones from images |
+| `make down` | Destroy all VMs |
+| `make wait-ssh` | Wait for SSH on master (checks every 5s, 60 retries) |
+| `make ssh` | SSH into master node |
+| `make ansible` | Run full Ansible playbook (installs Cilium, Rook-Ceph, verifies) |
+| `make verify` | Run only the verification playbook |
+| `make lint` | Run all linters (nixfmt, tflint, ansible-lint, yamllint) |
+| `make fmt` | Format all files (nixfmt, tofu fmt) |
+
+### Environment Variables
+
+Override cluster configuration via environment variables:
+
+```bash
+# Deploy a different cluster index (default: 0)
+CLUSTER_INDEX=1 make up
+
+# Change worker count (default: 3)
+WORKER_COUNT=5 make up
+
+# Combine both
+CLUSTER_INDEX=2 WORKER_COUNT=4 make up
+```
+
+### Typical Workflows
+
+**Initial deployment:**
+```bash
+make up
+```
+
+**Rebuild after NixOS config changes:**
+```bash
+make up  # Full lifecycle rebuild
+```
+
+**Just verify cluster health:**
+```bash
+make verify
+```
+
+**SSH into master for debugging:**
+```bash
+make ssh
+```
+
+**Clean up when done:**
+```bash
+make down
+```
+
+**Before committing changes:**
+```bash
+make lint  # Check formatting and linting
+make fmt   # Auto-fix formatting issues
+```
+
+### Target Details
+
+- **`make up`** — The primary target. Chains: `build` → `deploy` → `wait-ssh` → `ansible`
+- **`make build`** — Runs `nix build .#images` to create QCOW2 images
+- **`make deploy`** — Runs `tofu destroy` then `tofu apply` with the built images
+- **`make ansible`** — Runs the full Ansible playbook which:
+  1. Waits for SSH on all nodes
+  2. Installs Cilium CNI with eBPF masquerade
+  3. Installs Rook-Ceph storage (operator, CephCluster, CSI, StorageClass)
+  4. Verifies cluster health (all pods Running, all services Ready)
-- 
2.51.2