docs(kubevirt): refine switch vs boot guidance

This commit is contained in:
Ryan Yin committed 2026-09-20 22:45:22 +08:00
1 parent 54016a9da2
commit 40b3786f14
2 files changed
+13 -16

No files matched your search

+4 -2
View File
@@ -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.
+9 -14
View File
@@ -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 <veth>`) 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 <veth>`) or
reboot it.
## Distributed Building