From b04c20f3fb256fc151cf3c48eba7b06185809be4 Mon Sep 17 00:00:00 2001 From: Piotr Mlocek Date: Fri, 2 Oct 2026 10:11:44 -0700 Subject: [PATCH] fix(config): use generic Helm gateway configuration Signed-off-by: Piotr Mlocek --- deploy/helm/openshell/README.md | 1 - .../openshell/templates/gateway-config.yaml | 7 -- deploy/helm/openshell/values.yaml | 3 - docs/how-it-works/gateways/configuration.mdx | 12 +++- docs/images/gateway-config-push-stage-1.svg | 72 +++++++++++++++++++ skills/debug-openshell-cluster/SKILL.md | 7 +- 6 files changed, 87 insertions(+), 15 deletions(-) create mode 100644 docs/images/gateway-config-push-stage-1.svg diff --git a/deploy/helm/openshell/README.md b/deploy/helm/openshell/README.md index 5829e1c96..df3ea173a 100644 --- a/deploy/helm/openshell/README.md +++ b/deploy/helm/openshell/README.md @@ -391,7 +391,6 @@ discovery endpoint or its TLS CA. | securityContext.runAsNonRoot | bool | `true` | Require the gateway container to run as a non-root user. | | securityContext.runAsUser | int | `1000` | UID assigned to the gateway container. | | 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. | -| server.configDeliveryMode | string | `""` | Supervisor configuration delivery. Empty uses the gateway release default (poll in 0.1.x). Push enables shadow snapshots in the Stage 1 gateway. | | server.credentialDrivers.kubernetesSecrets.createNamespace | bool | `false` | Create the credential namespace. Requires a namespace other than the release namespace. The Namespace is retained on uninstall so stored credentials survive; an existing Namespace not owned by this release is left untouched. | | server.credentialDrivers.kubernetesSecrets.enabled | bool | `false` | Enable the in-tree Kubernetes Secret credential driver. WARNING: The RBAC Role grants read/write access to ALL Secrets in the configured namespace. Use a dedicated namespace to limit blast radius. | | server.credentialDrivers.kubernetesSecrets.namespace | string | `""` | Namespace where OpenShell-managed provider Secret objects are stored. Empty = Helm release namespace. A dedicated namespace is RECOMMENDED to isolate OpenShell-managed Secrets from other workloads. | diff --git a/deploy/helm/openshell/templates/gateway-config.yaml b/deploy/helm/openshell/templates/gateway-config.yaml index 6b7b2d2b7..a3e0210a3 100644 --- a/deploy/helm/openshell/templates/gateway-config.yaml +++ b/deploy/helm/openshell/templates/gateway-config.yaml @@ -46,13 +46,6 @@ data: {{- end }} log_level = {{ .Values.server.logLevel | quote }} compute_driver = "kubernetes" - {{- $configDeliveryMode := .Values.server.configDeliveryMode | default "" }} - {{- if not (has $configDeliveryMode (list "" "poll" "push")) }} - {{- fail "server.configDeliveryMode must be empty, poll, or push" }} - {{- end }} - {{- if $configDeliveryMode }} - config_delivery_mode = {{ $configDeliveryMode | quote }} - {{- end }} {{- if $credentialDrivers }} credential_drivers = [{{- range $i, $driver := $credentialDrivers }}{{ if $i }}, {{ end }}{{ $driver | quote }}{{- end }}] {{- end }} diff --git a/deploy/helm/openshell/values.yaml b/deploy/helm/openshell/values.yaml index 01538f0ac..4bf21b88a 100644 --- a/deploy/helm/openshell/values.yaml +++ b/deploy/helm/openshell/values.yaml @@ -258,9 +258,6 @@ affinity: {} # Server configuration server: - # -- Supervisor configuration delivery. Empty uses the gateway release default - # (poll in 0.1.x). Push enables shadow snapshots in the Stage 1 gateway. - configDeliveryMode: "" # -- Operator-facing gateway name. Defaults to the chart fullname so all # replicas in one installation share an identity. Set explicitly when one # telemetry collector receives spans from multiple namespaces or clusters. diff --git a/docs/how-it-works/gateways/configuration.mdx b/docs/how-it-works/gateways/configuration.mdx index 445b6974c..c618942c3 100644 --- a/docs/how-it-works/gateways/configuration.mdx +++ b/docs/how-it-works/gateways/configuration.mdx @@ -26,7 +26,17 @@ On-disk SQLite databases run in WAL mode with `synchronous=FULL`: the gateway ke When shadow push is enabled, the gateway waits at most one second for an optional configuration bootstrap during supervisor reconnects. If a credential backend stalls, the gateway accepts the session without that bootstrap so SSH, exec, and service connections can resume. Supervisor polling continues to supply configuration. -In 0.1.x, `[openshell.gateway].config_delivery_mode` defaults to `poll`. Set it to `push` to enable experimental shadow configuration snapshots over the supervisor session. Supervisors in this release still apply configuration by polling, including when the gateway sends shadow snapshots. Set the mode with `--config-delivery-mode`, `OPENSHELL_CONFIG_DELIVERY_MODE`, or Helm `server.configDeliveryMode`. The Helm value is empty by default, so the chart omits the TOML key. During an upgrade, enable `push` only after every gateway replica supports this setting; an older gateway rejects the new TOML key. Keep the mode the same on all HA replicas. +In 0.1.x, `[openshell.gateway].config_delivery_mode` defaults to `poll`. Set it to `push` to enable experimental shadow snapshots over the supervisor session. Supervisors still apply configuration by polling in both modes. The gateway also accepts `--config-delivery-mode` and `OPENSHELL_CONFIG_DELIVERY_MODE`. + +With a Helm chart that supports `gatewayConfig`, set the same gateway TOML field through chart values: + +```yaml +gatewayConfig: + openshell.gateway: + config_delivery_mode: push +``` + +During an upgrade, enable `push` only after every gateway replica supports this setting. An older gateway rejects the new TOML key. Keep the mode the same on all HA replicas. On startup, the gateway repairs missing legacy policy history and skips invalid stored policies. A valid global policy can still override an invalid local policy; otherwise, that sandbox's configuration reads continue to report the validation failure. diff --git a/docs/images/gateway-config-push-stage-1.svg b/docs/images/gateway-config-push-stage-1.svg new file mode 100644 index 000000000..10d5dcaf1 --- /dev/null +++ b/docs/images/gateway-config-push-stage-1.svg @@ -0,0 +1,72 @@ + + + + + Stage 1 gateway configuration delivery + A configuration change is saved in the shared database. With push mode enabled, a hint reaches each gateway that owns an affected supervisor session. The owner sends a full snapshot, which the supervisor receives but ignores. In both modes, the supervisor continues to poll and apply configuration every ten seconds. + + + + + + + + + + + + Stage 1: push observes; polling applies + The saved configuration is the source for both paths. + + + Configuration + change + + + Shared DB + saves latest state + + + OPTIONAL PUSH MODE · SHADOW DELIVERY + + + Route update hint + to session owner(s) + across HA gateways + + + Owning gateway + builds full snapshot + + + Supervisor + receives and ignores + + + BOTH MODES · AUTHORITATIVE POLLING + + + Supervisor + polls every 10 seconds + + + Gateway + reads saved state + + + Supervisor + applies configuration + diff --git a/skills/debug-openshell-cluster/SKILL.md b/skills/debug-openshell-cluster/SKILL.md index 9a0b6f73b..597617ef3 100644 --- a/skills/debug-openshell-cluster/SKILL.md +++ b/skills/debug-openshell-cluster/SKILL.md @@ -482,9 +482,10 @@ be served by a non-owner gateway replica and relayed to the current supervisor owner over the internal `PeerRelay` RPC. Check the headless peer Service, projected peer ServiceAccount token volume, and TokenReview RBAC: -The experimental `server.configDeliveryMode: push` sends configuration hints -to that same peer endpoint over `PeerNotifyConfigUpdate`. Check that every -gateway replica runs a version supporting the RPC and uses the same mode. +The experimental `[openshell.gateway].config_delivery_mode = "push"` sends +configuration hints to that same peer endpoint over `PeerNotifyConfigUpdate`. +Check that every gateway replica runs a version supporting the RPC and uses +the same mode. `poll` is the 0.1.x default; a push setting in this release sends shadow snapshots while supervisors still poll. If hints fail, inspect `openshell_supervisor_config_peer_hints_total` and peer authentication logs.