KubeVirt Workload Update Strategy#

During a KubeVirt control plane upgrade, existing VMI workloads (virt-launcher, libvirt, qemu) are not updated by default. Opting in to automated workload updates requires configuring spec.workloadUpdateStrategy on the KubeVirt CR — available since v0.39.0.

API Structure#

KubeVirtWorkloadUpdateStrategy 1 is embedded in KubeVirtSpec 2:

Two WorkloadUpdateMethod constants are defined 3:

• LiveMigrate — live-migrates the VMI into a new pod with updated components; zero downtime for the guest.
• Evict — issues a pod eviction. If the VMI is owned by a VirtualMachine with runStrategy: Always, a new VMI starts automatically; standalone VMIs shut down.

When both methods are listed, LiveMigrate takes precedence: only VMIs that cannot be live-migrated are evicted 4 5.

Example — LiveMigrate + Evict with batching:

spec:
  workloadUpdateStrategy:
    workloadUpdateMethods:
      - LiveMigrate
      - Evict
    batchEvictionSize: 10
    batchEvictionInterval: "1m"

(full examples in the user guide)

Controller Logic#

The WorkloadUpdateController runs inside virt-controller and is the sole actor driving workload updates.

Safety Gates#

execute() enforces two hard preconditions before any action is taken:

1. kv.Status.Phase == KubeVirtPhaseDeployed
2. kv.Status.ObservedDeploymentID == kv.Status.TargetDeploymentID

Both must be true, ensuring workload updates only begin after all KubeVirt infrastructure components have fully rolled out 6.

Staleness Detection#

isOutdated() compares vmi.Status.LauncherContainerImageVersion against the controller's current launcherImage. VMIs still initializing or mid-migration (empty LauncherContainerImageVersion) are skipped.

Update Categorization#

getUpdateData() buckets all running VMIs into:

• migratableOutdatedVMIs — outdated + live-migratable (when LiveMigrate enabled)
• evictOutdatedVMIs — outdated + not live-migratable (when Evict enabled)
• abortChangeVMIs — VMIs whose in-flight workload-update migration should be cancelled

VMIs already migrating are excluded from action lists to avoid duplicate operations 7.

Batching and Concurrency#

sync() applies two independent rate controls:

• Live migration cap: new migrations are bounded by ParallelMigrationsPerCluster minus currently active migrations 8. Migration candidates are randomly shuffled to avoid repeatedly retrying stuck VMIs 9.
• Eviction batching: evictions respect BatchEvictionSize and BatchEvictionInterval (defaulting to 10 / 60 s) via a lastDeletionBatch timestamp 10.

Each workload-update migration is annotated with WorkloadUpdateMigrationAnnotation for tracking 11 and given PrioritySystemCritical priority unless the migration is hotplug- or volume-change-driven 12.

The count of pending outdated VMIs is surfaced as kv.Status.OutdatedVirtualMachineInstanceWorkloads and a Prometheus metric via SetOutdatedVirtualMachineInstanceWorkloads.

Key Source Files#