KVM Ballooning: Read Guest Pressure Before Reclaiming RAM

A KVM host can be swapping while one guest still appears to have gigabytes available. That discrepancy does not prove the balloon is broken, and it does not make the guest’s cache disposable. Host resident memory, the balloon target, guest-available memory, reclaimable memory and actual swap activity describe different layers.

Do not lower a busy VM’s memory target from one host graph. Capture the domain definition and balloon statistics, verify the guest driver is reporting recently, observe both host and guest pressure through a representative workload, then move the target in a small reversible step. Success means the host regains headroom without guest swap growth, major-fault growth, latency regression or an OOM event.

Start with the contradiction, not a new target

First record the host’s current pressure and the domain’s configured boundaries. Replace VM_NAME with the real libvirt domain:

free -h
vmstat 1 10
virsh dominfo VM_NAME
virsh dumpxml VM_NAME \
  | grep -E '<(memory|currentMemory|memballoon)([[:space:]>])'

vmstat provides motion rather than a single occupancy value. Sustained nonzero si or so shows host swap traffic; a large swap allocation with no current I/O is historical state, not proof of an active incident. Record load latency and application errors at the same time so memory tuning has a user-visible acceptance criterion.

<memory> is the guest’s maximum allocation, while <currentMemory> can establish a lower starting or target allocation for ballooning. A memballoon device with the virtio model provides the communication path. Libvirt’s current domain XML documentation also distinguishes balloon statistics, automatic deflation near guest OOM and free-page reporting; those controls are related but not interchangeable.

If the broader question is whether a virtualized workload has a real isolation boundary, read KVM hypervisor isolation for VPS buyers. Balloon diagnosis begins after that architecture decision, on a host you can observe and control.

Make dommemstat evidence current

Run the current statistic set before changing anything:

virsh dommemstat VM_NAME

Output containing only actual and rss usually means the guest statistic poll is not enabled, the driver is unavailable, or the platform cannot expose the extra fields. Enable a short reporting period for the live domain and persistent configuration, then wait longer than one interval:

virsh dommemstat VM_NAME --period 5 --live
virsh dommemstat VM_NAME --period 5 --config
sleep 6
virsh dommemstat VM_NAME

The official virsh dommemstat reference defines actual as the current balloon value and rss as resident memory of the QEMU process. It defines available as memory usable from the domain’s view, while usable estimates memory reclaimable by the balloon without pushing the guest toward swap. Unsupported statistics are omitted, so a missing field is not zero.

QEMU’s virtio balloon statistics specification confirms that guest statistics are polled and returned asynchronously. Check last_update; stale numbers must not drive an automated reclaim decision.

Prove that the guest can report pressure

Inside a Linux guest, confirm the driver and collect the guest’s own pressure evidence:

lsmod | grep '^virtio_balloon'
free -h
grep -E 'MemAvailable|SwapTotal|SwapFree' /proc/meminfo
vmstat 1 10

Modern Linux guests commonly include virtio_balloon, but image policy or a custom kernel can remove it. Windows guests need the appropriate VirtIO balloon driver and service. Proxmox’s dynamic memory management guide documents both requirements and warns that aggressive ballooning can force guest swapping or trigger its OOM killer.

Guest MemAvailable is more useful than MemFree because Linux deliberately fills otherwise idle RAM with cache. Still, available memory is not a promise that the whole amount can disappear without latency. Cache refaults, anonymous working sets, locked memory and application allocators can turn a seemingly idle reduction into storage I/O or an OOM event.

An OOM message needs separate attribution. Linux OOM kill evidence distinguishes kernel global or cgroup kills from systemd-oomd; ballooning may create pressure, but the actual killer and scope remain observable facts.

Separate balloon reclaim from four look-alikes

Healthy balloon statistics do not rule out host pressure from another layer. Use the evidence branch that matches the symptom.

Host swap without a falling balloon target: libvirt by itself does not promise a general pressure-driven auto-balloon policy. A management layer may own dynamic targets, or no controller may exist. Identify the process that issues target changes before assuming the hypervisor will redistribute RAM automatically.

A falling target with rising guest swap or major faults: the guest is surrendering working-set pages or useful cache. Stop reducing the target and return to the last accepted floor. Repeated reclaim and refill can cost more than steady allocation.

High host RSS while actual fell: RSS and balloon target measure different things and may converge slowly. Transparent huge pages, locked pages, QEMU overhead, mappings, page reporting and host reclaim all affect what becomes resident or reusable. freePageReporting='on' can return unused pages to the hypervisor, but libvirt explicitly notes that it does not change free memory reported by dommemstat.

Slow VM with stable memory signals: investigate another resource. VPS CPU steal-time diagnosis covers host scheduler contention visible inside a guest, while cgroup v2 CPU throttling evidence explains latency caused by quota periods even when host-wide CPU looks quiet.

Change one boundary in a reversible step

Before a live change, record maximum memory, current target, workload baseline and an explicit rollback target. Confirm that console access and monitoring remain available. setmem requests a new balloon target; it does not validate application headroom for you.

virsh dominfo VM_NAME
virsh dommemstat VM_NAME
virsh setmem VM_NAME 12G --live
watch -n 2 virsh dommemstat VM_NAME

Treat 12G only as an example. Choose a small step above the proven working-set floor and below the configured maximum. Do not combine the test with a maximum-memory edit, VM migration, cache drop, KSM policy change or swap reconfiguration; multiple simultaneous controls destroy causal evidence.

During the observation window, compare deltas in swap_in, swap_out, major_fault, usable and actual. Inside the guest, watch latency, queue depth, allocator failures and its own vmstat. On the host, confirm whether swap I/O settles and MemAvailable recovers. Roll back immediately if guest swap-out, major faults, application latency or OOM evidence rises beyond the agreed boundary.

virsh setmem VM_NAME 16G --live

Use the captured previous value instead of blindly pasting 16G. The requested deflation may also need time; prove the target and workload recovered before another experiment.

Convert the observation into a durable policy

A stable target is not yet fleet policy. For each VM, define a maximum, an accepted minimum, a workload-specific guardrail and an owner for dynamic changes. Floors should come from peak working-set evidence, not from idle screenshots. Databases, JVM heaps, pinned pages and latency-sensitive caches often need more conservative floors than stateless workers.

Automation should require fresh last_update, driver presence, enough usable headroom, stable guest swap deltas and host pressure that persists for a defined window. Add hysteresis so the controller does not inflate and deflate around one threshold. Limit step size and frequency, log every old and new target, and expose a manual disable switch.

Proxmox environments add an orchestration layer and platform-specific exclusions. Its documentation warns that passthrough devices or mediated devices can prevent expected memory release even while the guest reports less available memory. Test VFIO, huge-page and pinned-memory workloads separately instead of inheriting a generic rule.

Proxmox VM backup consistency remains a separate guest-state concern. Balloon tuning does not prove that a database or filesystem snapshot is application-consistent, and backup success does not validate the VM’s memory floor.

Close the incident with a two-sided receipt

Finish only after a representative workload window, not immediately after setmem returns zero. Save the domain XML, dommemstat before-and-after output, guest driver evidence, host and guest vmstat, application latency/error metrics, chosen floor and rollback result.

Acceptance needs both sides: host swap I/O is no longer growing and physical headroom remains stable; guest swap and major faults stay within baseline, application latency meets its objective, no OOM event occurred, and the current target matches the intended policy. If committed guest floors plus host reserve exceed physical capacity, balloon tuning cannot make the arithmetic safe. Reduce consolidation or add RAM instead of reclaiming the same pages repeatedly.