VM Memory Overhead#

KubeVirt adds memory overhead on top of a VM's guest memory when sizing the virt-launcher pod. This overhead accounts for the QEMU/KVM process stack, KubeVirt daemons, page tables, video RAM, and other per-VM infrastructure. Understanding how it is calculated, applied, and exposed is essential for capacity planning, Kubernetes QoS tuning, and debugging OOMKill events.

Key source files:

• pkg/hypervisor/kvm/hypervisorbackend.go — GetMemoryOverhead(), fixed process constants
• pkg/virt-controller/services/renderresources.go — WithMemoryOverhead(), WithMemoryRequests(), WithAutoMemoryLimits()
• pkg/virt-controller/services/template.go — CalculateMemoryOverhead(), pod annotation injection
• pkg/virt-controller/watch/vmi/lifecycle.go — updateMemoryOverheadStatusFromPod(), VMI status update

Overhead Calculation#

The entry point is GetMemoryOverhead() in the KVM hypervisor backend. It computes a total overhead value by summing several components:

Fixed process overhead#

These are observable RSS values rounded up for safety 1. The QemuOverhead constant is subject to periodic revision as QEMU grows with new virtio features and guest OS sizes increase — it was bumped from 30 Mi to 50 Mi in PR #18388 to resolve CI flakes 2.

Dynamic overhead components#

All computed inside GetMemoryOverhead():

• Page tables: 1 bit per 512 bytes of guest RAM 3
• vCPU tables: 8 Mi per vCPU + 8 Mi static for IOThreads 4
• Video RAM: 32 Mi if AutoattachGraphicsDevice is enabled (default) 5
• ARM64 UEFI pflash: +128 Mi on arm64 6
• VFIO devices: +1 Gi to cover DMA-locked guest RAM + MMIO space 7
• DownwardMetrics disk: +1 Mi for memory-backed emptyDir 8
• Exec probes: +100 Mi base + 10 Mi per probe (virt-probe binary overhead) 9
• SEV/SEV-SNP/SEV-ES: +256 Mi for encrypted memory regions 10
• TPM (swtpm): +53 Mi 11
• Dedicated CPU / Guaranteed QoS: +100 Mi 12
• Custom reserved overhead: additive field from spec.domain.memory.reservedOverhead.addedOverhead 13
• Additional ratio multiplier: an optional cluster-level ratio applied last to scale the entire overhead value 14

Applying overhead to the pod#

WithMemoryOverhead() in renderresources.go adds the computed overhead to the pod's memory request, and always adds it to the memory limit (even when overcommitGuestOverhead: true prevents it from being added to the request) 15. For hugepages VMIs, WithHugePages() routes the overhead into the ordinary memory request rather than hugepages pages.

Auto memory limits default to 2× the memory request if no explicit limit is set, controllable per-namespace via the label alpha.kubevirt.io/auto-memory-limits-ratio 16 17.

Overcommit Strategies and QoS#

KubeVirt offers three memory overcommit strategies to increase node VM density, each with a different QoS trade-off 18:

1. Overcommit guest overhead (overcommitGuestOverhead: true)#

Setting spec.domain.resources.overcommitGuestOverhead: true on a VMI excludes the calculated overhead from the pod request (it is still included in the limit). This reduces the per-VMI Kubernetes accounting cost. Best for short-lived or bursty VMs where temporary OOM risk is acceptable 15.

2. Explicit guest memory overcommit#

A VMI can be configured with a guest memory size larger than the Kubernetes memory request (e.g., spec.domain.memory.guest: 2Gi but spec.domain.resources.requests.memory: 1Gi). Kubernetes assigns the pod a Burstable QoS class, making it the first to be evicted under node memory pressure 18.

3. Implicit cluster-level overcommit (memoryOvercommit)#

The KubeVirt CR field spec.configuration.developerConfiguration.memoryOvercommit accepts a percentage (default 100). When set above 100, WithMemoryRequests() automatically scales down the pod memory request to (guest_memory × 100) / overcommit_percent, allowing more VMs per node without per-VMI changes 19.

Overcommit is only applied when all of: memory requests are not explicitly set on the VMI, guest memory or hugepages are present, and the overcommit config is not 100. Explicitly set memory requests are preserved to allow the user to achieve Guaranteed QoS 20.

QoS classes#

For Guaranteed QoS, an extra 100 Mi is added to GetMemoryOverhead() 12, and sidecar containers also have their requests set equal to limits 21.

Reducing overhead to save memory#

Disabling the graphical device (spec.domain.devices.autoattachGraphicsDevice: false) removes the 32 Mi video RAM overhead per VMI 5 18. For high-density nodes, enabling KSM via node labels can deduplicate shared memory pages across VMs.

Overhead Visibility: VMI Status and Pod Annotation#

Feature gate#

The VmiMemoryOverheadReport feature gate (Beta) controls overhead exposure. When enabled:

1. Pod annotation: CalculateMemoryOverhead() stores the computed value as kubevirt.io/memory-overhead-bytes on the virt-launcher pod 22.
2. VMI status: updateMemoryOverheadStatusFromPod() reads the annotation and writes it to VMI.status.memory.memoryOverhead during the lifecycle reconciliation loop 23.

Recording the overhead on the pod at creation time (rather than recalculating it) ensures the value remains consistent across KubeVirt upgrades and cluster config changes 24.

Live migration#

During live migration a target virt-launcher pod is created, possibly on a node with different hardware (e.g., different arch, different enabled features). The target pod's overhead is tracked separately at VMI.status.migrationState.targetMemoryOverhead for the duration of the migration, then promoted to VMI.status.memory.memoryOverhead once migration completes 24 17.

Usage#

• Metrics collectors and monitoring agents can read status.memory.memoryOverhead without recalculating it, getting a stable value tied to the actual running pod.
• Schedulers and capacity planners can sum spec.domain.resources.requests.memory + status.memory.memoryOverhead to determine real node memory consumption per VMI.
• The annotation kubevirt.io/memory-overhead-bytes on virt-launcher pods can be used for direct pod-level queries.