diff --git a/AGENTS.md b/AGENTS.md index 2b4fe26b..442f9937 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,8 +61,10 @@ 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 +- KubeVirt hosts (`kubevirt-shoryu`/`shushou`/`youko`): avoid activations that restart the OVS + bridge units (`ovs-vswitchd`/`ovsbr1-netdev`) — that recreates the bridge and drops the VM + network. `switch` is fine for changes that don't touch the OVS/network stack; use `boot` + serial + reboot for nixpkgs/Open vSwitch or networking changes. 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. diff --git a/hosts/README.md b/hosts/README.md index ffeecd8d..4eab9cb9 100644 --- a/hosts/README.md +++ b/hosts/README.md @@ -111,21 +111,16 @@ Use existing hosts as templates. The key files typically include: ## 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. +The three KubeVirt hosts (`kubevirt-shoryu`, `kubevirt-shushou`, `kubevirt-youko`) carry the VM +network on the `ovsbr1` Open vSwitch bridge via `ovs-cni`. -- **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. +- `switch` is fine for changes that don't touch the OVS/network stack (e.g. journald or other + service settings). Deploy serially (`-p 1`) and re-check VM reachability afterwards. +- Use `boot` + a serial reboot when the change can restart the OVS units (`ovs-vswitchd` / + `ovsbr1-netdev`) — nixpkgs/Open vSwitch updates, `networking.vswitches` or `systemd.network` + edits, or any broad rebuild. Restarting them recreates the bridge and drops the VM ports. +- If a host loses VM networking, re-add the host-side veths (`ovs-vsctl add-port ovsbr1 `) or + reboot it. ## Distributed Building