mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-29 07:23:25 +08:00
Drew Newberry
9a85667d0d
* feat(sandbox-backend): route runtime connections to shared supervisor sessions A supervisor shared by several sandboxes needs one listener for every session's runtime-initiated Sandbox Protocol connections. The runtime now sends a fixed, bounded routing preface (magic, version, length, and an opaque route handle) before its pinned TLS handshake when its bootstrap names a route. RuntimeRouter treats the handle only as a hint that selects which generation-pinned TLS identity to demand, closes unknown, removed, and replaced handles before any handshake, bounds unauthenticated handshakes globally and per route, and queues an authenticated connection only for its own session, so no peer can displace a live channel. A routed session waits up to the bootstrap grace for its first connection, because it is registered before its workload Pod is scheduled. The session_control module defines the trusted contract between a compute driver and a shared supervisor: registering one generation's runtime descriptor and gateway-issued credentials, reading its status, and removing it, over mutually authenticated TLS 1.3. Dedicated descriptors and bootstrap listeners keep their encodings. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(supervisor): host gateway-registered sessions in one process openshell-supervisor experimental-host replaces the idle bootstrap process with a session host. A mutually authenticated session-control API accepts registrations only from the admission certificate holder, the gateway. Each registration starts a SessionHost session that acts only with the gateway credentials issued for its generation, keeps its proxy CA, trust directory, and SSH socket under a private directory, and receives its runtime connections through the routed listener. Status reports each session's own readiness; the health socket keeps reporting process health only. Removing a session runs on a task the host owns, so it completes when the caller disconnects, concurrent removers share its result, and the route stays reserved until the session has ended and its files are gone. An identical registration is accepted again and a different one for a registered route is refused. Sessions get no upstream proxy, extra CA bundle, or provider workload identity; the Kubernetes driver refuses configurations that need them. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(server): issue a TLS-only private PKI from generate-certs generate-certs --tls-only creates just a server and a client TLS Secret from a fresh CA, with the same create-if-missing contract and a recovery hint for partial state. The Helm certgen hook uses it for private PKIs that must not carry a sandbox-JWT signing key. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(kubernetes): supervise gateway-topology generations as shared sessions With experimental_supervisor_topology = "gateway", each new runtime generation becomes a session on the gateway's shared supervisor instead of a supervisor Pod and boundary Service of its own. The generation records its placement and session route on its Sandbox resource when it starts, and every later decision reads that record, so changing the setting never reinterprets a running generation and unknown records fail closed. The runtime identity ends with the session route, which no Pod UID can equal, so Pod authentication cannot vouch for a shared generation. Create and start add a per-sandbox egress allowance to the Pods the shared supervisor's Service selects, bind it into the boundary evidence, and register the session over session control before releasing the workload; registration does not wait for the runtime, so create still returns before the gateway persists the generation. Readiness follows the session's own status. Stop, restart, and delete remove only that session, and reconciliation suspends a workload whose session is gone and removes sessions that no current generation may run. Configurations with an upstream proxy or provider SPIFFE identity are refused. Closes #4700 Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(helm): deploy and wire the shared supervisor With the gateway topology enabled, the chart runs the session host as a single-replica Deployment with its Service and a NetworkPolicy that admits session control only from the gateway and runtime connections only from sandbox workload Pods. The certgen hook issues a private session-control PKI whose client credential only the gateway mounts, the gateway may read only that Service, and the chart renders the matching experimental_shared_supervisor table. The supervisor Pod has no service account token. Settings the shared supervisor cannot isolate, and a hand-written connection table, fail at render time. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(ocsf): attribute events to session-bound contexts A supervisor process that hosts several sandboxes cannot use one process-wide OCSF context: every event would carry the wrong sandbox identity, and middleware requests read their sandbox identity from the same context. Builders now accept a ContextRef, either a borrowed context or a context shared by a hosted session, so per-session contexts need not be leaked. ctx() returns the context bound to the calling thread when present and falls back to the process-wide context otherwise. OCSF JSON output settings can likewise be bound per thread, and OpenTelemetry can parent a span from an explicit W3C trace context instead of process environment. A dedicated supervisor keeps using the process-wide context. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * test(e2e): run two sandboxes on one shared Kubernetes supervisor The e2e:kubernetes:shared-supervisor lane enables the gateway topology and creates two sandboxes with different policies and provider credentials. It checks that one shared supervisor process hosts both, that each session enforces its own policy and injects its own credential, that stopping one leaves the other working, that the routed listener refuses stale and unknown routes and drops a peer that names a live route without its pinned identity, and that a restart registers a fresh session on the same process. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): scope gateway credentials and network state to a session The supervisor kept its gateway bearer, Sandbox Protocol bearer, and renewal task in process-wide slots, and the network supervisor read provider token grants, proxy CA files, and the gateway identity from process environment. A second sandbox in the same process would have replaced or rotated the first sandbox's credentials, reused its provider access tokens, and exposed its denials through policy.local. GatewayCredentials now holds one session's gateway and Sandbox Protocol credentials and their renewal; every gateway client receives a GatewayEndpoint that pairs the URL with them, including log push, ConnectSupervisor and its redirects, and extension-credential rotation. run_networking takes a NetworkSession with the sandbox identity, the session's gateway access, its Workload API socket, its policy.local denial source, and its proxy CA files. Provider token grants use a cache and HTTP client owned by the session and fail closed without a Workload API socket. run_session supervises one generation from an explicit SessionConfig and owner-provided SessionControls. run_sandbox_with_backend remains the dedicated entry point: it keeps the process-wide OCSF context, reads the same environment, binds readiness endpoints to session readiness, and stops on SIGTERM or SIGINT. The binary shares one set of credentials between log push and supervision, as before. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs: describe the experimental shared supervisor Document the gateway supervisor topology, its chart-owned connection settings and limits, and how to debug and test it. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(supervisor): host concurrent sessions on session-bound runtimes SessionHost runs several supervisor sessions in one process. Each session gets its own Tokio runtime, and every thread that runtime starts, plus the thread driving it, is bound to the session's OCSF context, OCSF JSON settings, log sink, and denial log. Tasks, blocking work, reconnects, and credential renewal spawned by a session therefore keep its identity, while threads outside any session carry none and push no logs. Gateway credentials stay explicit per session. Removing a session stops its workload gracefully, or cancels it at once while it is still starting, then shuts down only its runtime and revokes its gateway credentials. The key stays registered until the session thread has finished, so the same generation cannot gain a second owner while one is stopping. A panicking session reports a failure, clears its readiness, and is revoked the same way. Hosted sessions get a private proxy trust directory and serve policy.local denials from their own log. A focused test runs two sessions concurrently and checks that nested and blocking tasks see their own identity, gateway requests carry their own bearer, log lines reach only their own stream, and removing one leaves the other supervising. Closes #4699 Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix: tighten shared supervisor naming, removal deadlines, and route probes The shared supervisor's resource name appended its suffix before truncating, so a release fullname of 51 or 52 characters produced the gateway Service's own name. A fullname without room for the suffix now keeps a prefix and a hash of the whole fullname. Removing a session waits up to 20 s for its workload to stop and 5 s for the session runtime to shut down, but the driver gave DELETE the same 15 s budget as other session-control calls and reported normal removals as failures. The contract now defines the removal grace and a 45 s removal deadline, and deleting a sandbox no longer waits on a session whose workload is already going away. The shared host runs no supervisor OTLP trace or OCSF exporter. The driver warns at startup when the gateway configures that export, and the docs state the limit. experimental-host keeps its Unix-only imports in its Unix entry point. The e2e route probe fails when the supervisor neither refuses nor challenges a connection, or keeps a challenged connection open after a malformed TLS answer, and it checks that every probe reached the supervisor Pod. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): route shared supervisor crypto through openshell-crypto Main now routes first-party TLS providers and digests through the openshell-crypto facade. Build the session-control TLS configurations and the routed-runtime test server from its configuration provider, install the experimental host's default provider through it, and hash shared session registrations with its SHA-256 instead of a direct sha2 dependency. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(supervisor): report shared supervisor health over TCP experimental-host takes --health-port instead of a Unix health socket, matching experimental-bootstrap. It binds the wildcard health listener after the session-control and runtime listeners and accepts and closes connections while the process runs. The chart probes the named container port health (5502) with native kubelet tcpSocket checks; session control stays on 5501, the Service exposes only runtime and session control, and /run/openshell remains for per-session files. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): probe shared supervisor health on session control The shared supervisor's kubelet tcpSocket probes now connect to the mTLS session-control listener (5501) instead of a separate health listener. Drop the experimental-host --health-port flag, its accept loop, and the chart's 5502 container port. Probes open and close a TCP connection; every session-control request still requires mTLS. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): use shared mode flags for the session host Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): describe the shared host module by its mode Drop the experimental label from the shared host module documentation so it matches the --mode=shared entry point. No behavior changes. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(test): preserve shared supervisor workspace overlays Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): name hosted lifetimes sandbox instances A sandbox instance is one running generation of a stable Sandbox resource. Gateway transport connections and the gateway supervisor sessions they carry can reconnect within one instance, so the hosted object, its configuration, controls, host, and per-instance network, denial, and token-grant state now use the sandbox instance name. Rename session_host to sandbox_instance_host, run_session to run_sandbox_instance, and SessionConfig, SessionControls, SessionHost, and related hosted types to their SandboxInstance equivalents. Gateway supervisor sessions, SSH sessions, and authentication session types keep their names. No wire, configuration, or lifecycle behavior changes. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): launch sandbox instances from one config and prepared bindings Replace SandboxRunConfig and its field-by-field copy into SandboxInstanceConfig with a single launch configuration. Live per-instance state (gateway credentials, OCSF context and JSON settings, log sink, and denial log) is now an explicit SandboxInstanceBindings value that the owner prepares once, instead of placeholders the runner or host overwrote. The dedicated binary loads launch inputs from its arguments and environment and shares one GatewayCredentials with log push; run_sandbox_with_backend keeps the process-wide OCSF context, health endpoints, and signal handling. The instance host binds the same SandboxInstanceBindings to its runtime threads and revokes their credentials when the instance ends. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): use session-control wire types for instance status and trace context Drop the supervisor's duplicate SandboxInstancePhase, SandboxInstanceStatus, and TraceContext families. The sandbox instance host reports SandboxInstanceStatusReport directly, with its key as the route, so the shared host no longer converts or re-keys status, lists, or removal results. SandboxInstanceConfig carries RegistrationTraceContext and the dedicated process reads it through trace_context_from_environment. No wire definitions change. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(supervisor): update Windows host proxy test config Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): assign shared sandbox instances over a supervisor-initiated gRPC stream Replace the private HTTP/JSON session-control API, which the gateway dialed on the shared supervisor, with a supervisor-initiated stream to the gateway. The gateway owns the desired set of sandbox instances; the shared supervisor attaches with a gateway-scoped host certificate, receives complete assignment snapshots with session-scoped revisions, reconciles its instance registry to each one, and reports what it observes. Losing the stream never stops an instance; only a later snapshot that omits it does. - Add the private openshell.supervisor.host.v1 protocol, served on the gateway listener but authorized only for the supervisor host certificate, excluded from SDK generation and reflection, and classified in the schema inventory. - Add SupervisorHostController in openshell-core: uninitialized until the driver derives the desired set once, compare-and-replace full resyncs, capacity bound, session fencing by connection epoch, revision-bounded acks, bounded sends. - Classify TLS peers per connection against the ordinary client CA and the supervisor host CA from one configuration snapshot; a chain matching neither or both is refused, and host connections never become users. - Persist each shared generation's launch material in its supervisor Secret so a restarted gateway rebuilds assignments from Sandbox resources, and withdraw instances on stop, delete, and suspend. - Issue the host identity with `generate-certs --client-only`; the gateway mounts only the CA. Drop the control port, server certificate, and gateway ingress rule from the chart; require gateway TLS for the topology. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): authenticate the shared supervisor stream with a gateway-minted supervisor token Replace the shared supervisor's host CA and client certificate with a supervisor token: a bearer the gateway mints from its existing launch-signing key under a profile of its own (typ openshell-supervisor+jwt, subject openshell-supervisor:<gateway_id>, no sandbox, generation, or epoch claims). The supervisor dials the gateway's Attach stream over ordinary server-authenticated TLS and presents the token; the gateway verifies it with the same key infrastructure, grants only the assignment stream, refuses every other credential on it, and ends a stream when the token that opened it expires. The gateway renews the token at half its lifetime and publishes each renewal into the supervisor host controller; the Kubernetes driver's only part in authentication is delivery, replacing the token in the chart-created <release>-supervisor-token Secret, which the supervisor mounts and re-reads on every connection attempt. The gateway Role may get and patch only that Secret. Remove the host-only TLS realm classification, the supervisor host CA mount and config, certgen --client-only, and the supervisor host PKI; gateway TLS returns to its pre-feature behavior and remains required for the topology. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(helm): remove redundant certgen condition Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(supervisor): extract gateway-owned shared supervision into openshell-supervisor-control Move the shared supervisor control types out of openshell-core and openshell-sandbox-backend into a new openshell-supervisor-control crate: the SupervisorHostController (desired set, revision fencing, host sessions, observations), the SandboxInstanceRegistration launch material and SandboxInstanceStatusReport mapping, and a new SharedSupervision coordinator that owns the control contracts a compute driver previously implemented itself: validated persist-before-assign launches, recovery from durable records with the compare-and-replace baseline captured before the driver lists them, keep-previous-set on any failed or mismatched read, and one interpretation of host observations for readiness and bootstrap. Supervisor token delivery keeps its retry and newer-value policy in the crate; the write itself stays with the driver. The gateway now constructs the coordination: ComputeDriverBuildContext exposes shared_supervision() and the server keeps the controller for the Attach stream and token minting, replacing the driver-created controller that was installed into the gateway. The Kubernetes factory injects it through KubernetesComputeDriver::with_shared_supervision; new() stays the dedicated-topology constructor and refuses a configuration that selects the gateway topology without the gateway's coordination. The Kubernetes driver keeps its platform work: placement annotations, the shared supervisor Service and egress NetworkPolicy, launch Secret create and read (bytes only), its own fence and Pod evidence, and the token Secret patch. The supervisor process consumes the moved registration and status types unchanged. Wire protocol, storage JSON, annotations, and the supervisor token profile are unchanged; the private protobuf stays generated in openshell-core and is re-exported by the new crate. Signed-off-by: Drew Newberry <anewberry@nvidia.com> --------- Signed-off-by: Drew Newberry <anewberry@nvidia.com>
OpenShell Helm Chart
Experimental - the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.
This chart deploys the OpenShell gateway into a Kubernetes cluster. It is published as an OCI artifact to GHCR at oci://ghcr.io/nvidia/openshell/helm-chart.
By default, this chart also creates the namespace-scoped resources needed by
sandboxes. For a shared-gateway deployment, install it with
workspaceResources.enabled=false, then install the
deploy/helm/openshell-workspace chart in every pre-provisioned workspace
namespace. The gateway and workspace releases can then be upgraded and removed
independently. Use Kubernetes operator workspace mode when one gateway serves
multiple pre-provisioned workspace namespaces.
Cluster-scoped vs namespaced objects
Most objects in this chart are namespaced and land in the release namespace. Only two are cluster-scoped:
| Object | Default name |
|---|---|
ClusterRole |
<fullname>-node-reader-<release namespace> |
ClusterRoleBinding |
<fullname>-node-reader-<release namespace> |
By default the release creates both, so an install by a cluster-admin is unchanged. On clusters where cluster-scoped RBAC is owned by a different team, split the install in two.
A cluster-admin applies the cluster-scoped objects once per gateway ServiceAccount, rendered from the same values the release uses:
helm template openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
--namespace openshell -f my-values.yaml \
--set rbac.create=true \
--set rbac.clusterScoped.create=true \
--set agentSandbox.preflight.enabled=false \
--show-only templates/clusterrole.yaml \
--show-only templates/clusterrolebinding.yaml | kubectl apply -f -
A namespace-admin then installs and upgrades the release with cluster-scoped
objects omitted, using ci/values-namespace-admin.yaml
or the equivalent --set:
helm upgrade --install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
--namespace openshell -f my-values.yaml \
--set rbac.clusterScoped.create=false
The gateway ServiceAccount name and namespace do not change, so the
pre-created ClusterRoleBinding keeps matching the release. This works with
serviceAccount.create=false too: the ClusterRoleBinding subject follows
serviceAccount.name, so render the admin step with the same values.
Which flag the installer needs
In the default shared workspace mode the release also creates a namespaced
sandbox Role granting Agent Sandbox (agents.x-k8s.io) permissions.
Kubernetes forbids granting permissions you do not hold, and the built-in
admin ClusterRole does not cover that CRD, so an installer holding only
admin cannot create it. rbac.clusterScoped.create=false alone is then not
enough and the install fails with attempting to grant RBAC permissions not currently held.
| Workspace mode | Installer holds | Use |
|---|---|---|
shared |
built-in admin only |
rbac.create=false, cluster-admin pre-creates all gateway RBAC |
shared |
admin plus the sandbox permissions in the namespace |
rbac.clusterScoped.create=false |
managed, operator |
built-in admin only |
rbac.clusterScoped.create=false |
managed and operator render no namespaced sandbox Role, so no extra grant
is needed there.
With rbac.create=false the cluster-admin applies the namespaced RBAC too,
adding it to the same render:
helm template openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
--namespace openshell -f my-values.yaml \
--set rbac.create=true \
--set rbac.clusterScoped.create=true \
--set agentSandbox.preflight.enabled=false \
--show-only templates/clusterrole.yaml \
--show-only templates/clusterrolebinding.yaml \
--show-only templates/role.yaml \
--show-only templates/rolebinding.yaml \
--show-only templates/peer-role.yaml | kubectl apply -f -
To grant the installer the sandbox permissions instead, bind it to a Role
carrying the same rules as the chart's openshell-sandbox Role.
The certgen hook and credential driver RBAC keep their own flags
(pkiInitJob.enabled and
server.credentialDrivers.kubernetesSecrets.rbac.create).
Migrating an existing release
Helm deletes objects that leave a release manifest, so setting
rbac.clusterScoped.create=false on a release that already owns the
ClusterRole and ClusterRoleBinding deletes them. The gateway then loses
TokenReview until a cluster-admin re-applies them. Hand ownership over first, as
cluster-admin, so nothing is deleted:
kubectl annotate clusterrole "openshell-node-reader-<namespace>" \
helm.sh/resource-policy=keep --overwrite
kubectl annotate clusterrolebinding "openshell-node-reader-<namespace>" \
helm.sh/resource-policy=keep --overwrite
The objects then survive the upgrade that sets the flag, and the cluster-admin owns them from that point on. Fresh installs need no such step.
rbac.clusterScoped.create is independent of
server.drivers.kubernetes.workspaceMode. Managed and operator modes change
what the ClusterRole contains, but they never force the namespaced release to
apply it. Re-run the cluster-admin step after changing values that affect the
ClusterRole rules.
Prerequisites
Required: Your cluster CNI MUST enforce Kubernetes
NetworkPolicyfor ingress and egress in every sandbox namespace. OpenShell creates the policies, but Kubernetes accepts them even if no CNI enforces them. Without enforcement, sandbox workloads may connect directly and bypass supervisor network policy. Verify CNI support before installing OpenShell.
The Kubernetes Agent Sandbox CRDs and controller must be installed on the cluster before deploying OpenShell. Install them with:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/sandbox.yaml
The chart does not install this cluster-scoped dependency. By default, it
fails before creating gateway resources when the cluster serves neither
supported Sandbox API (agents.x-k8s.io/v1beta1 or
agents.x-k8s.io/v1alpha1). Disable the check with
agentSandbox.preflight.enabled=false for offline helm template rendering,
where Helm cannot discover cluster APIs.
Install on Kubernetes
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version>
Install on OpenShift
See the full OpenShift install guide for details. Quick start:
# Precreate the openshell namespace
oc create ns openshell
# Deploy openshell with overrides to allow SCC assignment of fsGroup and runAsUser for the gateway
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> -n openshell \
--set server.disableTls=true \
--set podSecurityContext.fsGroup=null \
--set securityContext.runAsUser=null
On OpenShift 4.22+, end-to-end TLS is supported via BackendTLSPolicy. See the
OpenShift install guide for details.
Available versions
| Tag | Source | Notes |
|---|---|---|
<semver> (e.g. 0.6.0) |
Tagged GitHub release | Tracks the matching gateway, sandbox, and supervisor image versions. Recommended for production. |
<semver>-pre.N (e.g. 0.1.0-pre.3) |
A specific prerelease candidate | Immutable candidate pin that tracks images with the same exact version. |
0.0.0-dev |
Latest commit on main |
Floating tag, overwritten on every push. appVersion is dev, so images resolve to the :dev tag. |
0.0.0-dev.<commit-sha> |
A specific commit on main |
Per-commit pin. Chart version and appVersion both use the full 40-character commit SHA, which matches the image tag pushed by CI. |
Prerelease and dev tags are intended for testing changes ahead of a release. Production deployments should pin to a stable tagged release.
Configuration
See values.yaml for source defaults. Selected overlays:
ci/values-gateway.yaml- gateway-only configurationci/values-cert-manager.yaml- cert-manager integrationci/values-keycloak.yaml- Keycloak OIDC integrationci/values-high-availability.yaml- CI overlay for multi-replica external PostgreSQL testingci/values-autoscaling.yaml- CI overlay for rendering the optional gateway HorizontalPodAutoscalerci/values-spire.yaml- SPIFFE/SPIRE provider token grantsci/values-spire-stack.yaml- SPIRE hardened chart values for local development
Database backend
By default, OpenShell uses SQLite and runs the gateway as a StatefulSet so the database is backed by a per-pod PVC:
server:
dbUrl: "sqlite:/var/openshell/openshell.db"
Data PVC storage
Size the gateway data claim, openshell-data, and select its StorageClass with
server.dataStorageSize and server.dataStorageClass. Omitting both
requests 1Gi from the cluster's default StorageClass. Set
server.dataStorageClass on clusters with no default StorageClass,
otherwise the gateway PVC stays Pending. Both values are ignored under
workload.kind=deployment, which mounts no PVC.
server:
dataStorageSize: 20Gi
dataStorageClass: fast-ssd
volumeClaimTemplates is immutable, so set both at install time. To grow an
existing claim, expand it in place when its StorageClass allows expansion, then
recreate the StatefulSet so its template matches:
kubectl -n openshell patch pvc openshell-data-openshell-0 \
-p '{"spec":{"resources":{"requests":{"storage":"20Gi"}}}}'
kubectl -n openshell delete statefulset openshell --cascade=orphan
helm upgrade openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <installed-version> \
--reuse-values -n openshell --set server.dataStorageSize=20Gi
A recreated StatefulSet re-adopts existing claims unchanged, so changing StorageClass means copying the data to a new claim.
External PostgreSQL
Use external PostgreSQL when the gateway should connect to a database managed outside this chart. The OpenShell chart does not deploy a database; install PostgreSQL separately using the chart, operator, or managed service that fits your environment, then pass the connection URI through a Secret.
Create a Secret containing the PostgreSQL connection URI if one does not already exist:
kubectl create secret generic my-pg-credentials -n openshell \
--from-literal=uri="postgresql://user:pass@host:5432/dbname"
Then install the chart pointing at that Secret:
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
-n openshell \
--set workload.kind=deployment \
--set server.externalDbSecret=my-pg-credentials
Use workload.kind=deployment for external database-backed multi-replica
gateways. workload.kind=statefulset is still available for single-replica
SQLite installs and for operators who explicitly need StatefulSet identity or
storage semantics.
Credential storage
By default, the chart uses the gateway's encrypted database credential storage. The gateway writes encrypted provider credential envelopes to the OpenShell database. The chart creates a retained Kubernetes Secret with the shared key-encryption key and injects that key into every gateway pod, so the same default works for single-replica and external database-backed HA deployments.
Use gatewayConfig to select kubernetes-secrets or vault when credentials
should live in a cluster or external secret backend. Selecting an external
credential driver disables the default credential-storage key-encryption-key
Secret and environment injection. The map is rendered directly as gateway TOML,
so it uses the gateway's snake_case field names:
gatewayConfig:
openshell.gateway:
credential_drivers:
- vault
openshell.credential_drivers.vault:
address: https://vault.vault.svc.cluster.local:8200
mount: secret
kv_version: "2"
auth_method: kubernetes
role: openshell-gateway
gatewayConfigmust contain only non-secret values. Helm serializes unknown fields generically and cannot determine whether an arbitrary string, such asapi_token, is confidential. Do not put passwords, tokens, private keys, database URLs, or other secret material in this map. Use Secret-backed environment variables, files, volumes, or gateway credential drivers instead. The chart rejects known unsafe forms such asdatabase_url, inline URL credentials, and PEM private keys; it is not a general secret scanner.
For the Kubernetes Secret driver, use
openshell.credential_drivers.kubernetes-secrets.namespace in the same map.
The chart derives any required RBAC from the selected driver; use a dedicated
namespace to limit access to OpenShell-managed Secrets.
OpenShift
Append these flags to any of the PostgreSQL commands above for OpenShift:
--set server.disableTls=true \
--set podSecurityContext.fsGroup=null \
--set securityContext.runAsUser=null
High availability
Set replicaCount above 1 only with server.externalDbSecret; the default
SQLite database is per pod and cannot coordinate multiple gateway replicas.
The chart creates a headless peer Service for gateway-to-gateway relay traffic.
StatefulSet pods use stable pod DNS names through that headless Service.
Deployment pods advertise their pod IP with OPENSHELL_PEER_ENDPOINT, because
Kubernetes does not assign stable per-pod DNS names to Deployment replicas.
Gateway peer traffic uses Kubernetes ServiceAccount identity. Each gateway pod
mounts a projected, pod-bound ServiceAccount token with audience
openshell-gateway-peer; receiving replicas validate that token with the
Kubernetes TokenReview API, verify the live pod UID and Helm selector labels,
and authorize only the internal PeerRelay RPC. The chart does not create or
accept a shared gateway peer Secret.
With gateway TLS enabled, peer calls use the chart CA and client TLS Secret for
server verification and mTLS. The client verifies the stable gateway Service
DNS name while connecting directly to the owning pod. Custom TLS Secrets must
include that Service DNS name in the server certificate and provide the CA and
client credentials configured by server.tls.
Set autoscaling.enabled=true to render an autoscaling/v2
HorizontalPodAutoscaler for the gateway workload. The Deployment or
StatefulSet then omits spec.replicas, and the chart applies its
multi-replica checks to autoscaling.maxReplicas. CPU and memory targets
need a matching resources.requests entry, or a resources.limits entry,
which Kubernetes copies into the request. Add custom metrics from a metrics
adapter with autoscaling.metrics. See the
High Availability guide
for the metrics to scale and alert on.
Enabling autoscaling on an existing release removes spec.replicas from the
workload in that upgrade. Kubernetes can reset the workload to one replica
until the HPA scales it back to at least autoscaling.minReplicas, which
disconnects supervisor sessions from the other gateway pods; they reconnect to the remaining replica. Enable autoscaling
when you install the chart, or during a maintenance window. On an existing
release, upgrade with --reset-then-reuse-values, which needs Helm 3.14 or
later. With an older Helm, save the values with
helm get values <release> -o yaml > values.yaml and upgrade with
--reset-values -f values.yaml. --reuse-values keeps the
previous chart version's defaults, which lack the autoscaling values,
including the scale-down behavior, when that release predates them. For background, refer to
Migrating Deployments and StatefulSets to horizontal autoscaling.
Disabling autoscaling renders spec.replicas from replicaCount again,
which defaults to 1, so set replicaCount to the replica count you want in
that upgrade.
Secret bootstrap
By default, a pre-install/pre-upgrade hook Job runs openshell-gateway generate-certs
to create the gateway's server/client mTLS Secrets and sandbox JWT signing Secret.
The Job uses the gateway image itself, so air-gapped environments only need to
mirror that one image (no separate openssl/alpine sidecar).
When certManager.enabled=true, cert-manager owns the TLS Secrets and the chart
runs the same hook in JWT-only mode because cert-manager does not create the
sandbox JWT signing Secret. This precedence applies even if
pkiInitJob.enabled remains true. Set pkiInitJob.enabled=false only when an
external non-cert-manager TLS source manages TLS and you pre-create the sandbox
JWT signing Secret.
SPIFFE/SPIRE provider token grants
Set gatewayConfig.openshell.drivers.kubernetes.provider_spiffe_workload_api_socket_path
to let sandbox supervisors use SPIFFE JWT-SVIDs for dynamic provider token
grants. The chart keeps supervisor-to-gateway authentication on gateway-minted
sandbox JWTs and passes the configured socket path to the Kubernetes driver.
gatewayConfig:
openshell.drivers.kubernetes:
provider_spiffe_workload_api_socket_path: /spiffe-workload-api/spire-agent.sock
For local development, uncomment the SPIRE Helm releases in skaffold.yaml and
add ci/values-spire.yaml to the OpenShell release values files.
The gateway verifies supervisor JWT-SVIDs with JWT bundles fetched from the SPIFFE Workload API, so this path does not require access to the SPIRE OIDC discovery endpoint or its TLS CA.
Values
| Key | Type | Default | Description |
|---|---|---|---|
| affinity | object | {} |
Affinity rules for the gateway pod. |
| agentSandbox.preflight.enabled | bool | true |
Check the live cluster for a supported Agent Sandbox API before rendering gateway resources. Disable only for offline rendering and linting. |
| autoscaling.behavior | object | {"scaleDown":{"policies":[{"periodSeconds":120,"type":"Pods","value":1}],"stabilizationWindowSeconds":300}} |
HPA scaling behavior. Scale-down hands the removed pod's supervisor sessions to the remaining replicas, so the default removes at most one replica every two minutes after a five-minute stabilization window. Helm merges maps: set autoscaling.behavior.scaleDown to null to drop the default. |
| autoscaling.enabled | bool | false |
Render a HorizontalPodAutoscaler and stop rendering spec.replicas. |
| autoscaling.maxReplicas | int | 4 |
Maximum gateway replicas. Each replica opens up to database_max_connections + database_lock_max_connections PostgreSQL connections (14 with the defaults; set them under gatewayConfig.openshell.gateway); size the database for rollouts at this count, as the High Availability guide describes. With a Deployment and the default pool sizes, the default of 4 needs max_connections of at least 126, more than the PostgreSQL default of 100. |
| autoscaling.metrics | list | [] |
Additional autoscaling/v2 MetricSpec entries appended verbatim, such as Pods metrics served by prometheus-adapter. |
| autoscaling.minReplicas | int | 2 |
Minimum gateway replicas. Use 2 or more to survive a pod failure. |
| autoscaling.targetCPUUtilizationPercentage | int | 80 |
Target average CPU utilization, as a percentage of resources.requests.cpu. Set to null to disable. Requires resources.requests.cpu, or resources.limits.cpu, which Kubernetes copies into the request. |
| autoscaling.targetMemoryUtilizationPercentage | int | nil |
Target average memory utilization, as a percentage of resources.requests.memory. Null disables it. Requires resources.requests.memory, or resources.limits.memory, which Kubernetes copies into the request. |
| certManager.caSecretName | string | "openshell-ca-tls" |
Secret created for the intermediate CA (Certificate with isCA: true). |
| certManager.certificateDuration | string | "8760h" |
Duration for cert-manager-issued certificates. |
| certManager.certificateRenewBefore | string | "720h" |
Renewal window for cert-manager-issued certificates. |
| certManager.clientCaFromServerTlsSecret | bool | true |
Mount gateway client CA from the internal server TLS secret's ca.crt. The internal server certificate is always signed by the chart CA — the same CA that signs the client (mTLS) certificate — so the default (true) is correct for all configurations, including when serverIssuerRef is set. Only set to false if you mount the client CA from a separate secret via server.tls.clientCaSecretName. |
| certManager.enabled | bool | false |
Create cert-manager Issuer and Certificate resources. When enabled, cert-manager owns TLS and the chart runs a JWT-only certgen hook to create the sandbox JWT signing Secret that cert-manager does not manage. |
| certManager.serverDnsNames | list | ["openshell","openshell.openshell.svc","openshell.openshell.svc.cluster.local","localhost","openshell.localhost","*.openshell.localhost","host.docker.internal"] |
DNS SANs on the cert-manager-issued server certificate. |
| certManager.serverIpAddresses | list | ["127.0.0.1"] |
IP SANs on the cert-manager-issued server certificate. |
| certManager.serverIssuerRef | object | {"group":"","kind":"","name":""} |
Override the issuerRef for the external server Certificate (e.g. a real LetsEncrypt/ACME ClusterIssuer for a publicly-trusted cert on an external hostname). When set, the chart creates a second server certificate from this issuer with only the hostnames in serverDnsNames; the internal server certificate is always signed by the chart's own CA. Leave name empty to use the chart CA for all server certificates (default). Requires certManager.enabled=true. |
| credentialDrivers.vault.caConfigMapName | string | "" |
ConfigMap containing the private Vault/OpenBao CA certificate under the ca.crt key. Helm mounts it only when the Vault driver is selected. |
| fullnameOverride | string | "" |
Override the full generated resource name. |
| gateway.image.digest | string | "" |
Gateway image digest. When set, this takes precedence over tag. |
| gateway.image.pullPolicy | string | nil |
Gateway image pull policy. Empty uses global.image.pullPolicy. |
| gateway.image.registry | string | "" |
Gateway image registry. Empty uses global.image.registry. |
| gateway.image.repository | string | "openshell/gateway" |
Gateway image repository. |
| gateway.image.tag | string | "" |
Gateway image tag. Defaults to the chart appVersion when empty. |
| gatewayConfig | object | {"openshell":{"version":2}} |
Non-secret gateway application configuration. Top-level keys name TOML tables and are rendered into the mounted gateway.toml file. Kubernetes resource inputs remain outside this map; template expressions derive the corresponding runtime values from their resource owner. |
| global.image.pullPolicy | string | "IfNotPresent" |
Shared OpenShell image pull policy. Individual image pull policies take precedence. |
| global.image.registry | string | "ghcr.io/nvidia" |
Shared OpenShell image registry. Individual image registries take precedence. |
| global.image.tag | string | "" |
Shared OpenShell image tag. Defaults to the chart appVersion when empty. |
| grpcRoute.backendTLSPolicy.caCertificateConfigMapName | string | "" |
Name of the ConfigMap containing the CA certificate (key: ca.crt) used to validate the gateway pod's TLS certificate. Defaults to <fullname>-backend-ca when empty. The certgen hook auto-creates this: with pkiInitJob (default), immediately on install/upgrade; with cert-manager, the hook polls for pkiInitJob.timeoutSeconds seconds waiting for cert-manager to issue the server certificate, then creates the ConfigMap. A single install usually succeeds; if cert-manager takes longer, increase pkiInitJob.timeoutSeconds. By default (pkiInitJob.failOnTimeout=true), the install fails if the timeout is reached; set failOnTimeout=false to allow the install to succeed and run helm upgrade after the certificate is issued. |
| grpcRoute.backendTLSPolicy.enabled | bool | false |
Create a BackendTLSPolicy resource for end-to-end TLS between the Gateway proxy and the OpenShell gateway pod. The traffic flow is: client → HTTPS → Gateway (terminate) → TLS (re-encrypt) → gateway pod. Requires server.disableTls=false and server.tls.enableMtls=false. The certgen hook auto-creates the backend CA ConfigMap. |
| grpcRoute.backendTLSPolicy.hostname | string | "" |
Hostname the Gateway proxy validates against the backend's TLS certificate SAN. Defaults to the service FQDN (<fullname>.<namespace>.svc.cluster.local) when empty, which matches the SAN included by both cert-manager and the pkiInitJob. |
| grpcRoute.enabled | bool | false |
Create a Gateway API GRPCRoute for the gateway service. |
| grpcRoute.gateway.className | string | "eg" |
GatewayClass for a chart-created Gateway. Set this to the name exposed by your Gateway API implementation. Envoy Gateway uses "eg" in the OpenShell examples. Ignored when gateway.create is false. |
| grpcRoute.gateway.create | bool | false |
When true, a Gateway resource is created in the release namespace. Set to false and provide name/namespace to attach to a pre-existing Gateway. Use sectionName to select a specific listener when needed. |
| grpcRoute.gateway.listener.allowedRoutes | string | "Same" |
"Same" restricts attached routes to the release namespace; "All" allows any namespace. |
| grpcRoute.gateway.listener.port | int | 80 |
Listener port for the generated Gateway resource. Use 443 with protocol HTTPS. |
| grpcRoute.gateway.listener.protocol | string | "HTTP" |
Listener protocol for the generated Gateway resource: HTTP or HTTPS. HTTPS terminates TLS at the Gateway listener; pair it with server.disableTls=true so the proxy forwards plaintext to the gateway pod, and use OIDC for client identity (the gateway never sees the client certificate). |
| grpcRoute.gateway.listener.tls.certificateRefs | list | [] |
certificateRefs for the HTTPS listener. Required when protocol is HTTPS. Each entry needs a name pointing at a kubernetes.io/tls Secret in the Gateway's namespace. May reference a cert-manager-issued Secret or the existing openshell-server-tls Secret (its SANs must include the external hostname). |
| grpcRoute.gateway.name | string | "" |
Name of the Gateway resource. Defaults to <fullname>. Set a distinct name when the selected controller creates a proxy Service with the Gateway name. When gateway.create is false, set this to the name of the existing Gateway. |
| grpcRoute.gateway.namespace | string | "" |
Namespace of the Gateway referenced by the GRPCRoute parentRef. Defaults to the release namespace. A chart-created Gateway always resides in the release namespace. |
| grpcRoute.gateway.sectionName | string | "" |
Listener name on an existing Gateway. Leave empty to let Gateway API listener matching select compatible listeners. |
| grpcRoute.hostnames | list | [] |
Hostnames the GRPCRoute matches on. Leave empty to match all hosts. |
| grpcRoute.replicaRouting.enabled | bool | false |
Route requests carrying an x-openshell-replica header straight to that gateway replica. The CLI sets the header on long-lived sandbox connections (SSH, port forwards, exec) using the owner the gateway reports, so they skip the relay through a peer replica. Renders one Service per replica. Requires workload.kind=statefulset, workload.allowMultiReplicaStatefulSet=true, and at most 15 replicas. |
| imagePullSecrets | list | [] |
Image pull secrets attached to gateway and helper pods. |
| nameOverride | string | "openshell" |
Override the chart name used in generated resource names. |
| networkPolicy.enabled | bool | true |
Restrict SSH ingress on sandbox pods to the gateway. In managed mode, the driver applies the equivalent policy to each workspace namespace. |
| nodeSelector | object | {} |
Node selector for the gateway pod. |
| openshiftRoute.annotations | object | {} |
Extra annotations on the Route (e.g. haproxy.router.openshift.io/*). |
| openshiftRoute.enabled | bool | false |
Create an OpenShift Route with TLS passthrough. |
| openshiftRoute.host | string | "" |
Hostname for the Route. Must match a SAN on the gateway's server cert. |
| pkiInitJob.enabled | bool | true |
Run a pre-install/pre-upgrade Job that creates gateway and client mTLS Secrets. When certManager.enabled=true, cert-manager owns TLS and this same hook runs in JWT-only mode even if pkiInitJob.enabled remains true. |
| pkiInitJob.failOnTimeout | bool | true |
Fail the helm install/upgrade if cert-manager does not issue the certificate within the polling timeout. When true (default), the install fails immediately if the timeout is reached, providing clear feedback that BackendTLSPolicy is non-functional. When false, the hook succeeds with a warning and you can run helm upgrade after cert-manager issues the certificate to create the backend CA ConfigMap. If you set this to false and see "TLS error: Secret is not supplied by SDS" when connecting to the gateway, check if the TLS secret exists and run helm upgrade to create the ConfigMap. |
| pkiInitJob.securityContext.allowPrivilegeEscalation | bool | false |
Whether the certgen hook container can gain additional privileges. |
| pkiInitJob.securityContext.capabilities.drop | list | ["ALL"] |
Linux capabilities dropped from the certgen hook container. |
| pkiInitJob.securityContext.runAsNonRoot | bool | true |
Require the certgen hook container to run as a non-root user. |
| pkiInitJob.securityContext.seccompProfile.type | string | "RuntimeDefault" |
Seccomp profile applied to the certgen hook container. |
| pkiInitJob.serverDnsNames | list | [] |
Extra DNS SANs to append to the server certificate. |
| pkiInitJob.serverIpAddresses | list | [] |
Extra IP SANs to append to the server certificate. |
| pkiInitJob.timeoutSeconds | int | 120 |
Maximum time in seconds for the certgen hook to poll for cert-manager certificates. When using cert-manager with BackendTLSPolicy, the hook polls for this many seconds waiting for the certificate to be issued, then creates the backend CA ConfigMap. The Job deadline is set to (timeoutSeconds + 30) to allow time for ConfigMap creation and cleanup. Increase this if cert-manager takes longer than 120 seconds to issue certificates. |
| podAnnotations | object | {} |
Extra annotations to add to the gateway pod. |
| podLabels | object | {} |
Extra labels to add to the gateway pod. |
| podLifecycle.terminationGracePeriodSeconds | int | 30 |
Maximum time, in seconds, Kubernetes waits for the gateway to exit before killing it. The gateway exits as soon as shutdown completes; the limit covers supervisor session cleanup and draining queued OCSF records. |
| podSecurityContext.fsGroup | int | 1000 |
fsGroup assigned to the gateway pod. |
| probes.liveness.failureThreshold | int | 3 |
Liveness probe failure threshold before the container is restarted. |
| probes.liveness.initialDelaySeconds | int | 2 |
Liveness probe initial delay, in seconds. |
| probes.liveness.periodSeconds | int | 5 |
Liveness probe period, in seconds. |
| probes.liveness.timeoutSeconds | int | 1 |
Liveness probe timeout, in seconds. |
| probes.readiness.failureThreshold | int | 3 |
Readiness probe failure threshold before the pod is marked not ready. |
| probes.readiness.initialDelaySeconds | int | 1 |
Readiness probe initial delay, in seconds. |
| probes.readiness.periodSeconds | int | 2 |
Readiness probe period, in seconds. |
| probes.readiness.timeoutSeconds | int | 1 |
Readiness probe timeout, in seconds. |
| probes.startup.failureThreshold | int | 30 |
Startup probe failure threshold before the container is killed. |
| probes.startup.periodSeconds | int | 2 |
Startup probe period, in seconds. |
| probes.startup.timeoutSeconds | int | 1 |
Startup probe timeout, in seconds. |
| rbac.clusterScoped.clusterRoleBindingName | string | "" |
Name for the ClusterRoleBinding. Empty uses the <fullname>-node-reader-<release namespace> default. |
| rbac.clusterScoped.clusterRoleName | string | "" |
Name for the ClusterRole. Empty uses the <fullname>-node-reader-<release namespace> default. |
| rbac.clusterScoped.create | bool | true |
Create the cluster-scoped ClusterRole and ClusterRoleBinding. Disable for a namespace-admin install where a cluster-admin applies them separately; the gateway ServiceAccount name and namespace are unchanged, so a pre-created ClusterRoleBinding still matches. |
| rbac.create | bool | true |
Create the RBAC objects that grant the gateway ServiceAccount access. Disable to supply the namespaced sandbox and peer Role/RoleBinding and the cluster-scoped ClusterRole/ClusterRoleBinding out of band. The certgen hook and credential driver RBAC keep their own flags. |
| replicaCount | int | 1 |
Number of OpenShell gateway replicas. Values greater than 1 require server.externalDbSecret because the default SQLite backend is per pod. |
| resources | object | {} |
Gateway pod resource requests and limits. |
| sandbox.image.digest | string | "" |
Sandbox image digest. When set, this takes precedence over tag. |
| sandbox.image.pullPolicy | string | nil |
Sandbox image pull policy. Leave unset to use the Kubernetes image default. |
| sandbox.image.repository | string | "nvcr.io/nvidia/base/ubuntu" |
Default standalone sandbox image repository. |
| sandbox.image.tag | string | "24.04" |
Sandbox image tag. Defaults to latest when empty. |
| sandboxRuntime.image.digest | string | "" |
Sandbox runtime image digest. When set, this takes precedence over tag. |
| sandboxRuntime.image.pullPolicy | string | nil |
Sandbox runtime image pull policy. Empty uses global.image.pullPolicy. |
| sandboxRuntime.image.registry | string | "" |
Sandbox runtime image registry. Empty uses global.image.registry. |
| sandboxRuntime.image.repository | string | "openshell/sandbox" |
Sandbox runtime image repository. |
| sandboxRuntime.image.tag | string | "" |
Sandbox runtime image tag. Defaults to the chart appVersion when empty. |
| sandboxServiceAccount.annotations | object | {} |
Annotations to add to the generated sandbox service account. |
| sandboxServiceAccount.create | bool | true |
Create a service account for sandbox pods. |
| sandboxServiceAccount.name | string | "" |
Existing service account name for sandbox pods when sandboxServiceAccount.create is false. |
| securityContext.allowPrivilegeEscalation | bool | false |
Whether the gateway container can gain additional privileges. |
| securityContext.capabilities.drop | list | ["ALL"] |
Linux capabilities dropped from the gateway container. |
| securityContext.runAsNonRoot | bool | true |
Require the gateway container to run as a non-root user. |
| securityContext.runAsUser | int | 1000 |
UID assigned to the gateway container. |
| securityContext.seccompProfile.type | string | "RuntimeDefault" |
Seccomp profile applied to the gateway container. |
| server.auth.allowUnauthenticatedUsers | bool | false |
UNSAFE: accept unauthenticated CLI/user requests as a local developer principal. Intended only for trusted local Skaffold/k3d development or a fully trusted fronting proxy. Leave false for shared or production clusters. |
| server.credentialDrivers.kubernetesSecrets.createNamespace | bool | false |
Create the credential namespace. Requires a namespace other than the release namespace. The Namespace is retained on uninstall so stored credentials survive; an existing Namespace not owned by this release is left untouched. |
| server.credentialDrivers.kubernetesSecrets.enabled | bool | false |
Enable the in-tree Kubernetes Secret credential driver. WARNING: The RBAC Role grants read/write access to ALL Secrets in the configured namespace. Use a dedicated namespace to limit blast radius. |
| server.credentialDrivers.kubernetesSecrets.namespace | string | "" |
Namespace where OpenShell-managed provider Secret objects are stored. Empty = Helm release namespace. A dedicated namespace is RECOMMENDED to isolate OpenShell-managed Secrets from other workloads. |
| server.credentialDrivers.kubernetesSecrets.rbac.create | bool | true |
Create a Role/RoleBinding granting the gateway ServiceAccount read/write access to managed provider Secrets. |
| server.credentialDrivers.vault.address | string | "" |
Vault service base URL. Non-loopback endpoints must use HTTPS, for example https://vault.vault.svc.cluster.local:8200. |
| server.credentialDrivers.vault.authMethod | string | "kubernetes" |
Authentication method. Use "kubernetes" in-cluster or "token_file" for local/dev validation. |
| server.credentialDrivers.vault.caConfigMapName | string | "" |
ConfigMap containing the private Vault CA certificate bundle in the ca.crt key. Leave empty to use platform trust roots. |
| server.credentialDrivers.vault.enabled | bool | false |
Enable the in-tree Vault credential driver. |
| server.credentialDrivers.vault.kubernetesAuthMount | string | "kubernetes" |
Vault Kubernetes auth mount. |
| server.credentialDrivers.vault.kvVersion | string | "2" |
Default KV engine version. Use "1" or "2". |
| server.credentialDrivers.vault.mount | string | "secret" |
Default KV mount name. |
| server.credentialDrivers.vault.role | string | "" |
Vault Kubernetes auth role when authMethod is kubernetes. |
| server.credentialDrivers.vault.serviceAccountTokenPath | string | "/var/run/secrets/kubernetes.io/serviceaccount/token" |
ServiceAccount token path used for Kubernetes auth. |
| server.credentialDrivers.vault.timeoutSecs | string | "" |
HTTP request timeout in seconds. Empty = driver default. |
| server.credentialDrivers.vault.tokenPath | string | "" |
Mounted token file path when authMethod is token_file. |
| server.credentialStorage.existingSecret | string | "" |
Name of a pre-existing Secret containing the key-encryption key. When set, the chart does NOT generate a new Secret; it references this one instead. The Secret must contain a key named "key-encryption-key" with a base64-encoded 32-byte value. Required for GitOps workflows that render manifests with helm template (where lookup is unavailable). |
| server.dataStorageClass | string | "" |
Kubernetes StorageClass for the gateway data PVC (StatefulSet workload only). Empty (default) = omit storageClassName, using the cluster's default StorageClass. Set this on clusters with no default StorageClass, otherwise the gateway PVC stays Pending. Use a block-backed class, not NFS or other network filesystems. Immutable after install. |
| server.dataStorageSize | string | "" |
Storage request for the gateway data PVC, openshell-data (StatefulSet workload only). Uses Kubernetes quantity syntax and requires an explicit unit ("20Gi", not "20"). Empty = built-in default (1Gi). Growing an existing release's claim is PVC expansion, not a values change. |
| server.dbUrl | string | "sqlite:/var/openshell/openshell.db" |
Gateway database URL (used for the default SQLite backend). SQLite runs in WAL mode and needs a local block-backed volume, not NFS or other network filesystems. |
| server.defaultRuntimeClassName | string | "" |
Default Kubernetes runtimeClassName for sandbox pods. Applied when a CreateSandbox request does not specify one. Empty (default) = omit the field, using the cluster's default RuntimeClass. Set to a RuntimeClass name (e.g. "kata-containers", "nvidia") to apply it to all sandboxes that don't explicitly override it. |
| server.disableTls | bool | false |
Disable TLS entirely - the server listens on plaintext HTTP. Set to true when a reverse proxy / tunnel terminates TLS at the edge. |
| server.drivers.kubernetes.allowDriverConfig | bool | false |
Allow caller driver JSON; external resources still require approval. |
| server.drivers.kubernetes.operatorNamespaceFile | string | "" |
Path to a JSON file containing an array of namespace names allowed in operator mode. Hot-reloaded on change. |
| server.drivers.kubernetes.operatorNamespaceLabel | string | "" |
K8s label selector for namespace discovery in operator mode. The driver watches namespaces matching this label. |
| server.drivers.kubernetes.resourceAdmission.enabled | bool | true |
Require operator approval labels on external sandbox attachments (GPU attachments exempt). |
| server.drivers.kubernetes.resourceAdmission.requiredLabels | string | nil |
Replacement label map; null uses the built-in admission labels. Empty map is invalid when enabled. |
| server.drivers.kubernetes.workspaceMode | string | "shared" |
How workspaces map to Kubernetes namespaces. "shared" (default): all sandboxes in a single namespace. "managed": auto-creates per-workspace namespaces. "operator": uses pre-provisioned namespaces. |
| server.enableLoopbackServiceHttp | bool | true |
Enable plaintext HTTP routing for loopback sandbox service URLs on TLS-enabled gateways. |
| server.enableUserNamespaces | bool | false |
Enable Kubernetes user namespace isolation (hostUsers: false) for sandbox pods. Requires Kubernetes 1.33+ with user namespace support available (beta through 1.35, GA in 1.36+), plus a supporting container runtime and Linux 5.12+. When enabled, container UID 0 maps to an unprivileged host UID and capabilities become namespaced. |
| server.enableWebsocketTunnel | bool | false |
Enable the WebSocket tunnel used by CLI/SDK clients behind an authenticated edge proxy. Leave disabled for direct gateway installs. |
| server.externalDbSecret | string | "" |
Name of a pre-existing Opaque Secret containing a PostgreSQL connection URI (key: uri). When set, the gateway reads OPENSHELL_DB_URL from this Secret instead of using dbUrl. The Secret must contain a uri key, e.g. postgresql://user:pass@host:5432/dbname. |
| server.extraVolumeMounts | list | [] |
Additional volume mounts for the gateway container. |
| server.extraVolumes | list | [] |
Additional volumes for the gateway pod. |
| server.grpcEndpoint | string | "" |
gRPC endpoint sandboxes call back into the gateway. Leave empty to derive it from the chart fullname, release namespace, service port, and disableTls flag, for example https://openshell.openshell.svc.cluster.local:8080. Override only when sandboxes must reach the gateway via a different hostname (e.g. an external ingress or a host alias). |
| server.grpcRateLimit.requests | int | 0 |
Maximum gRPC requests allowed per window. Must be positive (alongside windowSeconds) to enable rate limiting; 0 (default) disables it. |
| server.grpcRateLimit.windowSeconds | int | 0 |
gRPC rate-limit window length in seconds. Must be positive (alongside requests) to enable rate limiting; 0 (default) disables it. |
| server.hostGatewayIP | string | "" |
Host gateway IP for sandbox pod hostAliases. When set, sandbox pods get hostAliases entries mapping host.docker.internal and host.openshell.internal to this IP, allowing them to reach services running on the Docker host. Auto-detected by the cluster entrypoint script. |
| server.logLevel | string | "info" |
Gateway log level. |
| server.name | string | "" |
Operator-facing gateway name. Defaults to the chart fullname so all replicas in one installation share an identity. Set explicitly when one telemetry collector receives spans from multiple namespaces or clusters. |
| server.ocsfLog.enabled | bool | false |
Write gateway OCSF events as JSONL. |
| server.ocsfLog.maxFiles | int | 7 |
Rotated files retained when rotation is daily. |
| server.ocsfLog.path | string | "/tmp/gateway-ocsf.jsonl" |
OCSF JSONL path. The default is writable in the gateway container but does not persist across restarts. To keep records, mount a volume with server.extraVolumes and server.extraVolumeMounts and set a path on it. When replicas share the volume, set subPathExpr: $(OPENSHELL_POD_NAME) on the mount so each replica writes its own file. |
| server.ocsfLog.queueCapacity | int | 10000 |
Maximum records waiting for the file writer. |
| server.ocsfLog.queueMaxBytes | int | 16777216 |
Maximum encoded bytes waiting for the file writer. |
| server.ocsfLog.rotation | string | "daily" |
Rotate the active file daily in UTC, or never. |
| server.ocsfLog.schemaVersion | string | "" |
Optional OCSF downgrade target. Empty emits native OCSF 1.8.0. Supported values: "1.1", "1.3". |
| server.oidc.adminRole | string | "" |
Role name for admin access. Leave empty (with userRole also empty) for authentication-only mode. Both must be set or both empty. |
| server.oidc.audience | string | "openshell-cli" |
Expected audience claim for the API resource server. This should match the server's --oidc-audience, NOT the CLI client ID. |
| server.oidc.caConfigMapName | string | "" |
Name of a ConfigMap containing a CA certificate bundle (key: ca.crt) for verifying the OIDC issuer's TLS certificate. Required when the issuer uses a non-public CA (e.g. OpenShift ingress, private PKI). |
| server.oidc.dangerouslyAllowInsecureHttp | bool | false |
Development only: permit cleartext OIDC requests to numeric loopback addresses. This never permits HTTP to hostnames or non-loopback addresses. |
| server.oidc.issuer | string | "" |
OIDC issuer URL (e.g. https://keycloak.example.com/realms/openshell). |
| server.oidc.jwksAllowedOrigins | list | [] |
Additional trusted HTTPS origins allowed to serve JWKS. The issuer origin is always allowed. Entries must not include a path or query. |
| server.oidc.jwksTtl | int | 3600 |
JWKS key cache TTL in seconds. Must be greater than zero. |
| server.oidc.rolesClaim | string | "" |
Dot-separated path to the roles array in the JWT claims. Keycloak: "realm_access.roles", Entra ID: "roles", Okta: "groups". |
| server.oidc.scopesClaim | string | "" |
Dot-separated path to the scopes array in the JWT claims. |
| server.oidc.userRole | string | "" |
Role name for standard user access. |
| server.otlp.endpoint | string | "" |
OTLP/gRPC collector endpoint, conventionally using port 4317. |
| server.otlp.serviceName | string | "" |
Gateway OpenTelemetry service name. Empty uses openshell-gateway. |
| 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. |
| server.providerTokenGrants.spiffe.enabled | bool | false |
Mount the SPIFFE Workload API socket into gateway and sandbox pods for dynamic provider token grants. |
| server.providerTokenGrants.spiffe.workloadApiSocketPath | string | "/spiffe-workload-api/spire-agent.sock" |
Path to the SPIFFE Workload API socket mounted into gateway and sandbox pods. |
| server.sandboxGid | string | "" |
GID for sandbox pods (sandbox_gid). Empty (default) = same as sandboxUid. Must be an integer between 1 and 4294967294. |
| server.sandboxImagePullSecrets | list | [] |
Image pull secrets attached to sandbox pods. Referenced Secrets must exist in the sandbox namespace. |
| 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. |
| 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. |
| 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. |
| 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. |
| server.sandboxJwt.ttlSecs | int | 3600 |
Token TTL in seconds. Defaults to 3600 (1h). |
| server.sandboxNamespace | string | "" |
Namespace where sandbox pods are created. Defaults to the Helm release namespace (.Release.Namespace) when left empty. |
| 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. |
| server.telemetryEnabled | bool | true |
Enable anonymous OpenShell telemetry from the gateway and the sandbox supervisors it launches. |
| server.tls.certSecretName | string | "openshell-server-tls" |
K8s secret (type kubernetes.io/tls) with tls.crt and tls.key for the server. |
| 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. |
| server.tls.clientTlsSecretName | string | "openshell-client-tls" |
K8s secret mounted into sandbox pods for mTLS to the server. |
| server.tls.enableMtls | bool | true |
Enable mTLS client certificate authentication. When false, the gateway runs HTTPS-only without requiring client certificates (use OIDC for auth instead). Must be false when using BackendTLSPolicy because ingress proxies cannot present client certificates to the backend. |
| server.workspaceDefaultStorageSize | string | "" |
Default storage size for the workspace PVC in sandbox pods. Uses Kubernetes quantity syntax (e.g. "2Gi", "10Gi", "500Mi"). Empty = built-in default (2Gi). |
| server.workspaceStorageClass | string | "" |
Kubernetes StorageClass for the workspace PVC in sandbox pods. Empty (default) = omit storageClassName, using the cluster's default StorageClass. Set this on clusters with no default StorageClass, otherwise the workspace PVC stays Pending and the sandbox never starts. |
| service.healthPort | int | 8081 |
Gateway health service port. |
| service.metricsPort | int | 9090 |
Gateway metrics service port. |
| service.port | int | 8080 |
Gateway gRPC/HTTP service port. |
| service.type | string | "ClusterIP" |
Kubernetes Service type for the gateway. |
| serviceAccount.annotations | object | {} |
Annotations to add to the generated service account. |
| serviceAccount.create | bool | true |
Create a service account for the gateway. |
| serviceAccount.name | string | "" |
Existing service account name to use when serviceAccount.create is false. |
| supervisor.image.digest | string | "" |
Supervisor image digest. When set, this takes precedence over tag. |
| supervisor.image.pullPolicy | string | nil |
Supervisor image pull policy. Empty uses global.image.pullPolicy. Prefer always, if_not_present, or never; the chart also accepts legacy Kubernetes spellings Always, IfNotPresent, and Never. |
| supervisor.image.registry | string | "" |
Supervisor image registry. Empty uses global.image.registry. |
| supervisor.image.repository | string | "openshell/supervisor" |
Supervisor image repository. |
| supervisor.image.tag | string | "" |
Supervisor image tag. Defaults to the chart appVersion when empty. |
| supervisor.podSecurityContext.fsGroup | int | 65534 |
fsGroup assigned to the shared supervisor pod. |
| supervisor.podSecurityContext.runAsGroup | int | 65534 |
Primary GID assigned to the shared supervisor pod. |
| supervisor.podSecurityContext.runAsNonRoot | bool | true |
Require the shared supervisor to run as a non-root user. |
| supervisor.podSecurityContext.runAsUser | int | 65534 |
UID assigned to the shared supervisor pod. |
| supervisor.podSecurityContext.seccompProfile.type | string | "RuntimeDefault" |
Seccomp profile applied to the shared supervisor pod. |
| supervisor.sandboxRuntime.boundaryPort | int | 5500 |
Workload boundary TLS listener port. |
| tolerations | list | [] |
Tolerations for the gateway pod. |
| upstreamProxy | object | {"authAllowInsecure":false,"authSecret":{"key":"","name":""},"caBundle":{"configMapName":"","key":"ca.crt"},"connectByHostname":false,"noProxy":"","url":""} |
Operator-owned corporate forward proxy for policy-approved TLS egress from Kubernetes sandboxes. The workload cannot select or override it. |
| upstreamProxy.authAllowInsecure | bool | false |
Required when authSecret is configured because Basic auth to an HTTP proxy is cleartext. |
| upstreamProxy.authSecret.key | string | "" |
Secret key containing the proxy credential. |
| upstreamProxy.authSecret.name | string | "" |
Existing Secret in the sandbox namespace containing a user:pass value. |
| upstreamProxy.caBundle.configMapName | string | "" |
ConfigMap in the release namespace holding the corporate proxy CA bundle. Required for an https:// proxy with a private CA, and for a TLS-intercepting proxy that re-signs upstream certificates. The gateway reads it and stages it into each sandbox's immutable supervisor bootstrap Secret, so the anchor stays in the gateway's trust domain rather than the workload namespace. Supply only the CA that signs your proxy's certificate, or that the proxy re-signs intercepted upstream certificates with. Public roots already come from the supervisor image and its TLS stack, so a full merged trust bundle (for example an OpenShift config.openshift.io/inject-trusted-cabundle ConfigMap) adds hundreds of kilobytes of duplicated roots and can exceed the sandbox boundary's control-frame budget. |
| upstreamProxy.caBundle.key | string | "ca.crt" |
Key inside that ConfigMap. Change this only to reuse an existing ConfigMap whose key is not ca.crt. |
| upstreamProxy.connectByHostname | bool | false |
Last-resort option for hostname-filtering proxy ACLs. It lets the proxy resolve CONNECT targets. |
| upstreamProxy.noProxy | string | "" |
Comma-separated destinations that bypass only the corporate proxy. |
| upstreamProxy.url | string | "" |
Proxy URL in http://host:port or https://host:port form. An https:// proxy whose certificate is not publicly trusted also needs caBundle below. |
| workload.allowMultiReplicaStatefulSet | bool | false |
Allow replicaCount > 1 while rendering a StatefulSet. Prefer workload.kind=deployment for external database-backed multi-replica gateways; this override exists for operators who explicitly require StatefulSet identity or storage semantics. |
| workload.kind | string | "statefulset" |
Gateway workload controller kind. Use statefulset for the default SQLite database, or deployment when server.externalDbSecret points at an external database. |
| workspaceResources.enabled | bool | true |
Create the sandbox ServiceAccount, Role, RoleBinding, and NetworkPolicy from this chart. Disable for a gateway-only release. |
Autogenerated from chart metadata using helm-docs v1.14.2