Initial commit

docs/PHASE1_NODE_PLACEMENT_RUNBOOK.md

@@ -0,0 +1,108 @@
+# Phase 1 Node Placement Runbook
+
+This runbook matches the manifest changes in this repository.
+
+## Goal
+
+Separate Kubernetes workloads into two planes:
+
+- app plane for public-facing services
+- worker plane for async NATS consumers
+
+## Required node labels
+
+Apply these labels to your nodes.
+
+### App nodes
+
+```powershell
+kubectl label node <app-node-1> node-role.workolik/app=true
+kubectl label node <app-node-2> node-role.workolik/app=true
+```
+
+### Worker nodes
+
+```powershell
+kubectl label node <worker-node-1> node-role.workolik/worker=true
+kubectl label node <worker-node-2> node-role.workolik/worker=true
+```
+
+## Recommended taints
+
+These taints keep worker jobs away from app nodes and allow only matching workloads onto the correct plane.
+
+### Worker nodes
+
+```powershell
+kubectl taint node <worker-node-1> dedicated=workers:NoSchedule
+kubectl taint node <worker-node-2> dedicated=workers:NoSchedule
+```
+
+### App nodes
+
+```powershell
+kubectl taint node <app-node-1> dedicated=apps:NoSchedule
+kubectl taint node <app-node-2> dedicated=apps:NoSchedule
+```
+
+## What the updated manifests now expect
+
+### Worker plane
+
+These workloads now require worker-node placement:
+
+- [`manifests/core/workers.yaml`](E:/Birock/kubernetes/manifests/core/workers.yaml)
+- [`manifests/core/worker-statefulset.yaml`](E:/Birock/kubernetes/manifests/core/worker-statefulset.yaml)
+
+They now use:
+
+- required node affinity for `node-role.workolik/worker=true`
+- toleration for `dedicated=workers:NoSchedule`
+- pod anti-affinity
+- topology spread constraints
+
+### App plane
+
+These workloads now require app-node placement:
+
+- [`manifests/alaska/alaska.yaml`](E:/Birock/kubernetes/manifests/alaska/alaska.yaml)
+- [`manifests/nearle/nearle-ariane.yaml`](E:/Birock/kubernetes/manifests/nearle/nearle-ariane.yaml)
+- [`manifests/nearle/nearle-atlantis.yaml`](E:/Birock/kubernetes/manifests/nearle/nearle-atlantis.yaml)
+- [`manifests/nearle/nearle-fiesta.yaml`](E:/Birock/kubernetes/manifests/nearle/nearle-fiesta.yaml)
+- [`manifests/nearle/nearle-jupiter.yaml`](E:/Birock/kubernetes/manifests/nearle/nearle-jupiter.yaml)
+- [`manifests/nearle/nearle-titan.yaml`](E:/Birock/kubernetes/manifests/nearle/nearle-titan.yaml)
+
+They now use:
+
+- required node affinity for `node-role.workolik/app=true`
+- toleration for `dedicated=apps:NoSchedule`
+- pod anti-affinity
+- topology spread constraints
+
+## Safe rollout order
+
+1. Label nodes.
+2. Taint nodes.
+3. Confirm labels and taints:
+
+```powershell
+kubectl get nodes --show-labels
+kubectl describe node <worker-node-1>
+kubectl describe node <app-node-1>
+```
+
+4. Apply manifests.
+5. Watch rescheduling:
+
+```powershell
+kubectl get pods -A -o wide
+```
+
+## Important warning
+
+Do not apply these manifests until your cluster has at least:
+
+- one labeled app node
+- one labeled worker node
+
+If the labels do not exist yet, pods with required node affinity will stay Pending.