Skip to main content

KubeVirt Configuration

The KubeVirt Configuration page is a guided editor for the cluster-scoped KubeVirt custom resource that KubeVirt uses to configure the virtualization layer. Use the page to adjust feature gates, eviction and migration policy, workload update behavior, and Kernel Same-Page Merging (KSM) without editing the custom resource directly.

Virtual Machine Orchestrator (VMO) submits your changes with Server-Side Apply and identifies itself as the vmo-manager field manager. This allows VMO to share the resource with the KubeVirt operator and other controllers that own fields on it.

warning

This page edits the live configuration of your cluster. Changes take effect when you apply them and affect every VM that runs on the appliance.

info

The KubeVirt Configuration page is available only to users who hold cluster-admin privileges and who authenticate through OIDC.

Configuration Sections​

The page is organized into the following sections, each of which maps to a part of the KubeVirt resource.

SectionDescriptionResource fields
Developer ConfigurationCPU emulation, cluster-wide overcommit ratios, and the lists of enabled and disabled feature gates.spec.configuration.developerConfiguration, including featureGates and disabledFeatureGates
StrategiesCluster defaults for eviction, VM rollout, and uninstall behavior.spec.configuration.evictionStrategy, spec.configuration.vmRolloutStrategy, spec.uninstallStrategy
Live MigrationConcurrency, bandwidth, and timeout limits that apply to live migration.spec.configuration.migrations
Workload UpdatesHow KubeVirt applies updates to VMs that are already running.spec.workloadUpdateStrategy
KSM ConfigurationNode label selector that determines where KSM runs.spec.configuration.ksmConfiguration
OwnershipRead-only list of the controllers that own fields on the resource.metadata.managedFields

Configure KubeVirt​

  1. Log in to VMO.

  2. From the VMO left main menu, select Settings.

  3. Under Configuration, select KubeVirt. The page loads the current KubeVirt resource from the cluster.

  4. Adjust the fields you want to change in any section. To reach fields that the form does not display, select Open YAML and edit the resource spec directly. VMO validates your YAML and merges it into the same draft as the form fields.

  5. Select Apply. VMO makes Apply available only when your draft differs from the version stored in the cluster and every field passes validation.

  6. Review the Diff Preview, which compares the current spec with the spec you are about to submit.

  7. Select Apply in the Diff Preview to send the change to the cluster. VMO reloads the form from the updated resource and clears your draft.

Select Reload at any point to discard your draft and fetch the current resource from the cluster.

Developer Configuration​

FieldDescriptionDefault
Enable CPU emulationFalls back to software CPU emulation when the host does not provide hardware virtualization extensions. Intended for lab and development environments.Cleared
Memory overcommit ratio (%)Sets the cluster-wide level of memory overcommit. At 100, the memory request of a VM equals its guest memory. Higher values reduce the request proportionally, so 200 requests about half and allows more VMs per node.100
CPU allocation ratioDefines how much physical CPU is reserved per vCPU. Lower values give each vCPU more guaranteed CPU. Higher values increase VM density with less CPU per VM.10
Feature gatesKubeVirt feature gates turned on explicitly for the cluster. On KubeVirt 1.9.0 and later, Beta gates are also on unless they are in Disabled feature gates.Varies
Disabled feature gatesBeta feature gates that stay off on KubeVirt 1.9.0 and later, which turn every Beta gate on by default. Refer to Disabled Feature Gates.Set by VMO
info

The overcommit ratios change resource density across the whole cluster. To review the trade-offs before you adjust them, refer to VM Overcommitment and Memory Optimization.

To enable a feature gate, enter its name in the Add a gate field and select Add. To remove a gate, select the x on the gate. VMO submits the list as you entered it, so the KubeVirt admission webhook rejects a name it does not recognize when you apply. On KubeVirt 1.9.0 and later, removing a Beta gate from Feature gates does not turn it off. To turn off a Beta gate, refer to Disabled Feature Gates.

Disabled Feature Gates​

KubeVirt 1.9.0 and later turn on every Beta feature gate by default. The Disabled feature gates list turns individual Beta gates off. VMO fills the list with the Beta gates that it has not validated, both on new installations and when the cluster upgrades to KubeVirt 1.9.0. VMO fills the list only when the cluster does not have one, so your changes to the list stay in place across restarts and upgrades.

To keep a Beta gate off, enter its name in the Add a gate field of Disabled feature gates and select Add. To let KubeVirt turn a gate on, select the x on the gate. The field suggests only Beta gates, because GA gates cannot be turned off and Alpha gates are already off. On a cluster that runs an earlier KubeVirt version, the field suggests no gates. A gate cannot be in both Feature gates and Disabled feature gates, so each field refuses a gate that is already in the other.

VMO turns off the following Beta gates by default.

GateWhy VMO turns it off
TemplateDeploys the virt-template-apiserver and virt-template-controller images, which are not in the airgap content and have no FIPS build.
ExternalNetResourceInjectionChanges how KubeVirt reads Network Attachment Definitions. VMO has not validated it with secondary networks.
PodSecondaryInterfaceNamingUpgradeChanges existing VMs by migrating them away from the earlier naming of their pod network interfaces.
ImageVolume, NodeRestriction, GPUsWithDRA, HostDevicesWithDRADepend on Kubernetes feature gates that might not be on in the appliance.
KubevirtSeccompProfile, PasstBinding, LibvirtHooksServerAndClientAdd new runtime behavior that VMO has not validated, such as a custom seccomp profile, the passt network binding, and migration hooks.
warning

Before you remove a gate from Disabled feature gates, confirm that the appliance meets its requirement. For example, on an airgapped or FIPS appliance, removing Template leaves the virt-template-apiserver and virt-template-controller pods unable to start.

Strategies​

FieldDescriptionDefault
Default eviction strategyWhat KubeVirt does with a running VM when its node is drained.Live migrate
VM rollout strategyWhen a configuration change to a VM takes effect.Live update
Uninstall strategyWhether KubeVirt can be uninstalled while VM workloads still exist on the cluster.Block uninstall if workloads exist

Live Migration​

FieldDescriptionDefault
Parallel outbound migrations per nodeMaximum number of migrations that can leave a single node at the same time.Empty
Parallel migrations per clusterMaximum number of migrations that can run across the cluster at the same time.Empty
Bandwidth per migrationNetwork bandwidth limit for a single migration. Enter a Kubernetes quantity, such as 1Gi. Enter 0 for no limit.Empty
Completion timeout (s / GiB)Seconds allowed for each GiB of memory before KubeVirt cancels a migration that has not finished.150
Progress timeout (s)Seconds that a migration can run without making progress before KubeVirt cancels it.Empty
Allow auto-convergeThrottles the guest CPU when a migration cannot keep pace with the rate at which the guest changes memory.Selected
Allow post-copyAllows KubeVirt to switch to post-copy migration when pre-copy migration does not converge.Cleared
Allow workload disruption during maintenanceAllows KubeVirt to disrupt workloads that cannot migrate when a node enters maintenance.Cleared

An empty field means that the KubeVirt default applies. To review the upstream defaults, refer to Live Migration in the KubeVirt user guide. VMO validates the bandwidth format before you apply, so a value in the wrong format keeps Apply unavailable instead of failing at the admission webhook.

Workload Updates​

FieldDescriptionDefault
Workload update methodsHow KubeVirt updates VMs that are already running. Select LiveMigrate, Evict, or both.LiveMigrate
Batch eviction sizeNumber of VMs that KubeVirt updates in a single batch.Empty
Batch eviction intervalTime that KubeVirt waits between batches. Enter a Go duration, such as 1m0s.Empty

KSM Configuration​

KSM is a Linux kernel feature that allows deduplication of identical memory pages across VMs. It reduces memory consumption when many VMs run the same guest operating system.

The Node label selector determines where KSM runs. KSM runs on the nodes whose labels match every key and value pair in the selector. You can add up to eight pairs.

To restrict KSM to a set of nodes, enter a label key and its value, and then select Add. To remove a pair, select the delete icon at the end of its row.

info

KSM adds CPU overhead because the kernel continuously scans memory pages. For guidance on when the memory savings are worth that cost, refer to VM Overcommitment and Memory Optimization.

Ownership​

The Ownership section lists every field manager that owns fields on the KubeVirt resource, along with the operation it used, when it last wrote, and how many fields it owns. Typical managers are vmo-manager, virt-controller, and virt-operator.

This section is read-only. Review it when you plan to change a field that another controller manages, because Server-Side Apply returns a conflict when two managers claim the same field.

Apply Errors​

VMO displays the following errors at the top of the form when an apply does not succeed.

ErrorCauseResolution
Server-Side Apply conflictAnother field manager, often the KubeVirt operator, owns a field that you changed.Select Reload to fetch the current resource, and then make your change again on the updated state.
Kubernetes permission deniedYour Kubernetes identity does not hold update permission on the kubevirts.kubevirt.io resource. Both your VMO permission and Kubernetes RBAC must allow the change.Ask a cluster administrator to grant the permission, or apply the change with an account that holds it.
Admission rejectionThe KubeVirt admission webhook rejected the change, such as an unrecognized feature gate name or a malformed duration.Correct the value that the message identifies, and then apply again.

Permissions​

Two permissions control this page.

  • vmo:kubevirt:read - Displays the configuration and the YAML editor in read-only form.

  • vmo:kubevirt:write - Allows you to edit the draft and apply changes. Without this permission, the page displays a read-only banner and Apply remains unavailable.

Only the built-in Platform Admin role holds these permissions. Because the KubeVirt resource is cluster-scoped, the Configuration group is available only to users whose access is not restricted to specific namespaces.

To review the permissions that each built-in role holds, refer to VM User Roles and Permissions.

Feature Gate Considerations​

The DeclarativeHotplugVolumes gate is required to define a CD-ROM drive that has no ISO mounted when you create a VM. Without the gate, VMO omits empty CD-ROM entries from the manifest it generates. On KubeVirt 1.9.0 and later, the gate is a Beta gate that is on by default. It does not need to be in Feature gates, and VMO does not add it to Disabled feature gates. On earlier KubeVirt versions, the gate must be in Feature gates. For more information about adding CD-ROM drives, refer to Create a VM.

HotplugVolumes and DeclarativeHotplugVolumes can both appear in Feature gates without the admission webhook rejecting them. When the list contains both gates, HotplugVolumes takes precedence for the imperative hot-plug API, while DeclarativeHotplugVolumes still allows empty CD-ROM drives at creation time.

KubeVirt 1.9.0 deprecates HotplugVolumes, but VMO includes it in Feature gates by default on both new installations and upgrades. KubeVirt accepts hot-plug requests when either gate is on, so disk hot-plug keeps working without HotplugVolumes as long as DeclarativeHotplugVolumes stays on.

  • On KubeVirt 1.9.0 and later, remove HotplugVolumes from Feature gates.

  • On earlier KubeVirt versions, keep HotplugVolumes unless DeclarativeHotplugVolumes is also in Feature gates.

warning

Before you turn off DeclarativeHotplugVolumes, attach an ISO to every VM that has an empty CD-ROM drive, or remove the empty drive from those VMs. VMs that keep an empty CD-ROM drive after you turn off the gate can enter a degraded state. On KubeVirt 1.9.0 and later, turn off the gate by adding it to Disabled feature gates. On earlier versions, remove it from Feature gates.