From 30f28b78f77a6e25061278a7fbaf2569674efcbd Mon Sep 17 00:00:00 2001 From: Yan Zhu Date: Wed, 15 Jul 2026 09:36:22 +0800 Subject: [PATCH] docs: add rebootPolicy and boot override completeness guides - Document rebootPolicy: Terminate for handling in-guest reboot scenarios with oneshot boot order (KubeVirt 1.8.0+, kubevirt/kubevirt#16579) - IPMI guide: add persistent/uefi options, clear boot override (none), and boot options reference table - Redfish guide: add Disable Boot Override section, Disk/CD-ROM Continuous variants, combined boot device + firmware mode examples - Virtual Media guide: add cross-reference note for rebootPolicy Signed-off-by: Yan Zhu --- docs/ipmi-guide.md | 60 +++++++++++++++++++ docs/redfish-guide.md | 134 +++++++++++++++++++++++++++++++++++++++++- docs/virtual-media.md | 4 ++ 3 files changed, 196 insertions(+), 2 deletions(-) diff --git a/docs/ipmi-guide.md b/docs/ipmi-guide.md index bbb61f7..ccf5ad7 100644 --- a/docs/ipmi-guide.md +++ b/docs/ipmi-guide.md @@ -113,19 +113,49 @@ Powers off, waits briefly, then powers on. ### Set Boot to PXE ```bash +# One-shot (default) ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev pxe + +# Persistent +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev pxe options=persistent + +# One-shot + UEFI +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev pxe options=uefi + +# Persistent + UEFI +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev pxe options=persistent,uefi ``` ### Set Boot to Disk ```bash +# One-shot (default) ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev disk + +# Persistent +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev disk options=persistent + +# One-shot + UEFI +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev disk options=uefi + +# Persistent + UEFI +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev disk options=persistent,uefi ``` ### Set Boot to CD-ROM ```bash +# One-shot (default) ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev cdrom + +# Persistent +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev cdrom options=persistent + +# One-shot + UEFI +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev cdrom options=uefi + +# Persistent + UEFI +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev cdrom options=persistent,uefi ``` ### Supported Boot Devices @@ -136,6 +166,36 @@ ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev cdr | `disk` | Boot from disk | | `cdrom` | Boot from CD-ROM | +### Boot Options + +`chassis bootdev` supports the following `options=` flags: + +| Option | Description | +|--------|-------------| +| *(none)* | One-shot override (default). The device is used for a single boot, then the VM reverts to its default boot order. | +| `persistent` | Persistent override. The boot device override persists across multiple boots. Equivalent to Redfish `BootSourceOverrideEnabled: "Continuous"`. | +| `uefi` | UEFI firmware boot. Sets the boot mode to UEFI. Omit for legacy BIOS mode. | + +Multiple options can be combined with commas, e.g. `options=persistent,uefi`. + +### Clear Boot Override + +Clear any pending boot device override and restore the VM's default boot order: + +```bash +ipmitool -I lan -U "$USERNAME" -P "$PASSWORD" -H "$HOSTNAME" chassis bootdev none +``` + +### One-Shot Boot and In-Guest Reboot + +When using one-shot boot override (the default without `options=persistent`), the VM boots from the specified device once, then reverts to its default boot order. However, if the guest OS triggers a reboot (e.g., after completing an OS installation), KubeVirt's default behavior is to silently reboot the VirtualMachineInstance (VMI) without recreating it. This means the boot device override may not be re-applied to the VMI, and the VM may boot from its default device instead. + +To ensure the boot device override survives in-guest reboots, configure the KubeVirt VirtualMachine's `rebootPolicy` to `Terminate`. This causes the VMI to be terminated on guest reboot, allowing the VM controller to recreate the VMI with the updated boot order. + +!!! note "KubeVirt version requirement" + + The `rebootPolicy` field was introduced in KubeVirt 1.8.0 ([kubevirt/kubevirt#16579](https://github.com/kubevirt/kubevirt/pull/16579)). It requires the `RebootPolicy` feature gate to be enabled in the KubeVirt configuration. See the [Redfish Guide](redfish-guide.md#one-shot-boot-and-in-guest-reboot) for a complete example. + ## Next Steps - Read the [Redfish Guide](redfish-guide.md) for RESTful API access diff --git a/docs/redfish-guide.md b/docs/redfish-guide.md index 990cf9a..67b593f 100644 --- a/docs/redfish-guide.md +++ b/docs/redfish-guide.md @@ -233,6 +233,7 @@ curl -i -X PATCH \ ### Set Boot to Disk ```bash +# One-time curl -i -X PATCH \ -H "Content-Type: application/json" \ -H "X-Auth-Token: $TOKEN" \ @@ -243,11 +244,24 @@ curl -i -X PATCH \ "BootSourceOverrideEnabled": "Once" } }' + +# Continuous +curl -i -X PATCH \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $TOKEN" \ + http://testvm-virtbmc.default.svc.cluster.local/redfish/v1/Systems/1 \ + -d '{ + "Boot": { + "BootSourceOverrideTarget": "Hdd", + "BootSourceOverrideEnabled": "Continuous" + } + }' ``` -### Set Boot to CD-ROM (One-time) +### Set Boot to CD-ROM ```bash +# One-time curl -i -X PATCH \ -H "Content-Type: application/json" \ -H "X-Auth-Token: $TOKEN" \ @@ -258,9 +272,69 @@ curl -i -X PATCH \ "BootSourceOverrideEnabled": "Once" } }' + +# Continuous +curl -i -X PATCH \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $TOKEN" \ + http://testvm-virtbmc.default.svc.cluster.local/redfish/v1/Systems/1 \ + -d '{ + "Boot": { + "BootSourceOverrideTarget": "Cd", + "BootSourceOverrideEnabled": "Continuous" + } + }' +``` + +### Disable Boot Override + +Clear any pending boot device override and restore the VM's default boot order: + +```bash +curl -i -X PATCH \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $TOKEN" \ + http://testvm-virtbmc.default.svc.cluster.local/redfish/v1/Systems/1 \ + -d '{ + "Boot": { + "BootSourceOverrideEnabled": "Disabled" + } + }' +``` + +### Set Boot Device with Firmware Mode + +You can combine boot device override and firmware mode (UEFI/Legacy) in a single request: + +```bash +# PXE one-shot + UEFI +curl -i -X PATCH \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $TOKEN" \ + http://testvm-virtbmc.default.svc.cluster.local/redfish/v1/Systems/1 \ + -d '{ + "Boot": { + "BootSourceOverrideTarget": "Pxe", + "BootSourceOverrideEnabled": "Once", + "BootSourceOverrideMode": "UEFI" + } + }' + +# HDD continuous + Legacy +curl -i -X PATCH \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $TOKEN" \ + http://testvm-virtbmc.default.svc.cluster.local/redfish/v1/Systems/1 \ + -d '{ + "Boot": { + "BootSourceOverrideTarget": "Hdd", + "BootSourceOverrideEnabled": "Continuous", + "BootSourceOverrideMode": "Legacy" + } + }' ``` -### Set Boot Mode +### Set Boot Mode (Firmware Only) ```bash # UEFI mode @@ -286,6 +360,62 @@ curl -i -X PATCH \ | `BootSourceOverrideEnabled` | `Once`, `Continuous`, `Disabled` | Override behavior | | `BootSourceOverrideMode` | `Legacy`, `UEFI` | Boot mode | +### One-Shot Boot and In-Guest Reboot + +When using `"Once"` for `BootSourceOverrideEnabled`, the boot order override is applied to the KubeVirt VirtualMachine for a single boot. However, if the guest OS triggers a reboot (e.g., after completing an OS installation), KubeVirt's default behavior is to silently reboot the VirtualMachineInstance (VMI) without recreating it. This means the VirtualMachine's updated boot order may not be re-applied to the VMI after the in-guest reboot, and the VM may boot from its default device instead. + +To ensure the one-shot boot order survives in-guest reboots, configure the KubeVirt VirtualMachine's `rebootPolicy` to `Terminate`. This causes the VMI to be terminated on guest reboot, allowing the VM controller to recreate the VMI with the updated boot order configuration. + +!!! note "KubeVirt version requirement" + + The `rebootPolicy` field was introduced in KubeVirt 1.8.0 ([kubevirt/kubevirt#16579](https://github.com/kubevirt/kubevirt/pull/16579)). It requires the `RebootPolicy` feature gate to be enabled in the KubeVirt configuration. + +**Example VirtualMachine with rebootPolicy:** + +```yaml +apiVersion: kubevirt.io/v1 +kind: VirtualMachine +metadata: + name: testvm +spec: + runStrategy: Always + template: + spec: + domain: + rebootPolicy: Terminate # Terminate VMI on guest reboot + devices: + disks: + - name: containerdisk + disk: + bus: virtio + resources: + requests: + memory: 64Mi + volumes: + - name: containerdisk + containerDisk: + image: quay.io/kubevirt/cirros-container-disk-demo +``` + +!!! warning + + When `rebootPolicy` is set to `Terminate`, the VMI is terminated and recreated on every guest reboot. This may cause a brief interruption and should only be used when you need boot order changes to persist across in-guest reboots. + +### Verify RebootPolicy Feature Gate + +Check that the `RebootPolicy` feature gate is enabled: + +```bash +kubectl get kubevirt kubevirt -n kubevirt -o yaml | grep RebootPolicy +``` + +If it is not enabled, patch the KubeVirt resource: + +```bash +kubectl patch kubevirt kubevirt -n kubevirt --type merge -p \ + '{"spec":{"configuration":{"developerConfiguration":{"featureGates":["RebootPolicy"]}}}}' +``` + ## System Information ### Get System Details diff --git a/docs/virtual-media.md b/docs/virtual-media.md index 038318b..70a98de 100644 --- a/docs/virtual-media.md +++ b/docs/virtual-media.md @@ -201,6 +201,10 @@ curl -i -X POST \ -d '{"ResetType":"GracefulRestart"}' ``` +!!! note "In-guest reboot handling" + + When using one-shot boot (`"Once"`) to boot from virtual media, the boot order override may be lost if the guest OS triggers a reboot (e.g., after an installer finishes). To ensure the one-shot CD-ROM boot survives in-guest reboots, configure `rebootPolicy: Terminate` on the KubeVirt VirtualMachine. See the [Redfish Guide](redfish-guide.md#one-shot-boot-and-in-guest-reboot) for details. This requires KubeVirt 1.8.0+ with the `RebootPolicy` feature gate enabled. + ### Request Parameters | Parameter | Type | Required | Description |