Skip to content

Commit a48920a

Browse files
authored
feat(helm): add sandbox UID and GID values (#3947)
* feat(helm): add sandbox UID and GID values Closes #2697 Signed-off-by: Eric Curtin <[email protected]> * fix(helm): reject boolean sandbox UID and GID Signed-off-by: Eric Curtin <[email protected]> --------- Signed-off-by: Eric Curtin <[email protected]>
1 parent f7273e4 commit a48920a

7 files changed

Lines changed: 127 additions & 0 deletions

File tree

‎deploy/helm/openshell/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -450,13 +450,15 @@ discovery endpoint or its TLS CA.
450450
| server.policyValidationFailureMode | string | `"fail_closed"` | Posture when a candidate sandbox policy fails validation. `fail_closed` deactivates the previous policy; `retain_last_valid` keeps it active. |
451451
| server.providerTokenGrants.spiffe.enabled | bool | `false` | Mount the SPIFFE Workload API socket into gateway and sandbox pods for dynamic provider token grants. |
452452
| server.providerTokenGrants.spiffe.workloadApiSocketPath | string | `"/spiffe-workload-api/spire-agent.sock"` | Path to the SPIFFE Workload API socket mounted into gateway and sandbox pods. |
453+
| server.sandboxGid | string | `""` | GID for sandbox pods (`sandbox_gid`). Empty (default) = same as sandboxUid. Must be an integer between 1 and 4294967294. |
453454
| server.sandboxImagePullSecrets | list | `[]` | Image pull secrets attached to sandbox pods. Referenced Secrets must exist in the sandbox namespace. |
454455
| server.sandboxJwt.gatewayId | string | `""` | Stable gateway identity embedded in iss/aud of every minted token. Defaults to the release name so HA replicas share identity. |
455456
| server.sandboxJwt.k8sSaTokenTtlSecs | int | `3600` | Lifetime (seconds) of the projected ServiceAccount token kubelet writes into each sandbox pod for the IssueSandboxToken bootstrap exchange. Kubelet enforces a minimum of 600s; the driver clamps values outside [600, 86400]. Default 3600 — generous, since the supervisor consumes the token within seconds of pod start. |
456457
| server.sandboxJwt.secretDefaultMode | string | `""` | File mode for the mounted JWT signing key Secret. Default 0400 (owner-read only). Override to 0440 or 0444 if the container UID does not match the volume file owner. |
457458
| server.sandboxJwt.signingSecretName | string | `""` | Name of the Opaque Secret holding the signing key material. Empty falls back to the chart fullname with "-jwt-keys" appended. |
458459
| server.sandboxJwt.ttlSecs | int | `3600` | Token TTL in seconds. Defaults to 3600 (1h). |
459460
| server.sandboxNamespace | string | `""` | Namespace where sandbox pods are created. Defaults to the Helm release namespace (.Release.Namespace) when left empty. |
461+
| server.sandboxUid | string | `""` | UID for sandbox pods (`sandbox_uid`). Empty (default) = use the OpenShift SCC namespace annotation if present, otherwise the driver default. Must be an integer between 1 and 4294967294. |
460462
| server.telemetryEnabled | bool | `true` | Enable anonymous OpenShell telemetry from the gateway and the sandbox supervisors it launches. |
461463
| server.tls.certSecretName | string | `"openshell-server-tls"` | K8s secret (type kubernetes.io/tls) with tls.crt and tls.key for the server. |
462464
| server.tls.clientCaSecretName | string | `"openshell-server-client-ca"` | K8s secret with ca.crt for client certificate verification (mTLS). Only used when enableMtls is true. Set to "" to disable client certificate verification for HTTPS-only mode. |

‎deploy/helm/openshell/templates/_helpers.tpl‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,23 @@ never
379379
{{- end -}}
380380
{{- end }}
381381

382+
{{/*
383+
Render a sandbox UID/GID chart value as an integer, or nothing when unset.
384+
Takes a dict with `name` (the values key, for errors) and `value`. The bounds
385+
match openshell_policy::MIN_SANDBOX_UID..=MAX_SANDBOX_UID. Helm parses YAML
386+
numbers as float64, so the integer conversion also avoids `2e+09` rendering.
387+
Booleans are rejected because they would otherwise convert to 1 or 0.
388+
*/}}
389+
{{- define "openshell.sandboxId" -}}
390+
{{- if not (or (kindIs "invalid" .value) (eq (toString .value) "")) -}}
391+
{{- $id := int64 .value -}}
392+
{{- if or (kindIs "bool" .value) (ne (float64 .value) (float64 $id)) (lt $id 1) (gt $id 4294967294) -}}
393+
{{- fail (printf "%s must be an integer between 1 and 4294967294" .name) -}}
394+
{{- end -}}
395+
{{- $id -}}
396+
{{- end -}}
397+
{{- end }}
398+
382399
{{/*
383400
Validate chart values that Helm would otherwise accept silently.
384401
*/}}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,12 @@ data:
247247
{{- if .Values.server.defaultRuntimeClassName }}
248248
default_runtime_class_name = {{ .Values.server.defaultRuntimeClassName | quote }}
249249
{{- end }}
250+
{{- with include "openshell.sandboxId" (dict "name" "server.sandboxUid" "value" .Values.server.sandboxUid) }}
251+
sandbox_uid = {{ . }}
252+
{{- end }}
253+
{{- with include "openshell.sandboxId" (dict "name" "server.sandboxGid" "value" .Values.server.sandboxGid) }}
254+
sandbox_gid = {{ . }}
255+
{{- end }}
250256
{{- if (.Values.supervisor.image.pullPolicy | default .Values.global.image.pullPolicy) }}
251257
supervisor_image_pull_policy = {{ include "openshell.canonicalImagePullPolicy" (.Values.supervisor.image.pullPolicy | default .Values.global.image.pullPolicy) | quote }}
252258
{{- end }}
Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
suite: sandbox UID and GID
5+
templates:
6+
- templates/gateway-config.yaml
7+
release:
8+
name: openshell
9+
namespace: my-namespace
10+
11+
tests:
12+
- it: omits sandbox_uid and sandbox_gid by default
13+
asserts:
14+
- notMatchRegex:
15+
path: data["gateway.toml"]
16+
pattern: 'sandbox_uid|sandbox_gid'
17+
18+
- it: renders sandbox_uid and sandbox_gid as integers
19+
set:
20+
server.sandboxUid: 1500
21+
server.sandboxGid: 2000
22+
asserts:
23+
- matchRegex:
24+
path: data["gateway.toml"]
25+
pattern: '(?m)^\s*sandbox_uid\s*=\s*1500$'
26+
- matchRegex:
27+
path: data["gateway.toml"]
28+
pattern: '(?m)^\s*sandbox_gid\s*=\s*2000$'
29+
30+
- it: renders sandbox_uid alone
31+
set:
32+
server.sandboxUid: 1500
33+
asserts:
34+
- matchRegex:
35+
path: data["gateway.toml"]
36+
pattern: '(?m)^\s*sandbox_uid\s*=\s*1500$'
37+
- notMatchRegex:
38+
path: data["gateway.toml"]
39+
pattern: 'sandbox_gid'
40+
41+
- it: renders large IDs without scientific notation
42+
set:
43+
server.sandboxUid: 1000680000
44+
server.sandboxGid: 4294967294
45+
asserts:
46+
- matchRegex:
47+
path: data["gateway.toml"]
48+
pattern: '(?m)^\s*sandbox_uid\s*=\s*1000680000$'
49+
- matchRegex:
50+
path: data["gateway.toml"]
51+
pattern: '(?m)^\s*sandbox_gid\s*=\s*4294967294$'
52+
53+
- it: rejects a zero sandbox UID
54+
set:
55+
server.sandboxUid: 0
56+
asserts:
57+
- failedTemplate:
58+
errorPattern: "server.sandboxUid must be an integer between 1 and 4294967294"
59+
60+
- it: rejects a sandbox GID above the allowed range
61+
set:
62+
server.sandboxGid: 4294967295
63+
asserts:
64+
- failedTemplate:
65+
errorPattern: "server.sandboxGid must be an integer between 1 and 4294967294"
66+
67+
- it: rejects a non-numeric sandbox UID
68+
set:
69+
server.sandboxUid: abc
70+
asserts:
71+
- failedTemplate:
72+
errorPattern: "server.sandboxUid must be an integer between 1 and 4294967294"
73+
74+
- it: rejects a fractional sandbox UID
75+
set:
76+
server.sandboxUid: 1500.5
77+
asserts:
78+
- failedTemplate:
79+
errorPattern: "server.sandboxUid must be an integer between 1 and 4294967294"
80+
81+
- it: rejects a boolean sandbox UID
82+
set:
83+
server.sandboxUid: true
84+
asserts:
85+
- failedTemplate:
86+
errorPattern: "server.sandboxUid must be an integer between 1 and 4294967294"
87+
88+
- it: rejects a boolean sandbox GID
89+
set:
90+
server.sandboxGid: true
91+
asserts:
92+
- failedTemplate:
93+
errorPattern: "server.sandboxGid must be an integer between 1 and 4294967294"

‎deploy/helm/openshell/values.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,13 @@ server:
328328
# Set to a RuntimeClass name (e.g. "kata-containers", "nvidia") to apply it
329329
# to all sandboxes that don't explicitly override it.
330330
defaultRuntimeClassName: ""
331+
# -- UID for sandbox pods (`sandbox_uid`). Empty (default) = use the OpenShift
332+
# SCC namespace annotation if present, otherwise the driver default. Must be
333+
# an integer between 1 and 4294967294.
334+
sandboxUid: ""
335+
# -- GID for sandbox pods (`sandbox_gid`). Empty (default) = same as
336+
# sandboxUid. Must be an integer between 1 and 4294967294.
337+
sandboxGid: ""
331338
# -- gRPC endpoint sandboxes call back into the gateway. Leave empty to derive
332339
# it from the chart fullname, release namespace, service port, and
333340
# disableTls flag, for example https://openshell.openshell.svc.cluster.local:8080.

‎docs/how-it-works/gateways/configuration.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -811,6 +811,7 @@ provider_spiffe_workload_api_socket_path = "/spiffe-workload-api/spire-agent.soc
811811
# PVC init container. When unset, the driver auto-detects from OpenShift SCC
812812
# namespace annotations (openshift.io/sa.scc.uid-range) if present, falling
813813
# back to 1000 on non-OpenShift clusters. Any non-root Linux UID/GID is valid.
814+
# Helm sets these with server.sandboxUid and server.sandboxGid.
814815
# sandbox_uid = 1500
815816
# sandbox_gid = 1500
816817
# Operator-mode namespace discovery. At least one must be set when

‎docs/how-it-works/sandboxes/runtimes.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,7 @@ Only the OpenShell gateway and the Agent Sandbox controller should be able to ma
233233
| `supervisor_image` | `supervisor.image.*` | Override the supervisor image. |
234234
| `workspace_default_storage_size` | `server.workspaceDefaultStorageSize` | Default workspace PVC size. |
235235
| `workspace_storage_class` | `server.workspaceStorageClass` | `StorageClass` for workspace PVCs. Set this if the cluster has no default `StorageClass`. |
236+
| `sandbox_uid` / `sandbox_gid` | `server.sandboxUid` / `server.sandboxGid` | Sandbox pod UID and GID. Takes priority over OpenShift SCC namespace annotations. `sandbox_gid` defaults to the UID. |
236237
| `https_proxy` | `upstreamProxy.url` | Corporate proxy for sandbox egress. |
237238
| `no_proxy` | `upstreamProxy.noProxy` | Destinations that bypass the corporate proxy. |
238239
| `proxy_auth_secret_name` / `proxy_auth_secret_key` | `upstreamProxy.authSecret.name` / `.key` | Secret holding the proxy `user:pass` credential. |

0 commit comments

Comments
 (0)