refactor(gateway): drop image_pull_policy from shared inheritance

Kubernetes and Podman use mutually-incompatible vocabularies for the same
TOML key:

  - Kubernetes: `Always | IfNotPresent | Never` (free-form string passed
    verbatim to the K8s API).
  - Podman: `always | missing | never | newer` (strict lowercase enum
    deserialised into `ImagePullPolicy`).

No value means the same thing in both drivers. Sharing the key at
`[openshell.gateway]` scope and inheriting it into every active driver's
table meant any value safe for one driver was either wrong or silently
dropped for the other (`IfNotPresent` → `ImagePullPolicy::Missing` after
`.unwrap_or_default()`). Operators run one driver per gateway, so the
"shared default" never pays for itself.

Make `image_pull_policy` driver-local:

  - Remove the field from `GatewayFileSection` and from
    `inheritable_keys()` for both Kubernetes and Podman.
  - Drop the file→`RunArgs` merge for the gateway-scope key.
  - Stop unconditionally clobbering the driver value with
    `config.sandbox_image_pull_policy` in the runtime wiring — only apply
    the CLI/env override when it was set (and, for Podman, only when it
    parses into the lowercase enum).
  - Move the key under `[openshell.drivers.kubernetes]` and
    `[openshell.drivers.podman]` in every example, the RFC, the
    architecture doc, and the Helm-rendered gateway ConfigMap.

The supervisor pull policy follows the same shape: it is K8s-only and
moves into `[openshell.drivers.kubernetes]` alongside `image_pull_policy`
in the Helm template.

Author: TaylorMutch

architecture/gateway.md

@@ -213,12 +213,18 @@ worked example and RFC 0003 for the full schema.
 ### Driver inheritance
 
 `[openshell.gateway]` carries a small set of values (`default_image`,
-`supervisor_image`, `image_pull_policy`, `guest_tls_ca/cert/key`,
-`client_tls_secret_name`, `host_gateway_ip`, `enable_user_namespaces`) that
-are inherited into each driver's `[openshell.drivers.<name>]` table when
-the driver-specific table does not override them. The allowlist is
-per-driver so a gateway-wide default cannot land in a driver that does not
-understand it (e.g. `client_tls_secret_name` is K8s-only).
+`supervisor_image`, `guest_tls_ca/cert/key`, `client_tls_secret_name`,
+`host_gateway_ip`, `enable_user_namespaces`) that are inherited into each
+driver's `[openshell.drivers.<name>]` table when the driver-specific table
+does not override them. The allowlist is per-driver so a gateway-wide
+default cannot land in a driver that does not understand it (e.g.
+`client_tls_secret_name` is K8s-only).
+
+`image_pull_policy` is intentionally **not** inheritable: Kubernetes uses
+`Always | IfNotPresent | Never` (passed verbatim to the K8s API) while
+Podman uses the lowercase enum `always | missing | never | newer`. No
+value means the same thing in both, so the key lives only under each
+driver's own table.
 
 Driver-specific values that are not part of the inheritance allowlist
 (e.g. K8s `namespace`, Podman `socket_path`, VM `vcpus`) only come from

crates/openshell-server/src/cli.rs

@@ -580,12 +580,6 @@ fn merge_file_into_args(args: &mut RunArgs, file: &GatewayFileSection, matches:
     {
         args.sandbox_image = Some(image.clone());
     }
-    if let Some(policy) = &file.image_pull_policy
-        && args.sandbox_image_pull_policy.is_none()
-        && arg_defaulted(matches, "sandbox_image_pull_policy")
-    {
-        args.sandbox_image_pull_policy = Some(policy.clone());
-    }
     if let Some(secret) = &file.client_tls_secret_name
         && args.client_tls_secret_name.is_none()
         && arg_defaulted(matches, "client_tls_secret_name")

crates/openshell-server/src/config_file.rs

@@ -116,8 +116,6 @@ pub struct GatewayFileSection {
     #[serde(default)]
     pub supervisor_image: Option<String>,
     #[serde(default)]
-    pub image_pull_policy: Option<String>,
-    #[serde(default)]
     pub client_tls_secret_name: Option<String>,
     #[serde(default)]
     pub host_gateway_ip: Option<String>,
@@ -254,7 +252,6 @@ fn inheritable_keys(driver: ComputeDriverKind) -> &'static [&'static str] {
         ComputeDriverKind::Kubernetes => &[
             "default_image",
             "supervisor_image",
-            "image_pull_policy",
             "client_tls_secret_name",
             "host_gateway_ip",
             "ssh_handshake_skew_secs",
@@ -269,7 +266,6 @@ fn inheritable_keys(driver: ComputeDriverKind) -> &'static [&'static str] {
         ComputeDriverKind::Podman => &[
             "default_image",
             "supervisor_image",
-            "image_pull_policy",
             "guest_tls_ca",
             "guest_tls_cert",
             "guest_tls_key",
@@ -288,7 +284,6 @@ fn gateway_inherited_value(g: &GatewayFileSection, key: &str) -> Option<toml::Va
     match key {
         "default_image" => g.default_image.as_deref().map(string_value),
         "supervisor_image" => g.supervisor_image.as_deref().map(string_value),
-        "image_pull_policy" => g.image_pull_policy.as_deref().map(string_value),
         "client_tls_secret_name" => g.client_tls_secret_name.as_deref().map(string_value),
         "host_gateway_ip" => g.host_gateway_ip.as_deref().map(string_value),
         "ssh_handshake_skew_secs" => g.ssh_handshake_skew_secs.and_then(skew_value),
@@ -349,7 +344,6 @@ compute_drivers = ["kubernetes"]
 sandbox_namespace = "agents"
 default_image = "ghcr.io/nvidia/openshell/sandbox:latest"
 supervisor_image = "ghcr.io/nvidia/openshell/supervisor:latest"
-image_pull_policy = "IfNotPresent"
 client_tls_secret_name = "openshell-sandbox-tls"
 
 [openshell.gateway.tls]
@@ -442,7 +436,6 @@ version = 2
         let gateway = GatewayFileSection {
             default_image: Some("ghcr.io/nvidia/openshell/sandbox:0.9".to_string()),
             supervisor_image: Some("ghcr.io/nvidia/openshell/supervisor:0.9".to_string()),
-            image_pull_policy: Some("IfNotPresent".to_string()),
             ..Default::default()
         };
         let raw = toml::toml! {

crates/openshell-server/src/lib.rs

@@ -588,8 +588,14 @@ async fn build_compute_runtime(
             // file + CLI/env at startup.
             k8s.namespace.clone_from(&config.sandbox_namespace);
             k8s.default_image.clone_from(&config.sandbox_image);
-            k8s.image_pull_policy
-                .clone_from(&config.sandbox_image_pull_policy);
+            // Only let the gateway-wide CLI/env value overwrite the per-driver
+            // file value when it was actually set — otherwise the empty CLI
+            // default would silently clobber `image_pull_policy` configured
+            // under `[openshell.drivers.kubernetes]`.
+            if !config.sandbox_image_pull_policy.is_empty() {
+                k8s.image_pull_policy
+                    .clone_from(&config.sandbox_image_pull_policy);
+            }
             k8s.grpc_endpoint.clone_from(&config.grpc_endpoint);
             k8s.ssh_socket_path
                 .clone_from(&config.sandbox_ssh_socket_path);
@@ -677,7 +683,16 @@ async fn build_compute_runtime(
             // Shared fields are sourced from Config (which already merged
             // file + CLI/env at startup).
             podman.default_image.clone_from(&config.sandbox_image);
-            podman.image_pull_policy = config.sandbox_image_pull_policy.parse().unwrap_or_default();
+            // The CLI/env `image_pull_policy` is K8s-shaped
+            // (e.g. `IfNotPresent`) and won't parse into Podman's lowercase
+            // enum. Only apply it when the operator set a Podman-shaped value
+            // explicitly; otherwise keep whatever `[openshell.drivers.podman]`
+            // (or the struct default) provided.
+            if !config.sandbox_image_pull_policy.is_empty()
+                && let Ok(policy) = config.sandbox_image_pull_policy.parse()
+            {
+                podman.image_pull_policy = policy;
+            }
             podman.grpc_endpoint.clone_from(&config.grpc_endpoint);
             podman.gateway_port = config.bind_address.port();
             podman

deploy/helm/openshell/templates/gateway-config.yaml

@@ -33,12 +33,6 @@ data:
     sandbox_namespace     = {{ include "openshell.sandboxNamespace" . | quote }}
     default_image         = {{ .Values.server.sandboxImage | quote }}
     supervisor_image      = {{ include "openshell.supervisorImage" . | quote }}
-    {{- if .Values.server.sandboxImagePullPolicy }}
-    image_pull_policy     = {{ .Values.server.sandboxImagePullPolicy | quote }}
-    {{- end }}
-    {{- if .Values.supervisor.image.pullPolicy }}
-    supervisor_image_pull_policy = {{ .Values.supervisor.image.pullPolicy | quote }}
-    {{- end }}
     grpc_endpoint         = {{ include "openshell.grpcEndpoint" . | quote }}
     {{- if .Values.server.sshGatewayHost }}
     ssh_gateway_host      = {{ .Values.server.sshGatewayHost | quote }}
@@ -99,3 +93,9 @@ data:
 
     [openshell.drivers.kubernetes]
     supervisor_sideload_method = {{ include "openshell.supervisorSideloadMethod" . | quote }}
+    {{- if .Values.server.sandboxImagePullPolicy }}
+    image_pull_policy            = {{ .Values.server.sandboxImagePullPolicy | quote }}
+    {{- end }}
+    {{- if .Values.supervisor.image.pullPolicy }}
+    supervisor_image_pull_policy = {{ .Values.supervisor.image.pullPolicy | quote }}
+    {{- end }}

examples/gateway/gateway.example.toml

@@ -40,8 +40,12 @@ enable_loopback_service_http = true
 # when the driver-specific table does not override them.
 default_image          = "ghcr.io/nvidia/openshell/sandbox:latest"
 supervisor_image       = "ghcr.io/nvidia/openshell/supervisor:latest"
-image_pull_policy      = "IfNotPresent"
 client_tls_secret_name = "openshell-client-tls"
+# `image_pull_policy` is intentionally NOT a shared key: Kubernetes uses
+# `Always | IfNotPresent | Never` (passed as a string to the K8s API) while
+# Podman uses the lowercase `always | missing | never | newer` enum. There is
+# no value that means the same thing in both, so set it under the relevant
+# `[openshell.drivers.<name>]` table instead.
 
 # Gateway listener TLS (distinct from the per-driver guest_tls_*).
 [openshell.gateway.tls]
@@ -63,8 +67,9 @@ user_role     = "openshell-user"
 # over the inherited value.
 
 [openshell.drivers.kubernetes]
-namespace     = "agents"
-grpc_endpoint = "https://openshell-gateway.agents.svc:8080"
+namespace         = "agents"
+grpc_endpoint     = "https://openshell-gateway.agents.svc:8080"
+image_pull_policy = "IfNotPresent"   # K8s vocabulary: Always | IfNotPresent | Never
 
 [openshell.drivers.docker]
 network_name = "openshell-docker"
@@ -74,6 +79,7 @@ network_name = "openshell-docker"
 socket_path       = "/run/podman/podman.sock"
 network_name      = "openshell"
 stop_timeout_secs = 10
+image_pull_policy = "missing"   # Podman vocabulary: always | missing | never | newer
 
 [openshell.drivers.vm]
 state_dir      = "/var/lib/openshell/vm"

examples/gateway/kubernetes.example.toml

@@ -20,7 +20,6 @@ compute_drivers       = ["kubernetes"]
 # Shared defaults inherited into [openshell.drivers.kubernetes].
 default_image          = "ghcr.io/nvidia/openshell/sandbox:latest"
 supervisor_image       = "ghcr.io/nvidia/openshell/supervisor:latest"
-image_pull_policy      = "IfNotPresent"
 client_tls_secret_name = "openshell-client-tls"
 
 [openshell.gateway.tls]
@@ -31,6 +30,7 @@ client_ca_path = "/etc/openshell-tls/client-ca/ca.crt"
 [openshell.drivers.kubernetes]
 namespace                  = "agents"
 grpc_endpoint              = "https://openshell-gateway.agents.svc:8080"
+image_pull_policy          = "IfNotPresent"
 # Use the image volume on K8s >= 1.35 (GA in 1.36); switch to "init-container"
 # on older clusters or where the ImageVolume feature gate is off.
 supervisor_sideload_method = "image-volume"

examples/gateway/podman.example.toml

@@ -18,7 +18,6 @@ compute_drivers = ["podman"]
 # Shared defaults inherited into [openshell.drivers.podman].
 default_image     = "ghcr.io/nvidia/openshell/sandbox:latest"
 supervisor_image  = "ghcr.io/nvidia/openshell/supervisor:latest"
-image_pull_policy = "missing"   # Podman pull policy: always | missing | never | newer
 guest_tls_ca      = "/etc/openshell/certs/ca.pem"
 guest_tls_cert    = "/etc/openshell/certs/client.pem"
 guest_tls_key     = "/etc/openshell/certs/client-key.pem"
@@ -28,3 +27,4 @@ guest_tls_key     = "/etc/openshell/certs/client-key.pem"
 socket_path       = "/run/user/1000/podman/podman.sock"
 network_name      = "openshell"
 stop_timeout_secs = 10
+image_pull_policy = "missing"   # Podman vocabulary: always | missing | never | newer

rfc/0003-gateway-configuration/README.md

@@ -142,7 +142,7 @@ guest_tls_key     = "/etc/openshell/certs/client-key.pem"
 [openshell.drivers.podman]
 socket_path       = "/run/podman/podman.sock"
 default_image     = "ghcr.io/nvidia/openshell/sandbox:latest"
-image_pull_policy = "IfNotPresent"
+image_pull_policy = "missing"   # Podman vocabulary: always | missing | never | newer
 supervisor_image  = "ghcr.io/nvidia/openshell/supervisor:latest"
 network_name      = "openshell"
 stop_timeout_secs = 10