feat(vm-instance): allow attaching a disk to a running VM - #3978

What this PR does

A disk added to disks of an existing VMInstance never reaches the running guest. KubeVirt classifies the change as non-live-updatable, sets RestartRequired on the VirtualMachine, and the volume only shows up after the guest is restarted. A blank disk is worse: its PVC binds on WaitForFirstConsumer, and the only consumer that could bind it is the VMI that is not getting the volume. So adding a data disk to a live workload requires a reboot, which defeats the point of a hot-attach for anything built on the aggregated API.

KubeVirt supports this declaratively behind the DeclarativeHotplugVolumes feature gate (Alpha since v1.6.0, Beta in v1.9.0), and the user guide requires the volume to carry hotpluggable: true:

volumes:
  - dataVolume:
      name: hotplug-disk
      hotpluggable: true
    name: disk1

The chart cannot express it — disks[] exposes only name and bus — so no consumer of the aggregated API can ask for a hot-attach. This adds an optional disks[].hotpluggable that renders it.

Why the template refuses some buses

ValidateHotplugDiskConfiguration (pkg/storage/admitters/storagehotplug.go) rejects a hotplugged disk whose bus is neither scsi nor virtio, and nothing defaults an empty bus before that admitter runs — getDiskBus returns the field as written, and every hotplug test in tests/storage/hotplug.go passes an explicit bus.

So hotpluggable: true with bus: sata, or with no bus at all, would render fine and then be refused at admission. That failure is expensive: it leaves the HelmRelease in UpgradeFailed, and a stuck release keeps every subsequent change from reaching the machine — a restart included. The template therefore fails early and names the disk. bootOrder needs no change: the same admitter only requires it to be greater than zero, and the chart already emits add $i 1.

bus itself is untouched, and a non-hotpluggable disk with no bus keeps rendering disk: {} exactly as #2643 intended.

Verification

• helm unittest . — 5 new cases: the rendered field, its absence, both accepted buses, and the two refusals with their message.
• Negative control: 4 of the 5 fail without the template change. The fifth is the backward-compatibility assertion, and passes either way by construction.
• make generate output committed: values.schema.json, README.md, the ApplicationDefinition and api/apps/v1alpha1/vminstance/types.go.

A note for platform operators, beyond this PR

The field is inert until a cluster enables DeclarativeHotplugVolumes, and that gate is documented as incompatible with the deprecated HotplugVolumes one — "if both are declared, HotplugVolumes will have precedence until the time that HotplugVolumes is retired". packages/system/kubevirt/templates/kubevirt-cr.yaml declares HotplugVolumes (and tests/kubevirt_cr_test.yaml pins it), so switching is not additive.

It is also not free. The tenant CSI driver reaches the VMI removevolume subresource directly in the orphan-detach path added by #2866 (packages/apps/kubernetes/images/kubevirt-csi-driver/controller.go, RemoveVolumeFromVMI), and that path is gated on the deprecated HotplugVolumes alone — ephemeralHotplugSupported() in pkg/virt-api/rest/volumes.go ignores DeclarativeHotplugVolumes, and vmiVolumePatch then answers VMI %s/%s is owned by a VM. The normal attach and detach paths (AddVolumeToVM / RemoveVolumeFromVM, VM subresource) keep working under either gate; only that one breaks. Happy to open a separate issue for it if that is the right place.

Screenshots

No console code. The field reaches the dashboard through the schema-driven form (RJSF renders type: boolean as a checkbox from values.schema.json), so there is nothing to change in packages/system/dashboard/images/console — and nothing I can screenshot before the chart is deployed. I can attach one once it is running if that is wanted.

Downstream repositories

Walked the trigger map in docs/agents/contributing.md against the diff, file by file.

• No downstream repository is affected by this change
• cozystack/website — no follow-up needed: vm-instance is already in the website Makefile's VMS list, so the release bot regenerates its reference page from this package's README.md, which this PR updates. No page is hand-written for it.
• cozystack/terraform-provider-cozystack — follow-up: VMInstance: model the new disks[].hotpluggable field (upstream cozystack#3978) terraform-provider-cozystack#35
• cozystack/ansible-cozystack - follow-up:
• cozystack/ccp - follow-up:
• cozystack/talm - follow-up:
• cozystack/cozyhr - follow-up:
• cozystack/cozy-proxy - follow-up:
• cozystack/cozystack-telemetry-server - follow-up:
• cozystack/external-apps-example - follow-up:
• cozystack/examples - follow-up:

The provider hand-models disks[] as {name, bus} in internal/provider/vminstance_schema.go, in both the resource and the data source, plus its model and expand/flatten pair. Filed as an issue rather than a PR there: its api/apps/v1alpha1 pin has to move past this merge first, and shipping the attribute before that would hand users a Terraform field that silently does nothing.

Release note

feat(vm-instance): `disks[]` accepts an optional `hotpluggable` flag, which marks the volume so KubeVirt can attach or detach it while the VM is running. Requires the `DeclarativeHotplugVolumes` feature gate on the cluster, and `bus` to be `scsi` or `virtio`.

Summary by CodeRabbit

• New Features

  • Added optional hotplug support for VM disks, allowing compatible disks to be attached or detached while the VM is running.
  • Added configuration and schema support for the hotpluggable disk option.
  • Hotplugging is supported with scsi or virtio buses and requires the appropriate feature gate.

• Bug Fixes

  • Invalid hotplug configurations now fail validation with a clear error message.

• Documentation

  • Updated VM instance configuration documentation and examples.

Assisted by Codex