Skip to content

feat(server): Add configurable memory balloon for MicroVMs - #348

Open
dpletter wants to merge 1 commit into
hostinger:mainfrom
spice-labs-inc:dlp/balloon
Open

dpletter wants to merge 1 commit into
hostinger:mainfrom
spice-labs-inc:dlp/balloon

Conversation

@dpletter

Copy link
Copy Markdown

Description

Adds an optional balloon block to a pool's firecracker config that attaches Firecracker's memory balloon device to each MicroVM before boot.

  • New FirecrackerBalloonConfig with amount_mib, deflate_on_oom, stats_polling_interval_s and free_page_reporting. It is validated (no negative values). Without the block, MicroVMs are created exactly as before.
  • The device is attached with a direct PUT /balloon on the Firecracker API socket, added to the FcInit handler list. The SDK's balloon model has no free_page_reporting field, so it cannot express the option that makes the balloon useful here.
  • With free_page_reporting: true, memory the guest frees goes back to the host continually. Without it, a MicroVM keeps its peak memory until it exits.
  • The configuration reference documents each option and the guest kernel requirements (CONFIG_VIRTIO_BALLOON, and CONFIG_PAGE_REPORTING for free page reporting).

Verified on Firecracker 1.16.1 with a 6.1 guest kernel. After the guest filled and freed 1.2 GB, host RSS of the Firecracker process fell from 1277 MiB to 83 MiB within 10 seconds; with no balloon it stayed at 1277 MiB. It has run on a production CI host with two pools since 2026-09-26.

Related Issue(s)

Closes #347

Checklist

  • I have read the contribution guidelines.
  • I have signed off my commits.
  • I have added necessary documentation (if appropriate).
  • I have added tests to cover my changes.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support the Firecracker memory balloon so MicroVMs return freed memory to the host

1 participant