feat(podman): make container health check interval configurable (#1833)

* feat(podman): make container health check interval configurable

The Podman driver hardcoded a 3-second health check interval, which
spawns a conmon subprocess on every tick. On systems running multiple
sandboxes this creates sustained process churn and unnecessary CPU
overhead.

Add a `health_check_interval_secs` field to `PodmanComputeConfig`
(default: 10s) and wire it into the container health check spec.
Operators can tune it further via `[openshell.drivers.podman]` in
gateway.toml.

Signed-off-by: Sagi Shnaidman <sshnaidm@redhat.com>

* docs(podman): document health_check_interval_secs config field

Signed-off-by: Sagi Shnaidman <sshnaidm@redhat.com>

* docs(podman): document health_check_interval_secs zero-disables behavior

Signed-off-by: Sagi Shnaidman <sshnaidm@redhat.com>

---------

Signed-off-by: Sagi Shnaidman <sshnaidm@redhat.com>

Author: sshnaidm

crates/openshell-driver-podman/src/config.rs

@@ -126,8 +126,18 @@ pub struct PodmanComputeConfig {
     /// `template.driver_config`.
     #[serde(default)]
     pub enable_bind_mounts: bool,
+    /// Health check interval in seconds for sandbox containers.
+    ///
+    /// Podman runs the health check command at this interval to determine
+    /// container readiness. Lower values detect readiness faster but
+    /// increase process churn (each check spawns a conmon subprocess).
+    /// Set to `0` to disable health checks entirely.
+    /// Defaults to [`DEFAULT_HEALTH_CHECK_INTERVAL_SECS`] (10 seconds).
+    pub health_check_interval_secs: u64,
 }
 
+pub const DEFAULT_HEALTH_CHECK_INTERVAL_SECS: u64 = 10;
+
 impl PodmanComputeConfig {
     /// Returns `true` when all three TLS paths are configured.
     #[must_use]
@@ -251,6 +261,7 @@ impl Default for PodmanComputeConfig {
             guest_tls_key: None,
             sandbox_pids_limit: DEFAULT_SANDBOX_PIDS_LIMIT,
             enable_bind_mounts: false,
+            health_check_interval_secs: DEFAULT_HEALTH_CHECK_INTERVAL_SECS,
         }
     }
 }
@@ -273,6 +284,10 @@ impl std::fmt::Debug for PodmanComputeConfig {
             .field("guest_tls_key", &self.guest_tls_key)
             .field("sandbox_pids_limit", &self.sandbox_pids_limit)
             .field("enable_bind_mounts", &self.enable_bind_mounts)
+            .field(
+                "health_check_interval_secs",
+                &self.health_check_interval_secs,
+            )
             .finish()
     }
 }
@@ -314,6 +329,15 @@ mod tests {
         });
     }
 
+    #[test]
+    fn default_config_sets_health_check_interval() {
+        let cfg = PodmanComputeConfig::default();
+        assert_eq!(
+            cfg.health_check_interval_secs,
+            DEFAULT_HEALTH_CHECK_INTERVAL_SECS
+        );
+    }
+
     #[test]
     fn default_config_sets_driver_owned_pids_limit() {
         let cfg = PodmanComputeConfig::default();

crates/openshell-driver-podman/src/container.rs

@@ -880,7 +880,7 @@ pub fn try_build_container_spec_with_token(
                     openshell_core::config::DEFAULT_SSH_PORT
                 ),
             ],
-            interval: 3_000_000_000,
+            interval: config.health_check_interval_secs * 1_000_000_000,
             timeout: 2_000_000_000,
             retries: 10,
             start_period: 5_000_000_000,
@@ -1328,6 +1328,19 @@ mod tests {
         );
     }
 
+    #[test]
+    fn container_spec_healthcheck_interval_from_config() {
+        let sandbox = test_sandbox("test-id", "test-name");
+        let mut config = test_config();
+        config.health_check_interval_secs = 30;
+        let spec = build_container_spec(&sandbox, &config);
+
+        let interval = spec["healthconfig"]["Interval"]
+            .as_u64()
+            .expect("healthcheck interval should be a u64");
+        assert_eq!(interval, 30_000_000_000);
+    }
+
     #[test]
     fn container_spec_required_vars_cannot_be_overridden() {
         use openshell_core::proto::compute::v1::{DriverSandboxSpec, DriverSandboxTemplate};

crates/openshell-driver-podman/src/main.rs

@@ -135,7 +135,7 @@ async fn main() -> Result<()> {
         guest_tls_cert: args.podman_tls_cert,
         guest_tls_key: args.podman_tls_key,
         sandbox_pids_limit: args.sandbox_pids_limit,
-        enable_bind_mounts: false,
+        ..PodmanComputeConfig::default()
     })
     .await
     .into_diagnostic()?;

docs/reference/gateway-config.mdx

@@ -262,6 +262,10 @@ guest_tls_key           = "/etc/openshell/certs/client-key.pem"
 enable_bind_mounts      = false
 # Set to 0 to leave Podman's runtime default unchanged.
 sandbox_pids_limit      = 2048
+# Health check interval in seconds. Lower values detect readiness faster
+# but increase process churn (each check spawns a conmon subprocess).
+# Set to 0 to disable health checks entirely. Default: 10.
+health_check_interval_secs = 10
 ```
 
 ### MicroVM