feat(helm): add optional PostgreSQL backing store with Secret-based credentials

- Add postgres.enabled and postgres.deploy values to control database
  backend (SQLite vs PostgreSQL) and subchart deployment independently.
- Introduce db-secret.yaml template for Opaque Secret with assembled
  postgresql:// connection string injected via OPENSHELL_DB_URL env var.
- Add Bitnami PostgreSQL as optional subchart dependency keyed on
  postgres.deploy to prevent subchart deployment in external mode.
- Externalize JWT signing key file mode via sandboxJwt.secretDefaultMode
  with 0400 default matching upstream.
- Add validation guard for postgres.deploy=true without postgres.enabled.
- Add helm unit tests covering internal, external, URL-override, special
  character encoding, and misconfiguration error paths.
- Update README with Kubernetes and OpenShift install examples for
  bundled and external PostgreSQL configurations.
- Add helm dependency build to lint and unittest tasks.

Author: sauagarwa

.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/
 

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

@@ -32,9 +32,8 @@ oc create ns openshell
 # Sandboxes are deployed into the openshell namespace and use the openshell-sandbox service account
 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
+# Deploy openshell with overrides for OpenShift SCC compatibility
 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,73 @@ 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
+```
+
+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
+```
+
+Enable bundled PostgreSQL(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:
+
+```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
+```
+
+Use external PostgreSQL (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
+```
+
+Or provide a full connection URL directly:
+
+```bash
+helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
+  --set postgres.enabled=true \
+  --set postgres.external.url="postgres://user:pass@host:5432/db?sslmode=require"
+```
+
 ## PKI bootstrap
 
 By default, a pre-install/pre-upgrade hook Job runs `openshell-gateway generate-certs`

deploy/helm/openshell/templates/_helpers.tpl

@@ -102,6 +102,32 @@ Namespace where sandbox pods are created. An explicit
 {{- .Values.server.sandboxNamespace | default .Release.Namespace -}}
 {{- end }}
 
+{{/*
+Gateway database URL.
+- postgres.enabled=false: use .Values.server.dbUrl (default sqlite)
+- postgres.enabled=true + deploy=true: derive URL from bundled postgres subchart
+- postgres.enabled=true + deploy=false: use external.url or compose external fields
+*/}}
+{{- define "openshell.dbUrl" -}}
+{{- if .Values.postgres.enabled -}}
+{{- if not .Values.postgres.deploy -}}
+{{- if .Values.postgres.external.url -}}
+{{- .Values.postgres.external.url -}}
+{{- else -}}
+{{- $host := required "postgres.external.host is required when postgres.deploy=false and no postgres.external.url is provided" .Values.postgres.external.host -}}
+{{- $pw := required "postgres.external.password is required when postgres.deploy=false and no postgres.external.url is provided" .Values.postgres.external.password -}}
+{{- printf "postgres://%s:%s@%s:%d/%s" (.Values.postgres.external.username | urlquery) ($pw | urlquery) $host (int (default 5432 .Values.postgres.external.port)) .Values.postgres.external.database -}}
+{{- end -}}
+{{- else -}}
+{{- $pw := required "postgres.auth.password must be set when postgres.enabled=true" .Values.postgres.auth.password -}}
+{{- $host := .Values.postgres.host | default (printf "%s-postgres.%s.svc.cluster.local" .Release.Name .Release.Namespace) -}}
+{{- printf "postgres://%s:%s@%s:%d/%s" (.Values.postgres.auth.username | urlquery) ($pw | urlquery) $host (int .Values.postgres.port) .Values.postgres.auth.database -}}
+{{- end -}}
+{{- else -}}
+{{- .Values.server.dbUrl -}}
+{{- end -}}
+{{- end }}
+
 {{/*
 gRPC endpoint sandbox pods use to call back into the gateway. An explicit
 .Values.server.grpcEndpoint is used verbatim. Otherwise it is derived from

deploy/helm/openshell/templates/db-secret.yaml

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{{- if .Values.postgres.enabled }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "openshell.fullname" . }}-db
+  labels:
+    {{- include "openshell.labels" . | nindent 4 }}
+type: Opaque
+stringData:
+  db-url: {{ include "openshell.dbUrl" . | quote }}
+{{- end }}

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

@@ -8,7 +8,8 @@ at startup. CLI flags and OPENSHELL_* env vars on the StatefulSet container
 still override anything in this file.
 
 One value is intentionally NOT rendered here:
-  - server.dbUrl              → passed via --db-url in the StatefulSet args
+  - server.dbUrl              → passed via OPENSHELL_DB_URL env var (from Secret)
+                                 when postgres.enabled=true, or --db-url arg for SQLite
 */}}
 apiVersion: v1
 kind: ConfigMap

deploy/helm/openshell/templates/statefulset.yaml

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
-
+{{- if and .Values.postgres.deploy (not .Values.postgres.enabled) }}
+{{- fail "postgres.deploy=true requires postgres.enabled=true" }}
+{{- end }}
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
@@ -21,6 +23,9 @@ spec:
         # without this annotation a `helm upgrade` that only mutates the
         # ConfigMap would leave pods running with stale config.
         checksum/gateway-config: {{ include (print $.Template.BasePath "/gateway-config.yaml") . | sha256sum }}
+        {{- if .Values.postgres.enabled }}
+        checksum/db-secret: {{ include (print $.Template.BasePath "/db-secret.yaml") . | sha256sum }}
+        {{- end }}
         {{- with .Values.podAnnotations }}
         {{- toYaml . | nindent 8 }}
         {{- end }}
@@ -54,9 +59,18 @@ spec:
           args:
             - --config
             - /etc/openshell/gateway.toml
+            {{- if not .Values.postgres.enabled }}
             - --db-url
             - {{ .Values.server.dbUrl | quote }}
+            {{- end }}
           env:
+            {{- if .Values.postgres.enabled }}
+            - name: OPENSHELL_DB_URL
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "openshell.fullname" . }}-db
+                  key: db-url
+            {{- end }}
             # All gateway settings live in the ConfigMap-backed TOML file
             # mounted at /etc/openshell/gateway.toml. The only env var below
             # is a process-level setting consumed by libraries outside
@@ -137,7 +151,7 @@ spec:
         - name: sandbox-jwt
           secret:
             secretName: {{ .Values.server.sandboxJwt.signingSecretName | default (printf "%s-jwt-keys" (include "openshell.fullname" .)) }}
-            defaultMode: 0400
+            defaultMode: {{ .Values.server.sandboxJwt.secretDefaultMode | default 0400 }}
         {{- if not .Values.server.disableTls }}
         - name: tls-cert
           secret:

deploy/helm/openshell/tests/gateway_config_test.yaml

@@ -5,6 +5,7 @@ suite: gateway TOML config shape
 templates:
   - templates/gateway-config.yaml
   - templates/statefulset.yaml
+  - templates/db-secret.yaml
 release:
   name: openshell
   namespace: my-namespace
@@ -125,3 +126,124 @@ tests:
       - matchRegex:
           path: data["gateway.toml"]
           pattern: 'server_sans\s*=\s*\["openshell", "\*\.dev\.openshell\.localhost"\]'
+
+  - it: passes sqlite db-url via --db-url arg by default
+    template: templates/statefulset.yaml
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].args
+          content: "sqlite:/var/openshell/openshell.db"
+
+  - it: does not create a db Secret when postgres is disabled
+    template: templates/db-secret.yaml
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: does not pass --db-url in args when postgres is enabled
+    template: templates/statefulset.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: true
+      postgres.auth.password: test-pw
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].args
+          content: "--db-url"
+
+  - it: injects OPENSHELL_DB_URL from Secret when postgres is enabled
+    template: templates/statefulset.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: true
+      postgres.auth.password: test-pw
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: OPENSHELL_DB_URL
+            valueFrom:
+              secretKeyRef:
+                name: openshell-db
+                key: db-url
+
+  - it: creates db Secret with internal postgres URL
+    template: templates/db-secret.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: true
+      postgres.auth.password: test-pw
+    asserts:
+      - isKind:
+          of: Secret
+      - equal:
+          path: stringData["db-url"]
+          value: "postgres://openshell:test-pw@openshell-postgres.my-namespace.svc.cluster.local:5432/openshell"
+
+  - it: creates db Secret with external postgres URL fields
+    template: templates/db-secret.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: false
+      postgres.external.host: external-postgres.example.com
+      postgres.external.port: 5432
+      postgres.external.database: openshell_ext
+      postgres.external.username: ext_user
+      postgres.external.password: ext_pass
+    asserts:
+      - isKind:
+          of: Secret
+      - equal:
+          path: stringData["db-url"]
+          value: "postgres://ext_user:ext_pass@external-postgres.example.com:5432/openshell_ext"
+
+  - it: uses external.url verbatim when provided
+    template: templates/db-secret.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: false
+      postgres.external.url: "postgres://custom:secret@my-host:5433/mydb?sslmode=require"
+    asserts:
+      - isKind:
+          of: Secret
+      - equal:
+          path: stringData["db-url"]
+          value: "postgres://custom:secret@my-host:5433/mydb?sslmode=require"
+
+  - it: URL-encodes special characters in credentials
+    template: templates/db-secret.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: true
+      postgres.auth.password: "p@ss:word"
+    asserts:
+      - equal:
+          path: stringData["db-url"]
+          value: "postgres://openshell:p%40ss%3Aword@openshell-postgres.my-namespace.svc.cluster.local:5432/openshell"
+
+  - it: fails when postgres is enabled but no password is set
+    template: templates/statefulset.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: true
+    asserts:
+      - failedTemplate:
+          errorMessage: "postgres.auth.password must be set when postgres.enabled=true"
+
+  - it: fails when postgres.deploy=true but postgres.enabled=false
+    template: templates/statefulset.yaml
+    set:
+      postgres.deploy: true
+    asserts:
+      - failedTemplate:
+          errorMessage: "postgres.deploy=true requires postgres.enabled=true"
+
+  - it: fails when external postgres has no password
+    template: templates/statefulset.yaml
+    set:
+      postgres.enabled: true
+      postgres.deploy: false
+      postgres.external.host: my-host.example.com
+    asserts:
+      - failedTemplate:
+          errorMessage: "postgres.external.password is required when postgres.deploy=false and no postgres.external.url is provided"