feat(sandbox): add Firecracker disk I/O rate limiting (bandwidth + IOPS)

config/default.toml

@@ -110,6 +110,13 @@ veth_cidr = "10.12.0.0/16"
 mem_size_mib = 1024
 vcpu_count = 2
 
+[machine.disk_rate_limit]
+# enabled = true
+# bandwidth_bytes_per_sec = 104857600   # 100 MB/s sustained
+# bandwidth_burst_bytes = 10485760      # 10 MB one-time burst at VM start (not replenished)
+# iops = 3000
+# iops_burst = 500                       # one-time IOPS burst at VM start (not replenished)
+
 [envd]
 version = "0.5.15"
 init_timeout_secs = 60

src/cfg.rs

@@ -252,6 +252,32 @@ pub struct MachineConfig {
     pub vcpu_count: u32,
     #[config(default = 1024u32)]
     pub mem_size_mib: u32,
+    #[config(nested)]
+    pub disk_rate_limit: DiskRateLimitConfig,
+}
+
+#[derive(Debug, Config, Clone, Default, serde::Serialize, serde::Deserialize)]
+pub struct DiskRateLimitConfig {
+    /// Enable per-sandbox disk I/O rate limiting via Firecracker's virtio-blk rate limiter.
+    #[config(default = false)]
+    pub enabled: bool,
+    /// Sustained disk bandwidth limit in bytes per second (0 = unlimited).
+    #[config(default = 0u64)]
+    pub bandwidth_bytes_per_sec: u64,
+    /// One-time bandwidth burst in bytes, granted once when the VM starts (maps
+    /// to Firecracker's `one_time_burst`). It is a separate allowance consumed
+    /// before the sustained bucket and is not replenished after use, so it only
+    /// absorbs the initial I/O spike; it does not raise the steady-state rate.
+    #[config(default = 0u64)]
+    pub bandwidth_burst_bytes: u64,
+    /// Sustained IOPS limit (0 = unlimited).
+    #[config(default = 0u64)]
+    pub iops: u64,
+    /// One-time IOPS burst, granted once when the VM starts (maps to
+    /// Firecracker's `one_time_burst`). Consumed before the sustained bucket and
+    /// not replenished, so it only absorbs the initial spike, not steady state.
+    #[config(default = 0u64)]
+    pub iops_burst: u64,
 }
 
 #[derive(Debug, Config, Clone)]
@@ -778,6 +804,52 @@ impl AppConfig {
         }
         self.validate_memory_snapshot_background_download()?;
         self.validate_overlaybd_global_config_paths()?;
+        self.validate_disk_rate_limit()?;
+        Ok(())
+    }
+
+    /// Reject internally inconsistent or out-of-range disk rate limit configs so
+    /// operator mistakes fail at load time. Disabled sections are skipped: both
+    /// the fresh-boot and snapshot-resume paths ignore all configured values when
+    /// disabled, so dormant/pre-staged values must not block startup.
+    ///
+    /// When enabled: a one-time burst is meaningless without a nonzero sustained
+    /// limit (`build_disk_rate_limiter` only creates a bucket when the sustained
+    /// value is > 0, so a burst paired with a zero sustained limit is silently
+    /// ignored), and every value must fit Firecracker's signed `i64` token-bucket
+    /// fields (the consumer converts with `i64::try_from`, so an out-of-range
+    /// value would otherwise only fail later at sandbox start).
+    fn validate_disk_rate_limit(&self) -> Result<()> {
+        let cfg = &self.machine.disk_rate_limit;
+        if !cfg.enabled {
+            return Ok(());
+        }
+        if cfg.bandwidth_burst_bytes > 0 && cfg.bandwidth_bytes_per_sec == 0 {
+            bail!(
+                "machine.disk_rate_limit: bandwidth_burst_bytes is set but \
+                 bandwidth_bytes_per_sec is 0; a burst requires a nonzero sustained limit"
+            );
+        }
+        if cfg.iops_burst > 0 && cfg.iops == 0 {
+            bail!(
+                "machine.disk_rate_limit: iops_burst is set but iops is 0; \
+                 a burst requires a nonzero sustained limit"
+            );
+        }
+        for (name, value) in [
+            ("bandwidth_bytes_per_sec", cfg.bandwidth_bytes_per_sec),
+            ("bandwidth_burst_bytes", cfg.bandwidth_burst_bytes),
+            ("iops", cfg.iops),
+            ("iops_burst", cfg.iops_burst),
+        ] {
+            if value > i64::MAX as u64 {
+                bail!(
+                    "machine.disk_rate_limit.{name} ({value}) exceeds the maximum \
+                     supported value {}",
+                    i64::MAX
+                );
+            }
+        }
         Ok(())
     }
 
@@ -1110,6 +1182,69 @@ mod tests {
         );
     }
 
+    #[test]
+    fn validate_rejects_disk_burst_without_sustained() {
+        let mut config = AppConfig::default();
+        config.machine.disk_rate_limit.enabled = true;
+        config.machine.disk_rate_limit.bandwidth_bytes_per_sec = 0;
+        config.machine.disk_rate_limit.bandwidth_burst_bytes = 1024;
+        let err = config.validate().unwrap_err();
+        assert!(
+            err.to_string().contains("bandwidth_burst_bytes is set but"),
+            "unexpected error: {err}"
+        );
+
+        let mut config = AppConfig::default();
+        config.machine.disk_rate_limit.enabled = true;
+        config.machine.disk_rate_limit.iops = 0;
+        config.machine.disk_rate_limit.iops_burst = 500;
+        let err = config.validate().unwrap_err();
+        assert!(
+            err.to_string().contains("iops_burst is set but"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_skips_disabled_disk_rate_limit() {
+        // A disabled section is ignored at runtime, so even internally
+        // inconsistent or out-of-range values must not block startup.
+        let mut config = AppConfig::default();
+        config.machine.disk_rate_limit.enabled = false;
+        config.machine.disk_rate_limit.bandwidth_bytes_per_sec = 0;
+        config.machine.disk_rate_limit.bandwidth_burst_bytes = 1024;
+        config.machine.disk_rate_limit.iops = u64::MAX;
+        config
+            .validate()
+            .expect("disabled disk rate limit config is not validated");
+    }
+
+    #[test]
+    fn validate_rejects_disk_rate_limit_above_i64_max() {
+        let mut config = AppConfig::default();
+        config.machine.disk_rate_limit.enabled = true;
+        config.machine.disk_rate_limit.bandwidth_bytes_per_sec = i64::MAX as u64 + 1;
+        let err = config.validate().unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("machine.disk_rate_limit.bandwidth_bytes_per_sec"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_accepts_consistent_disk_rate_limit() {
+        let mut config = AppConfig::default();
+        config.machine.disk_rate_limit.enabled = true;
+        config.machine.disk_rate_limit.bandwidth_bytes_per_sec = 104_857_600;
+        config.machine.disk_rate_limit.bandwidth_burst_bytes = 10_485_760;
+        config.machine.disk_rate_limit.iops = 3000;
+        config.machine.disk_rate_limit.iops_burst = 500;
+        config
+            .validate()
+            .expect("consistent disk rate limit config passes");
+    }
+
     #[test]
     fn validate_rejects_shared_overlaybd_global_config_path() {
         let mut config = AppConfig::default();

src/sandbox/firecracker/config.rs

@@ -150,6 +150,12 @@ pub struct FirecrackerCommonConfig {
     /// start-fresh / start-resume hooks. Persisted with snapshot configs.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub custom_extension_params: Option<crate::sandbox::CustomExtensionParams>,
+    /// Effective disk I/O rate limit for the user rootfs drive. Carried in the
+    /// common config so fresh boot and snapshot resume apply the same config
+    /// and it persists across pause/resume, instead of each path reaching for
+    /// the process-global config.
+    #[serde(default)]
+    pub disk_rate_limit: crate::cfg::DiskRateLimitConfig,
 }
 
 impl FirecrackerCommonConfig {
@@ -181,6 +187,7 @@ impl FirecrackerCommonConfig {
             cpu_config_json: None,
             network_policy: None,
             custom_extension_params: None,
+            disk_rate_limit: crate::cfg::DiskRateLimitConfig::default(),
         }
     }
 
@@ -191,6 +198,7 @@ impl FirecrackerCommonConfig {
 
         let mut common = Self::new(firecracker_binary, tools_drive_version, runtime_policy);
         common.envd_version = config.envd.version.clone();
+        common.disk_rate_limit = config.machine.disk_rate_limit.clone();
         common.rootfs_allow_shrink = config.ublk.overlaybd.allow_shrink;
         common.control_plane_port = config.tools.control_plane_port;
         common.firecracker_work_base_dir = config.firecracker.work_dir.clone();
@@ -346,6 +354,7 @@ impl FirecrackerSandboxConfig {
             read_only: false,
             runtime_upper_mode: UpperMode::LogStructured,
         });
+        common.disk_rate_limit = app_config.machine.disk_rate_limit;
         Self {
             common,
             kernel_image,

src/sandbox/firecracker/instance.rs

@@ -8,7 +8,7 @@ use anyhow::{bail, Context, Result};
 use firecracker_client::models::drive::IoEngine;
 use firecracker_client::models::instance_action_info::ActionType;
 use firecracker_client::models::vm::State as VmState;
-use firecracker_client::models::{mmds_config::Version as MmdsVersion, MmdsConfig};
+use firecracker_client::models::{mmds_config::Version as MmdsVersion, MmdsConfig, PartialDrive};
 use firecracker_client::models::{
     Balloon, BootSource, DirtyMemoryRanges, Drive, InstanceActionInfo, Logger,
     MachineConfiguration, MemoryBackend, NetworkInterface, NetworkOverride, RateLimiter,
@@ -311,7 +311,10 @@ impl FirecrackerInstance {
     ///
     /// `is_root_device` must be `true` for the boot rootfs drive and `false`
     /// for any non-root extra drive. This API is only used during the
-    /// pre-boot configuration phase.
+    /// pre-boot configuration phase. `rate_limiter` attaches a pre-boot limiter
+    /// so throttling is in force from the guest's first I/O (a post-start PATCH
+    /// would leave a brief unthrottled window).
+    #[allow(clippy::too_many_arguments)]
     pub async fn add_drive(
         &self,
         drive_id: &str,
@@ -320,19 +323,36 @@ impl FirecrackerInstance {
         read_only: bool,
         direct: bool,
         io_engine: IoEngine,
+        rate_limiter: Option<Box<RateLimiter>>,
     ) -> Result<()> {
         let mut drive = Drive::new(drive_id.to_string(), is_root_device);
         drive.path_on_host = Some(path_on_host.to_string_lossy().into_owned());
         drive.is_read_only = Some(read_only);
         drive.direct = Some(direct);
         drive.io_engine = Some(io_engine);
+        drive.rate_limiter = rate_limiter;
         let path = format!("/drives/{}", drive_id);
         self.client
             .request_no_content(Method::PUT, &path, Some(&drive))
             .await
             .with_context(|| format!("Failed to add/update drive {}", drive_id))
     }
 
+    /// Updates the rate limiter on a running VM's drive via PATCH.
+    pub async fn patch_drive_rate_limiter(
+        &self,
+        drive_id: &str,
+        rate_limiter: Box<RateLimiter>,
+    ) -> Result<()> {
+        let mut partial = PartialDrive::new(drive_id.to_string());
+        partial.rate_limiter = Some(rate_limiter);
+        let path = format!("/drives/{}", drive_id);
+        self.client
+            .request_no_content(Method::PATCH, &path, Some(&partial))
+            .await
+            .with_context(|| format!("Failed to patch rate limiter on drive {}", drive_id))
+    }
+
     /// Adds a network interface.
     /// Pre-boot only.
     pub async fn add_network_interface(