From 08d153615bea6012a10ed67e54acb13929e1d55b Mon Sep 17 00:00:00 2001 From: Taylor Mutch Date: Tue, 17 Nov 2026 15:12:10 -0800 Subject: [PATCH] feat(helm)!: require opt-in for gateway service routing BREAKING CHANGE: Helm installations relying on gateway service URLs must explicitly set gatewayConfig."openshell.gateway".service_routing_enabled to true before upgrading. Core and non-Kubernetes defaults remain unchanged. Signed-off-by: Taylor Mutch --- deploy/helm/openshell/README.md | 25 ++++++++++++++- deploy/helm/openshell/README.md.gotmpl | 22 +++++++++++++ deploy/helm/openshell/templates/_toml.tpl | 4 +++ .../openshell/tests/gateway_config_test.yaml | 31 ++++++++++++++++--- deploy/helm/openshell/values.yaml | 3 ++ docs/how-it-works/gateways/configuration.mdx | 15 ++++++++- skills/debug-openshell-cluster/SKILL.md | 6 +++- 7 files changed, 98 insertions(+), 8 deletions(-) diff --git a/deploy/helm/openshell/README.md b/deploy/helm/openshell/README.md index c2940a0784..fcaad04f15 100644 --- a/deploy/helm/openshell/README.md +++ b/deploy/helm/openshell/README.md @@ -211,6 +211,28 @@ See [`values.yaml`](values.yaml) for source defaults. Selected overlays: - [`ci/values-spire.yaml`](ci/values-spire.yaml) - SPIFFE/SPIRE provider token grants - [`ci/values-spire-stack.yaml`](ci/values-spire-stack.yaml) - SPIRE hardened chart values for local development +### Sandbox service routing + +Gateway-mediated sandbox service routing is disabled by default in this Kubernetes +chart to avoid an unintended alternate application access path. Control-plane API +access is unchanged. Configure the supervisor app listener and external ingress +separately, or explicitly enable gateway forwarding: + +```yaml +gatewayConfig: + openshell.gateway: + service_routing_enabled: true +``` + +Existing Helm installations that rely on gateway service URLs must set this +explicitly before upgrading. Missing saved values receive the disabled chart +default; explicit choices are preserved. If neither routing mode is enabled, +startup logs warn that sandbox service routing is disabled. + +The core runtime continues to default gateway routing to enabled, preserving +Docker, Podman, and VM deployments outside this chart. Gateway service +authentication remains independently opt-in. + ### Additional destination CAs Create an operator-owned ConfigMap with a `ca.crt` key when sandboxes must reach @@ -577,7 +599,8 @@ discovery endpoint or its TLS CA. | 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. | +| gatewayConfig | object | `{"openshell":{"version":2},"openshell.gateway":{"service_routing_enabled":false}}` | 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. | +| gatewayConfig."openshell.gateway".service_routing_enabled | bool | `false` | Opt in to gateway-mediated sandbox service URLs and forwarding. Disabled for Kubernetes; configure application-listener ingress or explicitly enable this path. | | 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. | diff --git a/deploy/helm/openshell/README.md.gotmpl b/deploy/helm/openshell/README.md.gotmpl index 1d9f8c58dd..2fecd72b06 100644 --- a/deploy/helm/openshell/README.md.gotmpl +++ b/deploy/helm/openshell/README.md.gotmpl @@ -212,6 +212,28 @@ See [`values.yaml`](values.yaml) for source defaults. Selected overlays: - [`ci/values-spire.yaml`](ci/values-spire.yaml) - SPIFFE/SPIRE provider token grants - [`ci/values-spire-stack.yaml`](ci/values-spire-stack.yaml) - SPIRE hardened chart values for local development +### Sandbox service routing + +Gateway-mediated sandbox service routing is disabled by default in this Kubernetes +chart to avoid an unintended alternate application access path. Control-plane API +access is unchanged. Configure the supervisor app listener and external ingress +separately, or explicitly enable gateway forwarding: + +```yaml +gatewayConfig: + openshell.gateway: + service_routing_enabled: true +``` + +Existing Helm installations that rely on gateway service URLs must set this +explicitly before upgrading. Missing saved values receive the disabled chart +default; explicit choices are preserved. If neither routing mode is enabled, +startup logs warn that sandbox service routing is disabled. + +The core runtime continues to default gateway routing to enabled, preserving +Docker, Podman, and VM deployments outside this chart. Gateway service +authentication remains independently opt-in. + ### Additional destination CAs Create an operator-owned ConfigMap with a `ca.crt` key when sandboxes must reach diff --git a/deploy/helm/openshell/templates/_toml.tpl b/deploy/helm/openshell/templates/_toml.tpl index 45c35be635..38f889d3a0 100644 --- a/deploy/helm/openshell/templates/_toml.tpl +++ b/deploy/helm/openshell/templates/_toml.tpl @@ -102,6 +102,10 @@ Top-level lists represent TOML arrays of tables and preserve their YAML order. * {{- $config := deepCopy (.Values.gatewayConfig | default dict) -}} {{- $legacyServer := .Values.server | default dict -}} {{- $gateway := get $config "openshell.gateway" | default dict -}} +{{/* Keep the Kubernetes routing default when saved values omit it or use null. */}} +{{- if or (not (hasKey $gateway "service_routing_enabled")) (eq (get $gateway "service_routing_enabled") nil) -}} +{{- $_ := set $gateway "service_routing_enabled" false -}} +{{- end -}} {{- if not (hasKey $gateway "name") -}}{{- $_ := set $gateway "name" (get $legacyServer "name" | default (include "openshell.fullname" .)) -}}{{- end -}} {{/* The Service and probes own listener ports, so keep runtime listeners aligned. */}} {{- $_ := set $gateway "bind_address" (printf "0.0.0.0:%v" .Values.service.port) -}} diff --git a/deploy/helm/openshell/tests/gateway_config_test.yaml b/deploy/helm/openshell/tests/gateway_config_test.yaml index 26d4e3f438..b8332c905d 100644 --- a/deploy/helm/openshell/tests/gateway_config_test.yaml +++ b/deploy/helm/openshell/tests/gateway_config_test.yaml @@ -13,19 +13,40 @@ release: namespace: my-namespace tests: - - it: leaves gateway service routing enabled by the runtime default when omitted + - it: disables gateway service routing by default on Kubernetes template: templates/gateway-config.yaml asserts: - - notMatchRegex: + - matchRegex: path: data["gateway.toml"] - pattern: 'service_routing_enabled\s*=' + pattern: '(?m)^service_routing_enabled\s*=\s*false$' + + - it: allows explicitly enabling gateway service routing + template: templates/gateway-config.yaml + set: + gatewayConfig: + openshell.gateway: + service_routing_enabled: true + asserts: + - matchRegex: + path: data["gateway.toml"] + pattern: '(?m)^service_routing_enabled\s*=\s*true$' + + - it: defaults gateway routing off when saved configuration omits the gateway table + template: templates/gateway-config.yaml + set: + gatewayConfig: + openshell.gateway: null + asserts: + - matchRegex: + path: data["gateway.toml"] + pattern: '(?m)^service_routing_enabled\s*=\s*false$' - - it: disables gateway service routing through canonical configuration + - it: defaults gateway routing off when saved configuration omits the flag template: templates/gateway-config.yaml set: gatewayConfig: openshell.gateway: - service_routing_enabled: false + service_routing_enabled: null asserts: - matchRegex: path: data["gateway.toml"] diff --git a/deploy/helm/openshell/values.yaml b/deploy/helm/openshell/values.yaml index c8995f7926..81c9918c77 100644 --- a/deploy/helm/openshell/values.yaml +++ b/deploy/helm/openshell/values.yaml @@ -407,6 +407,9 @@ topologySpreadConstraints: [] gatewayConfig: openshell: version: 2 + openshell.gateway: + # -- Opt in to gateway-mediated sandbox service URLs and forwarding. Disabled for Kubernetes; configure application-listener ingress or explicitly enable this path. + service_routing_enabled: false # Server configuration server: diff --git a/docs/how-it-works/gateways/configuration.mdx b/docs/how-it-works/gateways/configuration.mdx index 0722f1be09..9172a8bbbf 100644 --- a/docs/how-it-works/gateways/configuration.mdx +++ b/docs/how-it-works/gateways/configuration.mdx @@ -607,7 +607,9 @@ and `https://--./` for the unnamed endpoint. The base domain is the first wildcard DNS SAN in `server_sans`; gateways without SANs use the built-in `openshell.localhost`. -`service_routing_enabled` defaults to `true`. Set it to `false` to stop publishing +The core runtime defaults `service_routing_enabled` to `true`; Docker, Podman, +and VM gateway behavior is unchanged. The Kubernetes Helm chart defaults it to +`false`. Set it to `false` to stop publishing gateway service URLs and reject gateway-mediated application HTTP requests and WebSocket upgrades with `404`. Control-plane APIs, service declarations, direct supervisor listeners, and discovery remain available. The setting also accepts @@ -621,6 +623,17 @@ gatewayConfig: service_routing_enabled: false ``` +For Kubernetes application ingress, enable and configure the supervisor app +listener and provision an ingress integration separately. The chart does not +enable either automatically. If both routing modes are disabled, startup logs +warn that sandbox service routing is disabled. + +When upgrading a Helm installation that uses gateway service URLs, explicitly +set `service_routing_enabled: true` in the canonical table above before the +upgrade. Missing saved values receive the chart's `false` default; explicit +`true` values remain enabled. This changes application forwarding only, not +control-plane API access or the service-authentication default. + With gateway routing disabled, `gateway_url` is empty and `gateway_service_urls` is empty. A configured application origin supplies the preferred URL; without one, preferred URLs are empty. Idempotent retries preserve recorded preferred diff --git a/skills/debug-openshell-cluster/SKILL.md b/skills/debug-openshell-cluster/SKILL.md index 5d93acde60..bdb6593e38 100644 --- a/skills/debug-openshell-cluster/SKILL.md +++ b/skills/debug-openshell-cluster/SKILL.md @@ -1760,7 +1760,11 @@ Watches recheck bearer credentials and membership every second. Allow one refres interval for withdrawals; route lease expiry remains independently enforced. For incorrect public service URLs, inspect -`[openshell.gateway].service_routing_enabled` first. When false, gateway URL fields +`[openshell.gateway].service_routing_enabled` first. The Helm chart defaults it +to false; the core runtime and non-Kubernetes deployments retain true. To retain +gateway forwarding in a Helm deployment or upgrade, set +`gatewayConfig."openshell.gateway".service_routing_enabled: true` explicitly. +When false, gateway URL fields are empty and gateway application requests return `404`; direct listener and discovery behavior is independent. Then inspect `[openshell.supervisor.app_listener].public_url`. It is an external HTTPS origin