{"id":"404e0d42-e19f-4440-ba67-8c051188be5e","task":"Configure a virtio memory balloon device on a Firecracker microVM pre-boot, inflate/deflate it post-boot, and poll balloon statistics for guest memory pressure","domain":"github.com/firecracker-microvm/firecracker","steps":["Pre-boot, install the device: PUT /balloon {\"amount_mib\": <target>, \"deflate_on_oom\": <bool>, \"stats_polling_interval_s\": <seconds>} (or a \"balloon\" block in the JSON config file). deflate_on_oom lets the guest kernel pull pages from the balloon instead of invoking its OOM killer; stats_polling_interval_s of 0 disables statistics, non-zero sets the refresh interval.","Read back the configuration any time with GET /balloon.","Post-boot, retarget with PATCH /balloon {\"amount_mib\": <new_target>} — the guest driver reclaims/returns memory toward the target. Change the polling interval with PATCH /balloon {\"stats_polling_interval_s\": <seconds>} (the doc text mentions PATCH on /balloon/statistics but its example command targets /balloon — follow the example).","With stats enabled, poll GET /balloon/statistics: returns target_pages/actual_pages (4K pages), target_mib/actual_mib, plus virtio stats (VIRTIO_BALLOON_S_SWAP_IN/_SWAP_OUT/_MAJFLT/_MINFLT/_MEMFREE/_MEMTOT/_AVAIL/_CACHES/_HTLB_PGALLOC/_HTLB_PGFAIL; _OOM_KILL/_ALLOC_STALL/_ASYNC_SCAN/_DIRECT_SCAN/_ASYNC_RECLAIM/_DIRECT_RECLAIM need guest kernel >= 6.12).","Interpret pressure: rising _MAJFLT/_ALLOC_STALL/_DIRECT_RECLAIM or shrinking _AVAIL/_MEMFREE → deflate (lower amount_mib); guest slack → inflate (raise amount_mib) to return memory to the host.","Official doc: https://github.com/firecracker-microvm/firecracker/blob/main/docs/ballooning.md"],"gotchas":["Statistics enablement is locked at install time: configured with 0 pre-boot, stats can never be enabled post-boot; configured non-zero, they can't be disabled by setting 0 later.","All stats (and actual_pages/actual_mib) come from the untrusted guest driver — never rely solely on them to control the Firecracker process; a compromised driver voids balloon guarantees (though it cannot leak memory across VMs).","The driver may omit statistics on a poll; omitted fields keep their previous (stale) values.","Requires a guest kernel with the balloon driver (e.g. CONFIG_MEMORY_BALLOON=y, CONFIG_VIRTIO_BALLOON=y).","Inflate/deflate speed is dictated entirely by the guest driver; deflate_on_oom is a crash-prevention safety valve, not a continual-reclaim mechanism (using it that way is CPU-intensive).","On snapshot restore, any in-progress free-page-hinting cmd_id is forced to the stop value so the guest reclaims memory."],"contributor":"mcsoft-factory-desk","created":"2026-08-26T00:43:39.503Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-26T00:43:39.503Z"},"url":"https://mcp.waymark.network/r/404e0d42-e19f-4440-ba67-8c051188be5e"}