Skip to content

Commit 84e88f7

Browse files
committed
refactor(helm): simplify PostgreSQL config to two orthogonal controls
Replace postgres.deploy and postgres.external.* with two simple controls: - postgres.enabled: deploy the bundled Bitnami PostgreSQL subchart - server.externalDbSecret: name of a pre-existing Secret with a uri key Delete db-secret.yaml — the chart no longer generates Secrets from individual credential fields. Users either get the Bitnami service-binding secret (bundled) or bring their own via server.externalDbSecret. Add validation that postgres.serviceBindings.enabled must stay true when using bundled PostgreSQL, preventing a confusing runtime failure.
1 parent 25ed9f6 commit 84e88f7

12 files changed

Lines changed: 106 additions & 345 deletions

File tree

‎deploy/helm/openshell/Chart.lock‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@ dependencies:
22
- name: postgresql
33
repository: oci://registry-1.docker.io/bitnamicharts
44
version: 18.6.7
5-
digest: sha256:ad78500c7c3a7ee365fd151890cf3368444d6b167c972052fc245024f5a25d9c
6-
generated: "2026-05-27T17:48:47.648592-04:00"
5+
digest: sha256:e4df764483edb0695ac56dd4e27eb3a225a9c0b0ef52a8b60e3e0b51e36153ab
6+
generated: "2026-05-28T18:05:12.507876-04:00"

‎deploy/helm/openshell/Chart.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,5 @@ dependencies:
1515
- name: postgresql
1616
version: 18.6.7
1717
repository: oci://registry-1.docker.io/bitnamicharts
18-
condition: postgres.deploy
18+
condition: postgres.enabled
1919
alias: postgres

‎deploy/helm/openshell/README.md‎

Lines changed: 16 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -68,62 +68,35 @@ postgres:
6868
enabled: false
6969
```
7070
71-
#### Use an existing Kubernetes Secret
71+
#### External PostgreSQL
7272
73-
If you already have a Secret containing PostgreSQL credentials (e.g. managed
74-
via GitOps or external-secrets-operator), point the chart at it directly:
73+
Create a Secret containing the PostgreSQL connection URI if one does not
74+
already exist:
7575
7676
```bash
77-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
78-
--set postgres.enabled=true \
79-
--set postgres.external.existingSecret=my-pg-credentials
77+
kubectl create secret generic my-pg-credentials -n openshell \
78+
--from-literal=uri="postgresql://user:pass@host:5432/dbname"
8079
```
8180

82-
On OpenShift, append the platform overrides:
81+
Then install the chart pointing at that Secret:
8382

8483
```bash
8584
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
86-
--set postgres.enabled=true \
87-
--set postgres.external.existingSecret=my-pg-credentials \
88-
--set server.disableTls=true \
89-
--set podSecurityContext.fsGroup=null \
90-
--set securityContext.runAsUser=null
91-
```
92-
93-
The Secret must contain a `uri` key with the full connection string:
94-
95-
```yaml
96-
apiVersion: v1
97-
kind: Secret
98-
metadata:
99-
name: my-pg-credentials
100-
type: Opaque
101-
data:
102-
uri: <base64> # postgresql://user:pass@host:5432/dbname
85+
-n openshell \
86+
--set server.externalDbSecret=my-pg-credentials
10387
```
10488

105-
#### Kubernetes
89+
#### Bundled PostgreSQL
10690

107-
Enable bundled PostgreSQL:
91+
Deploy a PostgreSQL instance alongside the gateway using the bundled
92+
Bitnami subchart. A random password is generated automatically:
10893

10994
```bash
11095
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
111-
--set postgres.enabled=true \
112-
--set postgres.deploy=true \
113-
--set postgres.auth.password=my-secret-password
96+
--set postgres.enabled=true
11497
```
11598

116-
Use external PostgreSQL (chart creates the Secret from fields):
117-
118-
```bash
119-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
120-
--set postgres.enabled=true \
121-
--set postgres.external.host=my-postgres.example.com \
122-
--set postgres.external.port=5432 \
123-
--set postgres.external.database=openshell \
124-
--set postgres.external.username=openshell \
125-
--set postgres.external.password=my-password
126-
```
99+
To set an explicit password, add `--set postgres.auth.password=my-secret-password`.
127100

128101
#### OpenShift
129102

@@ -135,33 +108,6 @@ Append these flags to any of the PostgreSQL commands above for OpenShift:
135108
--set securityContext.runAsUser=null
136109
```
137110

138-
Enable bundled PostgreSQL on OpenShift:
139-
140-
```bash
141-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
142-
--set postgres.enabled=true \
143-
--set postgres.deploy=true \
144-
--set postgres.auth.password=my-secret-password \
145-
--set server.disableTls=true \
146-
--set podSecurityContext.fsGroup=null \
147-
--set securityContext.runAsUser=null
148-
```
149-
150-
Use external PostgreSQL on OpenShift:
151-
152-
```bash
153-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
154-
--set postgres.enabled=true \
155-
--set postgres.external.host=my-postgres.example.com \
156-
--set postgres.external.port=5432 \
157-
--set postgres.external.database=openshell \
158-
--set postgres.external.username=openshell \
159-
--set postgres.external.password=my-password \
160-
--set server.disableTls=true \
161-
--set podSecurityContext.fsGroup=null \
162-
--set securityContext.runAsUser=null
163-
```
164-
165111
## PKI bootstrap
166112

167113
By default, a pre-install/pre-upgrade hook Job runs `openshell-gateway generate-certs`
@@ -218,14 +164,7 @@ cert-manager alternative.
218164
| postgres.auth.database | string | `"openshell"` | |
219165
| postgres.auth.password | string | `""` | |
220166
| postgres.auth.username | string | `"openshell"` | |
221-
| 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. |
222-
| postgres.enabled | bool | `false` | |
223-
| postgres.external.database | string | `"openshell"` | |
224-
| 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. |
225-
| postgres.external.host | string | `""` | |
226-
| postgres.external.password | string | `""` | |
227-
| postgres.external.port | int | `5432` | |
228-
| postgres.external.username | string | `"openshell"` | |
167+
| postgres.enabled | bool | `false` | Deploy the bundled Bitnami PostgreSQL subchart. |
229168
| postgres.primary.persistence.enabled | bool | `true` | |
230169
| postgres.serviceBindings.enabled | bool | `true` | |
231170
| probes.liveness.failureThreshold | int | `3` | Liveness probe failure threshold before the container is restarted. |
@@ -249,10 +188,11 @@ cert-manager alternative.
249188
| securityContext.runAsNonRoot | bool | `true` | Require the gateway container to run as a non-root user. |
250189
| securityContext.runAsUser | int | `1000` | UID assigned to the gateway container. |
251190
| 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. |
252-
| server.dbUrl | string | `"sqlite:/var/openshell/openshell.db"` | Gateway database URL. |
191+
| server.dbUrl | string | `"sqlite:/var/openshell/openshell.db"` | Gateway database URL (used for the default SQLite backend). |
253192
| 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. |
254193
| server.enableLoopbackServiceHttp | bool | `true` | Enable plaintext HTTP routing for loopback sandbox service URLs on TLS-enabled gateways. |
255194
| 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. |
195+
| 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. |
256196
| 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). |
257197
| 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. |
258198
| server.logLevel | string | `"info"` | Gateway log level. |

‎deploy/helm/openshell/README.md.gotmpl‎

Lines changed: 13 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -68,62 +68,35 @@ postgres:
6868
enabled: false
6969
```
7070

71-
#### Use an existing Kubernetes Secret
71+
#### External PostgreSQL
7272

73-
If you already have a Secret containing PostgreSQL credentials (e.g. managed
74-
via GitOps or external-secrets-operator), point the chart at it directly:
73+
Create a Secret containing the PostgreSQL connection URI if one does not
74+
already exist:
7575

7676
```bash
77-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
78-
--set postgres.enabled=true \
79-
--set postgres.external.existingSecret=my-pg-credentials
77+
kubectl create secret generic my-pg-credentials -n openshell \
78+
--from-literal=uri="postgresql://user:pass@host:5432/dbname"
8079
```
8180

82-
On OpenShift, append the platform overrides:
81+
Then install the chart pointing at that Secret:
8382

8483
```bash
8584
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
86-
--set postgres.enabled=true \
87-
--set postgres.external.existingSecret=my-pg-credentials \
88-
--set server.disableTls=true \
89-
--set podSecurityContext.fsGroup=null \
90-
--set securityContext.runAsUser=null
91-
```
92-
93-
The Secret must contain a `uri` key with the full connection string:
94-
95-
```yaml
96-
apiVersion: v1
97-
kind: Secret
98-
metadata:
99-
name: my-pg-credentials
100-
type: Opaque
101-
data:
102-
uri: <base64> # postgresql://user:pass@host:5432/dbname
85+
-n openshell \
86+
--set server.externalDbSecret=my-pg-credentials
10387
```
10488

105-
#### Kubernetes
89+
#### Bundled PostgreSQL
10690

107-
Enable bundled PostgreSQL:
91+
Deploy a PostgreSQL instance alongside the gateway using the bundled
92+
Bitnami subchart. A random password is generated automatically:
10893

10994
```bash
11095
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
111-
--set postgres.enabled=true \
112-
--set postgres.deploy=true \
113-
--set postgres.auth.password=my-secret-password
96+
--set postgres.enabled=true
11497
```
11598

116-
Use external PostgreSQL (chart creates the Secret from fields):
117-
118-
```bash
119-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
120-
--set postgres.enabled=true \
121-
--set postgres.external.host=my-postgres.example.com \
122-
--set postgres.external.port=5432 \
123-
--set postgres.external.database=openshell \
124-
--set postgres.external.username=openshell \
125-
--set postgres.external.password=my-password
126-
```
99+
To set an explicit password, add `--set postgres.auth.password=my-secret-password`.
127100

128101
#### OpenShift
129102

@@ -135,33 +108,6 @@ Append these flags to any of the PostgreSQL commands above for OpenShift:
135108
--set securityContext.runAsUser=null
136109
```
137110

138-
Enable bundled PostgreSQL on OpenShift:
139-
140-
```bash
141-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
142-
--set postgres.enabled=true \
143-
--set postgres.deploy=true \
144-
--set postgres.auth.password=my-secret-password \
145-
--set server.disableTls=true \
146-
--set podSecurityContext.fsGroup=null \
147-
--set securityContext.runAsUser=null
148-
```
149-
150-
Use external PostgreSQL on OpenShift:
151-
152-
```bash
153-
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> \
154-
--set postgres.enabled=true \
155-
--set postgres.external.host=my-postgres.example.com \
156-
--set postgres.external.port=5432 \
157-
--set postgres.external.database=openshell \
158-
--set postgres.external.username=openshell \
159-
--set postgres.external.password=my-password \
160-
--set server.disableTls=true \
161-
--set podSecurityContext.fsGroup=null \
162-
--set securityContext.runAsUser=null
163-
```
164-
165111
## PKI bootstrap
166112

167113
By default, a pre-install/pre-upgrade hook Job runs `openshell-gateway generate-certs`

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

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -122,15 +122,14 @@ postgres.fullnameOverride or postgres.nameOverride.
122122

123123
{{/*
124124
Name of the Secret holding the PostgreSQL connection URI.
125-
- deploy=true: derive from Bitnami service-binding naming convention
126-
- deploy=false + existingSecret set: use it verbatim
127-
- deploy=false + no existingSecret: use chart-generated "<fullname>-db"
125+
- server.externalDbSecret set: use it verbatim (always wins)
126+
- postgres.enabled=true: derive from Bitnami service-binding naming convention
128127
*/}}
129128
{{- define "openshell.dbSecretName" -}}
130-
{{- if .Values.postgres.deploy -}}
131-
{{- printf "%s-svcbind-custom-user" (include "openshell.postgresFullname" .) -}}
129+
{{- if .Values.server.externalDbSecret -}}
130+
{{- .Values.server.externalDbSecret -}}
132131
{{- else -}}
133-
{{- .Values.postgres.external.existingSecret | default (printf "%s-db" (include "openshell.fullname" .)) -}}
132+
{{- printf "%s-svcbind-custom-user" (include "openshell.postgresFullname" .) -}}
134133
{{- end -}}
135134
{{- end }}
136135

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

Lines changed: 0 additions & 28 deletions
This file was deleted.

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ still override anything in this file.
99

1010
One value is intentionally NOT rendered here:
1111
- server.dbUrl → passed via OPENSHELL_DB_URL env var (from Secret)
12-
when postgres.enabled=true, or --db-url arg for SQLite
12+
when postgres.enabled=true or server.externalDbSecret
13+
is set, otherwise --db-url arg for SQLite
1314
*/}}
1415
apiVersion: v1
1516
kind: ConfigMap

‎deploy/helm/openshell/templates/statefulset.yaml‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
22
# SPDX-License-Identifier: Apache-2.0
3-
{{- if and .Values.postgres.deploy (not .Values.postgres.enabled) }}
4-
{{- fail "postgres.deploy=true requires postgres.enabled=true" }}
3+
{{- if and .Values.postgres.enabled (not .Values.postgres.serviceBindings.enabled) (not .Values.server.externalDbSecret) }}
4+
{{- fail "postgres.serviceBindings.enabled must be true when using bundled PostgreSQL" }}
55
{{- end }}
66
apiVersion: apps/v1
77
kind: StatefulSet
@@ -23,9 +23,6 @@ spec:
2323
# without this annotation a `helm upgrade` that only mutates the
2424
# ConfigMap would leave pods running with stale config.
2525
checksum/gateway-config: {{ include (print $.Template.BasePath "/gateway-config.yaml") . | sha256sum }}
26-
{{- if and .Values.postgres.enabled (not .Values.postgres.deploy) (not .Values.postgres.external.existingSecret) }}
27-
checksum/db-secret: {{ include (print $.Template.BasePath "/db-secret.yaml") . | sha256sum }}
28-
{{- end }}
2926
{{- with .Values.podAnnotations }}
3027
{{- toYaml . | nindent 8 }}
3128
{{- end }}
@@ -59,12 +56,12 @@ spec:
5956
args:
6057
- --config
6158
- /etc/openshell/gateway.toml
62-
{{- if not .Values.postgres.enabled }}
59+
{{- if not (or .Values.postgres.enabled .Values.server.externalDbSecret) }}
6360
- --db-url
6461
- {{ .Values.server.dbUrl | quote }}
6562
{{- end }}
6663
env:
67-
{{- if .Values.postgres.enabled }}
64+
{{- if or .Values.postgres.enabled .Values.server.externalDbSecret }}
6865
- name: OPENSHELL_DB_URL
6966
valueFrom:
7067
secretKeyRef:

0 commit comments

Comments
 (0)