[PR #48] [MERGED] feat(sandbox): add Firecracker disk I/O rate limiting (bandwidth + IOPS) #138

New issue

Closed

opened 2026-10-29 14:20:07 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:07 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/48
Author: @rogeroger-yu
Created: 7/28/2026
Status: ✅ Merged
Merged: 8/7/2026
Merged by: @yingdi-shan

Base: main ← Head: feat/disk-rate-limit-firecracker

📝 Commits (7)

ef01c5c feat(sandbox): add Firecracker disk I/O rate limiting (bandwidth + IOPS)
ab2ab1f fix(sandbox): correct disk rate limiter refill and resume reconciliation
16f1722 fix(sandbox): apply fresh sandbox's own disk rate limit config
d394ede fix(sandbox): apply disk rate limiter before I/O and reconcile per dimension
26994b8 fix(sandbox): refine disk rate limit validation and disable semantics
3535c8b fix(sandbox): use all-zero token bucket as disable sentinel and fix fmt
de45f98 docs(cfg): clarify one_time_burst is a one-time start-of-VM allowance

📊 Changes

5 files changed (+409 additions, -3 deletions)

View changed files

📝 config/default.toml (+7 -0)
📝 src/cfg.rs (+135 -0)
📝 src/sandbox/firecracker/config.rs (+9 -0)
📝 src/sandbox/firecracker/instance.rs (+22 -2)
📝 src/sandbox/firecracker/sandbox.rs (+236 -1)

📄 Description

Summary

Wire Firecracker's per-drive TokenBucket rate limiter into the sandbox lifecycle
Configurable via [machine.disk_rate_limit] with bandwidth, IOPS, and one-time burst settings (refill period is fixed at 1s so *_per_sec values are the true sustained rate)
Applied at both fresh boot (pre-boot Drive::rate_limiter) and snapshot resume (PATCH /drives, reconciled before resume())

Closes #46

Notes on burst semantics

bandwidth_burst_bytes / iops_burst map to Firecracker's one_time_burst: a separate allowance granted once at VM start, consumed before the sustained bucket and not replenished. It absorbs the initial boot I/O spike; it does not raise the steady-state rate.

Changes

config/default.toml: Add [machine.disk_rate_limit] section (disabled by default)
src/cfg.rs: Add DiskRateLimitConfig with validation (disabled -> skip; reject burst-without-sustained; reject values > i64::MAX)
src/sandbox/firecracker/config.rs: Carry effective config in FirecrackerCommonConfig so fresh boot and resume apply the same config and it persists across pause/resume
src/sandbox/firecracker/instance.rs: Add patch_drive_rate_limiter() for the resume path
src/sandbox/firecracker/sandbox.rs: Build the pre-boot limiter for fresh drives; on resume, reconcile per dimension and use an all-zero token bucket to explicitly disable an inherited dimension

Test plan

Build passes (cargo build --release)
Baseline: sandbox disk I/O without limiting (~1.8 GB/s write)
Rate-limited: 100 MB/s + 3000 IOPS configured (~12-28 MB/s)
Resume path: limiter reconciled before resume(); inherited limiter cleared when disabled
Integration test with cargo test

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/48 **Author:** [@rogeroger-yu](https://github.com/rogeroger-yu) **Created:** 7/28/2026 **Status:** ✅ Merged **Merged:** 8/7/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/disk-rate-limit-firecracker` --- ### 📝 Commits (7) - [`ef01c5c`](https://github.com/kvcache-ai/AgentENV/commit/ef01c5c140b200f7bb883fe0e205ee3ab496be46) feat(sandbox): add Firecracker disk I/O rate limiting (bandwidth + IOPS) - [`ab2ab1f`](https://github.com/kvcache-ai/AgentENV/commit/ab2ab1f52b5b4c5c2806344fd9d3bad6fa3a73e7) fix(sandbox): correct disk rate limiter refill and resume reconciliation - [`16f1722`](https://github.com/kvcache-ai/AgentENV/commit/16f17220cbef92bfc69e93359a1ee560c4f34542) fix(sandbox): apply fresh sandbox's own disk rate limit config - [`d394ede`](https://github.com/kvcache-ai/AgentENV/commit/d394ede25470b03f2b8e30d06f3156c168fa0c0d) fix(sandbox): apply disk rate limiter before I/O and reconcile per dimension - [`26994b8`](https://github.com/kvcache-ai/AgentENV/commit/26994b8e07e8e2ffde1dc6c34034ad975f65be85) fix(sandbox): refine disk rate limit validation and disable semantics - [`3535c8b`](https://github.com/kvcache-ai/AgentENV/commit/3535c8bffe51a4e5e0013ce4d461a52882384ac8) fix(sandbox): use all-zero token bucket as disable sentinel and fix fmt - [`de45f98`](https://github.com/kvcache-ai/AgentENV/commit/de45f98e66bac49344d302fbb0d38cd0f5906a19) docs(cfg): clarify one_time_burst is a one-time start-of-VM allowance ### 📊 Changes **5 files changed** (+409 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `config/default.toml` (+7 -0) 📝 `src/cfg.rs` (+135 -0) 📝 `src/sandbox/firecracker/config.rs` (+9 -0) 📝 `src/sandbox/firecracker/instance.rs` (+22 -2) 📝 `src/sandbox/firecracker/sandbox.rs` (+236 -1) </details> ### 📄 Description ## Summary - Wire Firecracker's per-drive TokenBucket rate limiter into the sandbox lifecycle - Configurable via `[machine.disk_rate_limit]` with **bandwidth, IOPS, and one-time burst** settings (refill period is fixed at 1s so `*_per_sec` values are the true sustained rate) - Applied at both **fresh boot (pre-boot `Drive::rate_limiter`)** and **snapshot resume (`PATCH /drives`, reconciled before `resume()`)** Closes #46 ## Notes on burst semantics `bandwidth_burst_bytes` / `iops_burst` map to Firecracker's `one_time_burst`: a separate allowance granted **once at VM start**, consumed before the sustained bucket and **not replenished**. It absorbs the initial boot I/O spike; it does not raise the steady-state rate. ## Changes - `config/default.toml`: Add `[machine.disk_rate_limit]` section (disabled by default) - `src/cfg.rs`: Add `DiskRateLimitConfig` with validation (disabled -> skip; reject burst-without-sustained; reject values > i64::MAX) - `src/sandbox/firecracker/config.rs`: Carry effective config in `FirecrackerCommonConfig` so fresh boot and resume apply the same config and it persists across pause/resume - `src/sandbox/firecracker/instance.rs`: Add `patch_drive_rate_limiter()` for the resume path - `src/sandbox/firecracker/sandbox.rs`: Build the pre-boot limiter for fresh drives; on resume, reconcile per dimension and use an all-zero token bucket to explicitly disable an inherited dimension ## Test plan - [x] Build passes (`cargo build --release`) - [x] Baseline: sandbox disk I/O without limiting (~1.8 GB/s write) - [x] Rate-limited: 100 MB/s + 3000 IOPS configured (~12-28 MB/s) - [x] Resume path: limiter reconciled before `resume()`; inherited limiter cleared when disabled - [ ] Integration test with `cargo test` --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:07 +00:00