VM Lifecycle Management in KubeVirt#

KubeVirt manages VM lifecycle through two parallel state layers:

• VMIPhase — the Kubernetes-API-facing phase of a VirtualMachineInstance (Pending → Running → Succeeded/Failed)
• Domain LifeCycle — the libvirt/QEMU domain state internal to virt-launcher (Running, Paused, Shutoff, PMSuspended, etc.)

Four components coordinate transitions:

VMI Phases (Kubernetes-Facing)#

VirtualMachineInstancePhase is the user-visible lifecycle state, defined in staging/src/kubevirt.io/api/core/v1/types.go:

IsFinal() returns true for Succeeded and Failed — the terminal states that trigger virt-controller restart/cleanup logic. The VirtualMachineStatus.PrintableStatus field provides a finer-grained human-readable status beyond the raw phase 1.

Domain LifeCycle States (libvirt-Facing)#

The LifeCycle type in pkg/virt-launcher/virtwrap/api/schema.go mirrors libvirt's domain states:

Every state transition also carries a StateChangeReason 2. The most operationally significant are:

• Shutoff reasons: Shutdown (guest-initiated), Destroyed (force-killed), Migrated, Crashed, Panicked, Saved, FromSnapshot
• Pause reasons: User, Migration, IOError (triggers auto-retry), Postcopy, PostcopyFailed (triggers irrecoverable shutdown), Snapshot, StartingUp

DomainStatus stores both the current LifeCycle and StateChangeReason together 3.

VM RunStrategy (Policy Layer)#

The VirtualMachine object's RunStrategy field controls what the virt-controller does when the VMI reaches a terminal phase 4:

The controller implements this in syncRunStrategy(). Lifecycle API calls that don't match the current RunStrategy are rejected — for example, calling /start on a VM with RunStrategyAlways returns a 409 Conflict 5.

User requests that are compatible queue VirtualMachineStateChangeRequest items (StartRequest / StopRequest) into VM.Status.StateChangeRequests 6. The virt-controller drains this queue as it reconciles.

Component Responsibilities#

virt-api — pkg/virt-api/rest/lifecycle.go#

Exposes subresource endpoints: start, stop, restart, pause, unpause, softreboot, reset, migrate. Each handler:

1. Validates the current VMI phase and RunStrategy compatibility before accepting the request.
2. For start/stop/restart: patches VM.Spec (for Always/Once) or appends to VM.Status.StateChangeRequests (for Manual/RerunOnFailure) 7.
3. For pause/unpause: forwards the request directly to virt-handler via a PUT to the handler's REST endpoint — no VM-level state is mutated 8.

Key validation rules 9 10:

• start is rejected if the VMI is already in a non-final phase.
• pause requires VMI phase Running and the VirtualMachineInstancePaused condition absent.
• unpause requires the VirtualMachineInstancePaused condition present; also blocked if a snapshot is in progress.

virt-controller — pkg/virt-controller/watch/vm/vm.go#

The controller watches VirtualMachine and VirtualMachineInstance objects. Its entry point is Execute(), which calls sync() → syncRunStrategy(). For each RunStrategy branch it either creates a new VMI, deletes the existing one, or does nothing. Start failure crash-loop backoff is tracked in VirtualMachineStatus.StartFailure 1.

virt-handler — pkg/virt-handler/vm.go#

The per-node reconciliation loop runs sync() 11, which resolves four decision flags:

• shouldShutdown — domain alive + VMI deleted or deletion timestamp set → call processVmShutdown() (ACPI signal)
• shouldDelete — domain not alive + VMI in final state → call deleteVM() (cleanup)
• shouldUpdate — VMI active and phase in sync → call processVmUpdate() (sync spec, hotplug)
• forceShutdownIrrecoverable — domain paused due to PostcopyFailed → call processVmDestroy() (force kill)

After each action, virt-handler calls calculateVmPhaseForStatusReason() to translate the current domain LifeCycle + StateChangeReason into a VirtualMachineInstancePhase and writes it back to VMI.Status.

virt-launcher — pkg/virt-launcher/notify-client/client.go#

StartDomainNotifier() 12 registers libvirt event callbacks (lifecycle, device add/remove, job completed). On each event it:

1. Fetches fresh domain state from libvirt.
2. Calls domain.SetState(ConvState(status), ConvReason(status, reason)) to map libvirt enums to KubeVirt types.
3. Marshals the domain object to JSON and sends it to virt-handler via gRPC (SendDomainEvent()), retrying on transient errors (Unavailable, DeadlineExceeded, Aborted).

Key State Mappings#

The following table summarizes how calculateVmPhaseForStatusReason() 13 translates domain state → VMI phase:

Paused vs. Running: The VMI phase stays Running while the guest is paused — the guest-paused state is surfaced via the VirtualMachineInstancePaused condition on the VMI, not via a distinct phase. This means controllers and users need to check conditions, not just phase, to determine if a VM is actually executing.

IOError handling: A domain paused with reason IOError does not immediately map to failure. virt-handler's IO error retry manager delays the shouldUpdate action, giving storage time to recover before escalating 14.