Skip to content

Commit a1a1933

Browse files
committed
docs(helm): move chart configuration guidance to Kubernetes setup
Signed-off-by: Taylor Mutch <[email protected]>
1 parent aa5e148 commit a1a1933

2 files changed

Lines changed: 37 additions & 49 deletions

File tree

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

Lines changed: 2 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -16,55 +16,8 @@ The OpenShell gateway reads its configuration from a TOML file when `--config` o
1616
Gateway CLI flag > gateway OPENSHELL_* env var > TOML file > built-in default
1717
```
1818

19-
## Helm Configuration Boundary
20-
21-
The Kubernetes Helm chart exposes `gatewayConfig` as the non-secret gateway
22-
application-configuration boundary. Each top-level map key names a TOML table,
23-
and the chart serializes its fields into the mounted `gateway.toml` ConfigMap.
24-
New non-secret gateway options therefore do not require a chart-template
25-
change.
26-
27-
Secret material never belongs in `gatewayConfig` or the ConfigMap. Database
28-
URLs, credentials, private keys, and equivalent values use Kubernetes Secrets
29-
through the chart's supported environment-variable, file, or volume wiring.
30-
The normal precedence above still applies to the resulting mounted TOML file.
31-
32-
During Helm values migration, explicit `gatewayConfig` tables take precedence
33-
over deprecated aliases. This includes the resource-admission table and the
34-
Kubernetes Secrets credential namespace, even when a legacy alias still enables
35-
the credential driver. The global Helm image pull policy applies to runtime
36-
and supervisor images. Leave the workload's `image_pull_policy` and deprecated
37-
`sandbox.image.pullPolicy` unset to use Kubernetes defaults for the workload image.
38-
39-
The chart rejects the gateway's `database_url` file field and unambiguous
40-
inline credential or PEM private-key strings before rendering a ConfigMap. It
41-
validates Secret references as Kubernetes Secret names, but never reads or
42-
copies referenced Secret data into `gateway.toml`.
43-
44-
The serializer has a deterministic YAML-to-TOML contract. YAML `null` fields
45-
are omitted; `null` array members are rejected because TOML has no equivalent.
46-
Strings and booleans retain their TOML types, and numeric values remain TOML
47-
numbers. Helm normalizes YAML numbers before templates run, so it cannot retain
48-
the lexical distinction between an integral float such as `1.0` and an integer
49-
such as `1`; both render as the compact TOML value `1`. Scalar arrays become
50-
TOML arrays, maps become inline tables, and arrays of maps inside a table become
51-
arrays of inline tables. A top-level `gatewayConfig` list instead renders an
52-
ordered TOML array of tables: each list item must be a map and emits one
53-
`[[table]]` block. Keys are ordered alphabetically within each table, while
54-
array-of-tables item order follows the YAML list, so equivalent input produces
55-
the same ConfigMap checksum. String values are serialized literally; Helm
56-
template expressions inside them are not evaluated.
57-
58-
The implementation intentionally uses only long-standing Helm 3 template and
59-
Sprig functions (`kindIs`, `keys`, `sortAlpha`, `splitList`, `quote`, and
60-
`toJson`); it does not rely on a Helm-specific TOML encoder. This preserves the
61-
chart's documented Helm 3 compatibility while making the serialization rules
62-
explicit in the chart itself.
63-
64-
Helm retains ownership of Services, workloads, probes, Secrets, certificate
65-
resources, Routes, RBAC, NetworkPolicies, and mounts. When one of those inputs
66-
also determines a gateway runtime value, the chart derives it from its resource
67-
owner instead of exposing two independent settings.
19+
For Helm deployments, see [Configure Chart Values](/kubernetes/setup#configure-chart-values)
20+
for setting `gatewayConfig` and chart-owned Kubernetes resources.
6821

6922
`database_url` is env-only. The loader rejects it when it appears in the file. When `OPENSHELL_DB_URL` is unset, the gateway stores its SQLite database under `$XDG_STATE_HOME/openshell/gateway/openshell.db`.
7023

‎docs/kubernetes/setup.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,41 @@ openshell status
230230

231231
## Configure Chart Values
232232

233+
The Helm chart renders `gatewayConfig` into the mounted `gateway.toml`
234+
ConfigMap. Each top-level key names a TOML table, and its fields use the names
235+
in the [gateway configuration reference](/how-it-works/gateways/configuration).
236+
For example, set the gateway log level with:
237+
238+
```shell
239+
helm upgrade openshell \
240+
oci://ghcr.io/nvidia/openshell/helm-chart \
241+
--version <version> \
242+
--namespace openshell \
243+
--set 'gatewayConfig.openshell\.gateway.log_level=debug'
244+
```
245+
246+
Keep credentials, database URLs, and private keys in Kubernetes Secrets,
247+
using the chart's environment-variable, file, or volume wiring. The chart
248+
rejects `database_url`, inline URL credentials, and PEM private keys in
249+
`gatewayConfig`, but it does not detect every possible secret.
250+
251+
Helm values for Services, probes, TLS certificates, Secret references, RBAC,
252+
NetworkPolicies, and mounts still control those Kubernetes resources. The
253+
chart derives their corresponding runtime settings to keep the gateway
254+
configuration aligned with the deployed resources.
255+
256+
YAML scalar values retain their types, scalar lists become TOML arrays, and
257+
nested maps become inline tables. Top-level lists become arrays of tables and
258+
preserve item order. Null fields are omitted; null array elements are invalid.
259+
Helm template expressions in strings are not evaluated.
260+
261+
Existing application values remain supported as deprecated aliases. Explicit
262+
`gatewayConfig` fields take precedence, including resource-admission settings
263+
and the Kubernetes Secrets credential namespace. The global image pull policy
264+
applies to runtime and supervisor images. Leave `image_pull_policy` and
265+
`sandbox.image.pullPolicy` unset to use Kubernetes defaults for the workload
266+
image.
267+
233268
The most commonly changed values are:
234269

235270
| Value | Purpose |

0 commit comments

Comments
 (0)