From 68bea13405529048d940b3203babff1f696565b4 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sun, 20 Sep 2026 22:22:47 +0800 Subject: [PATCH] docs(kubevirt): document boot+reboot for KubeVirt hosts --- AGENTS.md | 3 +++ hosts/README.md | 18 ++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 16f502ff..2b4fe26b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,6 +61,9 @@ deployments. Keep repository guidance here; reusable global rules live in `agent - Deployment and upload recipes change systems; use eval/build commands for validation. Remote deployment requires an explicit request. When deployment behavior changes, report the exact `just` command to run. +- KubeVirt hosts (`kubevirt-shoryu`/`shushou`/`youko`): deploy with `boot` + serial reboot, never + `switch` — `switch` restarts the OVS bridge service and drops the VM network. See + [hosts/README.md](./hosts/README.md#deploying-kubevirt-hosts). - `just clean`, `just gc`, `just ggc`, and `just game` remove history or amend commits; they are not validation steps and require explicit authorization for their target and scope. - Do not use `just penvof` for process inspection: it can expose secret values. diff --git a/hosts/README.md b/hosts/README.md index 75b0a108..ffeecd8d 100644 --- a/hosts/README.md +++ b/hosts/README.md @@ -109,6 +109,24 @@ Use existing hosts as templates. The key files typically include: - **macOS systems**: See `darwin-fern/` for macOS configurations - **Apple Silicon**: See `12kingdoms-shoukei/` for ARM Linux setup +## Deploying KubeVirt Hosts + +The three KubeVirt hosts (`kubevirt-shoryu`, `kubevirt-shushou`, `kubevirt-youko`) run the KubeVirt +cluster and, through the `ovs-cni` plugin, carry the VM network on the `ovsbr1` Open vSwitch bridge. + +- **Deploy them with `boot`, then reboot — do not use `switch`.** `colmena apply switch` restarts + `ovs-vswitchd.service` and the generated `ovsbr1-netdev.service`; the latter runs + `ovs-vsctl del-br ovsbr1` on start/stop, which deletes the runtime ports added by `ovs-cni` and + cuts off every VM on the host. `boot` activates nothing, so the following reboot rebuilds the + bridge before the VMs start and the CNI re-adds the ports. + - `colmena apply boot --on '@virt-*' -p 1` + - Reboot the hosts **one at a time** (serial deployment and serial reboot both keep the k3s + control plane's etcd quorum), waiting for each host to become healthy before the next. +- `networking.vswitches` only models the static `interfaces`; it is unaware of the dynamic `ovs-cni` + ports, so any mid-flight restart of the bridge service is destructive. +- Recovery if a host ever loses VM networking after a `switch`: re-add the host-side veths + (`ovs-vsctl add-port ovsbr1 `) or simply reboot the host. + ## Distributed Building I usually run the build command on `Ai` and nix will distribute the build to other NixOS machines,