feat(helm): add optional PostgreSQL backing store

.gitignore

@@ -187,6 +187,9 @@ rootfs/
 # Docker build artifacts (image tarballs, packaged helm charts)
 deploy/docker/.build/
 
+# Helm subchart tarballs (regenerated by `helm dependency build`)
+deploy/helm/openshell/charts/
+
 # SBOM generated output (JSON, CSV) — release artifacts, not committed
 deploy/sbom/output/
 

README.md

@@ -157,7 +157,6 @@ Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall ba
 | [Ollama](https://ollama.com/)                                 | [Community](https://github.com/NVIDIA/OpenShell-Community)                       | Launch with `openshell sandbox create --from ollama`.                         |
 | [Pi](https://pi.dev/)                                 | [Community](https://github.com/NVIDIA/OpenShell-Community)                       | Launch with `openshell sandbox create --from pi`.                         |
 
-
 ## Key Commands
 
 | Command                                                    | Description                                     |

deploy/helm/openshell/Chart.lock

@@ -0,0 +1,6 @@
+dependencies:
+- name: postgresql
+  repository: oci://registry-1.docker.io/bitnamicharts
+  version: 18.6.7
+digest: sha256:ad78500c7c3a7ee365fd151890cf3368444d6b167c972052fc245024f5a25d9c
+generated: "2026-05-27T17:48:47.648592-04:00"

deploy/helm/openshell/Chart.yaml

@@ -11,3 +11,9 @@ type: application
 # empty), so a released chart automatically pulls the matching gateway and supervisor images.
 version: 0.0.0
 appVersion: "0.0.0"
+dependencies:
+  - name: postgresql
+    version: 18.6.7
+    repository: oci://registry-1.docker.io/bitnamicharts
+    condition: postgres.deploy
+    alias: postgres

deploy/helm/openshell/README.md

@@ -34,7 +34,6 @@ oc adm policy add-scc-to-user privileged -z openshell-sandbox -n 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 pkiInitJob.enabled=false \
   --set server.disableTls=true \
   --set podSecurityContext.fsGroup=null \
   --set securityContext.runAsUser=null
@@ -58,6 +57,111 @@ See [`values.yaml`](values.yaml) for source defaults. Selected overlays:
 - [`ci/values-cert-manager.yaml`](ci/values-cert-manager.yaml) - cert-manager integration
 - [`ci/values-keycloak.yaml`](ci/values-keycloak.yaml) - Keycloak OIDC integration
 
+### Database backend
+
+By default, OpenShell uses SQLite:
+
+```yaml
+server:
+  dbUrl: "sqlite:/var/openshell/openshell.db"
+postgres:
+  enabled: false
+```
+
+#### Use an existing Kubernetes Secret
+
+If you already have a Secret containing PostgreSQL credentials (e.g. managed
+via GitOps or external-secrets-operator), point the chart at it directly:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.existingSecret=my-pg-credentials
+```
+
+On OpenShift, append the platform overrides:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.existingSecret=my-pg-credentials \
+  --set server.disableTls=true \
+  --set podSecurityContext.fsGroup=null \
+  --set securityContext.runAsUser=null
+```
+
+The Secret must contain a `uri` key with the full connection string:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: my-pg-credentials
+type: Opaque
+data:
+  uri: <base64>  # postgresql://user:pass@host:5432/dbname
+```
+
+#### Kubernetes
+
+Enable bundled PostgreSQL:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.deploy=true \
+  --set postgres.auth.password=my-secret-password
+```
+
+Use external PostgreSQL (chart creates the Secret from fields):
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.host=my-postgres.example.com \
+  --set postgres.external.port=5432 \
+  --set postgres.external.database=openshell \
+  --set postgres.external.username=openshell \
+  --set postgres.external.password=my-password
+```
+
+#### 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
+```
+
+Enable bundled PostgreSQL on OpenShift:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.deploy=true \
+  --set postgres.auth.password=my-secret-password \
+  --set server.disableTls=true \
+  --set podSecurityContext.fsGroup=null \
+  --set securityContext.runAsUser=null
+```
+
+Use external PostgreSQL on OpenShift:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.host=my-postgres.example.com \
+  --set postgres.external.port=5432 \
+  --set postgres.external.database=openshell \
+  --set postgres.external.username=openshell \
+  --set postgres.external.password=my-password \
+  --set server.disableTls=true \
+  --set podSecurityContext.fsGroup=null \
+  --set securityContext.runAsUser=null
+```
+
 ## PKI bootstrap
 
 By default, a pre-install/pre-upgrade hook Job runs `openshell-gateway generate-certs`
@@ -111,6 +215,19 @@ cert-manager alternative.
 | podLabels | object | `{}` | Extra labels to add to the gateway pod. |
 | podLifecycle.terminationGracePeriodSeconds | int | `5` | Grace period, in seconds, before Kubernetes terminates the gateway pod. |
 | podSecurityContext.fsGroup | int | `1000` | fsGroup assigned to the gateway pod. |
+| postgres.auth.database | string | `"openshell"` |  |
+| postgres.auth.password | string | `""` |  |
+| postgres.auth.username | string | `"openshell"` |  |
+| postgres.deploy | bool | `false` | Deploy the bundled Bitnami PostgreSQL subchart. Set to true to run PostgreSQL alongside the gateway. Leave false when using an external PostgreSQL instance. |
+| postgres.enabled | bool | `false` |  |
+| postgres.external.database | string | `"openshell"` |  |
+| postgres.external.existingSecret | string | `""` | Name of a pre-existing Opaque Secret containing PostgreSQL credentials. When set, the chart does not create its own db Secret and reads directly from this one. The Secret must contain a `uri` key with the full connection string, e.g. postgresql://user:pass@host:5432/dbname. |
+| postgres.external.host | string | `""` |  |
+| postgres.external.password | string | `""` |  |
+| postgres.external.port | int | `5432` |  |
+| postgres.external.username | string | `"openshell"` |  |
+| postgres.primary.persistence.enabled | bool | `true` |  |
+| postgres.serviceBindings.enabled | bool | `true` |  |
 | 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. |
@@ -151,6 +268,7 @@ cert-manager alternative.
 | server.sandboxImagePullPolicy | string | `""` | Kubernetes imagePullPolicy for sandbox pods. Empty = Kubernetes default (Always for :latest, IfNotPresent otherwise). Set to "Always" for dev clusters so new images are picked up without manual eviction. |
 | 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. |

deploy/helm/openshell/README.md.gotmpl

@@ -34,7 +34,6 @@ oc adm policy add-scc-to-user privileged -z openshell-sandbox -n 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 pkiInitJob.enabled=false \
   --set server.disableTls=true \
   --set podSecurityContext.fsGroup=null \
   --set securityContext.runAsUser=null
@@ -58,6 +57,111 @@ See [`values.yaml`](values.yaml) for source defaults. Selected overlays:
 - [`ci/values-cert-manager.yaml`](ci/values-cert-manager.yaml) - cert-manager integration
 - [`ci/values-keycloak.yaml`](ci/values-keycloak.yaml) - Keycloak OIDC integration
 
+### Database backend
+
+By default, OpenShell uses SQLite:
+
+```yaml
+server:
+  dbUrl: "sqlite:/var/openshell/openshell.db"
+postgres:
+  enabled: false
+```
+
+#### Use an existing Kubernetes Secret
+
+If you already have a Secret containing PostgreSQL credentials (e.g. managed
+via GitOps or external-secrets-operator), point the chart at it directly:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.existingSecret=my-pg-credentials
+```
+
+On OpenShift, append the platform overrides:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.existingSecret=my-pg-credentials \
+  --set server.disableTls=true \
+  --set podSecurityContext.fsGroup=null \
+  --set securityContext.runAsUser=null
+```
+
+The Secret must contain a `uri` key with the full connection string:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: my-pg-credentials
+type: Opaque
+data:
+  uri: <base64>  # postgresql://user:pass@host:5432/dbname
+```
+
+#### Kubernetes
+
+Enable bundled PostgreSQL:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.deploy=true \
+  --set postgres.auth.password=my-secret-password
+```
+
+Use external PostgreSQL (chart creates the Secret from fields):
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.host=my-postgres.example.com \
+  --set postgres.external.port=5432 \
+  --set postgres.external.database=openshell \
+  --set postgres.external.username=openshell \
+  --set postgres.external.password=my-password
+```
+
+#### 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
+```
+
+Enable bundled PostgreSQL on OpenShift:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.deploy=true \
+  --set postgres.auth.password=my-secret-password \
+  --set server.disableTls=true \
+  --set podSecurityContext.fsGroup=null \
+  --set securityContext.runAsUser=null
+```
+
+Use external PostgreSQL on OpenShift:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.host=my-postgres.example.com \
+  --set postgres.external.port=5432 \
+  --set postgres.external.database=openshell \
+  --set postgres.external.username=openshell \
+  --set postgres.external.password=my-password \
+  --set server.disableTls=true \
+  --set podSecurityContext.fsGroup=null \
+  --set securityContext.runAsUser=null
+```
+
 ## PKI bootstrap
 
 By default, a pre-install/pre-upgrade hook Job runs `openshell-gateway generate-certs`