feat(helm): use TLS passthrough for Gateway API

This revises the ingress approach introduced by commit abcd15d to use TLS
passthrough instead of termination at the Envoy proxy. Envoy reads the
ClientHello SNI for routing and forwards the encrypted stream to the OpenShell
gateway, which remains the TLS termnation endpoint. That preserves end-to-end
TLS and client certificate authentication, so existing mTLS continues to work
through Envoy.

Passthrough also avoids certificate management at the Envoy listener. It
does not require reusing the OpenShell server certificate as a Gateway
certificate or provisioning a separate edge certificate and Secret.
The server certificate only needs to cover the external SNI hostname.

This also restores the HTTP listener on the Gateway, adding TLS as an
additional listener when enabled.

The values were restructured to be under a gatewayApi umbrella rather than
grpcRoute as there are now both GRPCRoute and TLSRoute resources.

Signed-off-by: Kris Hicks <khicks@nvidia.com>

Author: krishicks

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -296,11 +296,9 @@ openshell logs <sandbox-name>
 | Kubernetes gateway pod crash loops | Missing secret, bad DB URL, bad TLS config | `kubectl -n openshell logs deployment/openshell -c openshell-gateway` or `kubectl -n openshell logs statefulset/openshell -c openshell-gateway` |
 | CLI TLS error | Local mTLS bundle does not match server cert/CA | Check `~/.config/openshell/gateways/<name>/mtls/` |
 | Image pull failure | Gateway or sandbox image cannot be pulled | Runtime events and image pull credentials |
-| `K8s namespace not ready` with `envoy-gateway-openshell.yaml: the server could not find the requested resource` | Optional Gateway API manifest was applied without Envoy Gateway CRDs, or k3s Helm controller startup exceeded the namespace wait | Apply `deploy/kube/manifests/envoy-gateway-openshell.yaml` manually only after Envoy Gateway is installed and `grpcRoute` is enabled |
-| HTTPS ingress (`grpcRoute.gateway.listener.protocol=HTTPS`) connection resets or TLS handshake hangs | Envoy terminates TLS but the gateway pod still expects TLS, so the plaintext backend hop fails | Set `server.disableTls=true` so Envoy forwards plaintext to the pod; verify the listener `certificateRefs` Secret exists in the release namespace and `openshell status` over `https://<host>` |
-| HTTPS ingress returns `Unauthenticated` after connecting | TLS terminates at Envoy, so the gateway never sees a client cert; no OIDC issuer is configured for identity | Configure `server.oidc.issuer` and register with `openshell gateway add https://<host> --oidc-issuer <url>`, or set `server.auth.allowUnauthenticatedUsers=true` for a trusted-proxy/dev cluster |
-
-## Reporting
+| `K8s namespace not ready` with `envoy-gateway-openshell.yaml: the server could not find the requested resource` | Optional Gateway API manifest was applied without Envoy Gateway CRDs, or k3s Helm controller startup exceeded the namespace wait | Apply `deploy/kube/manifests/envoy-gateway-openshell.yaml` manually only after Envoy Gateway is installed and a `gatewayApi` resource is enabled |
+| TLSRoute remains unaccepted or port 443 is not exposed | The referenced Gateway has no compatible TLS passthrough listener, or the Gateway API controller does not support TLSRoute | Check `kubectl describe tlsroute -n <namespace>` and `kubectl describe gateway -n <namespace>`; with a chart-created Gateway, verify both `gatewayApi.gateway.create=true` and `gatewayApi.routes.tls.enabled=true` |
+| TLS passthrough connection fails during the handshake | The gateway server is running plaintext or its certificate does not cover the external SNI hostname | Keep `server.disableTls=false`, verify the server certificate SAN, and configure `pkiInitJob.serverDnsNames` or `certManager.serverDnsNames` before issuing the certificate |
 
 When handing results back to the user, include:
 

deploy/helm/openshell/README.md

@@ -53,7 +53,8 @@ The `dev` tags are intended for testing changes ahead of a release. Production d
 
 See [`values.yaml`](values.yaml) for source defaults. Selected overlays:
 
-- [`ci/values-gateway.yaml`](ci/values-gateway.yaml) - gateway-only configuration
+- [`ci/values-gateway.yaml`](ci/values-gateway.yaml) - Gateway API configuration
+- [`ci/values-gateway-tls.yaml`](ci/values-gateway-tls.yaml) - Gateway API TLS passthrough configuration
 - [`ci/values-cert-manager.yaml`](ci/values-cert-manager.yaml) - cert-manager integration
 - [`ci/values-keycloak.yaml`](ci/values-keycloak.yaml) - Keycloak OIDC integration
 - [`ci/values-high-availability.yaml`](ci/values-high-availability.yaml) - CI overlay for multi-replica external PostgreSQL testing
@@ -147,16 +148,14 @@ add `ci/values-spire.yaml` to the OpenShell release values files.
 | certManager.serverDnsNames | list | `["openshell","openshell.openshell.svc","openshell.openshell.svc.cluster.local","localhost","openshell.localhost","*.openshell.localhost","host.docker.internal"]` | DNS SANs on the cert-manager-issued server certificate. |
 | certManager.serverIpAddresses | list | `["127.0.0.1"]` | IP SANs on the cert-manager-issued server certificate. |
 | fullnameOverride | string | `""` | Override the full generated resource name. |
-| grpcRoute.enabled | bool | `false` | Create a Gateway API GRPCRoute for the gateway service. |
-| grpcRoute.gateway.className | string | `"eg"` | GatewayClass to reference. Envoy Gateway installs one named "eg". |
-| grpcRoute.gateway.create | bool | `false` | When true, a Gateway resource is created in the release namespace. Set to false and provide name/namespace to attach to a pre-existing Gateway. |
-| grpcRoute.gateway.listener.allowedRoutes | string | `"Same"` | "Same" restricts attached routes to the release namespace; "All" allows any namespace. |
-| grpcRoute.gateway.listener.port | int | `80` | Listener port for the generated Gateway resource. Use 443 with protocol HTTPS. |
-| grpcRoute.gateway.listener.protocol | string | `"HTTP"` | Listener protocol for the generated Gateway resource: HTTP or HTTPS. HTTPS terminates TLS at the Envoy Gateway listener; pair it with server.disableTls=true so Envoy forwards plaintext to the gateway pod, and use OIDC for client identity (the gateway never sees the client cert). |
-| grpcRoute.gateway.listener.tls.certificateRefs | list | `[]` | certificateRefs for the HTTPS listener. Required when protocol is HTTPS. Each entry needs a `name` pointing at a kubernetes.io/tls Secret in the Gateway's namespace. May reference a cert-manager-issued Secret or the existing openshell-server-tls Secret (its SANs must include the external hostname). |
-| grpcRoute.gateway.name | string | `""` | Name of the Gateway resource. Defaults to the chart fullname. |
-| grpcRoute.gateway.namespace | string | `""` | Namespace of the Gateway referenced by the GRPCRoute parentRef. Defaults to the release namespace. |
-| grpcRoute.hostnames | list | `[]` | Hostnames the GRPCRoute matches on. Leave empty to match all hosts. |
+| gatewayApi.gateway.className | string | `"eg"` | GatewayClass to reference. Envoy Gateway installs one named "eg". |
+| gatewayApi.gateway.create | bool | `false` | When true, a Gateway resource is created. Set to false and provide name/namespace to attach to a pre-existing Gateway. |
+| gatewayApi.gateway.name | string | `""` | Name of the Gateway resource. Defaults to the chart fullname. |
+| gatewayApi.gateway.namespace | string | `""` | Namespace of a pre-existing Gateway referenced by routes. Defaults to the release namespace. Chart-created Gateways always use the release namespace. |
+| gatewayApi.routes.grpc.enabled | bool | `false` | Create a Gateway API GRPCRoute for the gateway service. |
+| gatewayApi.routes.grpc.hostnames | list | `[]` | Hostnames the GRPCRoute matches on. Leave empty to match all hosts. |
+| gatewayApi.routes.tls.enabled | bool | `false` | Create a Gateway API TLSRoute that passes encrypted traffic through to the gateway service. When gatewayApi.gateway.create is true, the generated Gateway also gets a TLS listener on port 443 in Passthrough mode. |
+| gatewayApi.routes.tls.hostnames | list | `[]` | SNI hostnames the TLSRoute matches on. Leave empty to match all hosts. |
 | image.pullPolicy | string | `"IfNotPresent"` | Gateway image pull policy. |
 | image.repository | string | `"ghcr.io/nvidia/openshell/gateway"` | Gateway image repository. |
 | image.tag | string | `""` | Gateway image tag. Defaults to the chart appVersion when empty. |

deploy/helm/openshell/README.md.gotmpl

@@ -53,7 +53,8 @@ The `dev` tags are intended for testing changes ahead of a release. Production d
 
 See [`values.yaml`](values.yaml) for source defaults. Selected overlays:
 
-- [`ci/values-gateway.yaml`](ci/values-gateway.yaml) - gateway-only configuration
+- [`ci/values-gateway.yaml`](ci/values-gateway.yaml) - Gateway API configuration
+- [`ci/values-gateway-tls.yaml`](ci/values-gateway-tls.yaml) - Gateway API TLS passthrough configuration
 - [`ci/values-cert-manager.yaml`](ci/values-cert-manager.yaml) - cert-manager integration
 - [`ci/values-keycloak.yaml`](ci/values-keycloak.yaml) - Keycloak OIDC integration
 - [`ci/values-high-availability.yaml`](ci/values-high-availability.yaml) - CI overlay for multi-replica external PostgreSQL testing

deploy/helm/openshell/ci/values-gateway-tls.yaml

@@ -1,33 +1,20 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-# Gateway API overlay with TLS termination at the Envoy Gateway listener.
-#
-# Exercises the HTTPS listener branch of templates/gateway.yaml for
-# `helm template`/lint coverage. Envoy Gateway terminates TLS using the
-# referenced kubernetes.io/tls Secret and forwards plaintext to the gateway pod,
-# so the gateway runs with TLS disabled and uses OIDC for client identity.
-#
-# The certificate Secret (openshell-ingress-tls) and the OIDC issuer below are
-# placeholders for render coverage; a real deployment must provide a valid TLS
-# Secret in the release namespace and a reachable OIDC issuer.
+# Gateway API overlay with TLS passthrough to the OpenShell gateway server.
+# Envoy routes by SNI without terminating TLS, preserving server TLS and mTLS.
 
-grpcRoute:
-  enabled: true
+gatewayApi:
   gateway:
     create: true
     className: "eg"
-    listener:
-      port: 443
-      protocol: HTTPS
-      tls:
-        certificateRefs:
-          - name: openshell-ingress-tls
-  hostnames: []
+  routes:
+    tls:
+      enabled: true
+      hostnames:
+        - openshell.example.com
 
-server:
-  # Envoy terminates TLS at the edge; the gateway listens plaintext behind it.
-  disableTls: true
-  oidc:
-    issuer: "https://keycloak.example.com/realms/openshell"
-    audience: "openshell-cli"
+# Include the external hostname in certificates generated for fresh installs.
+pkiInitJob:
+  serverDnsNames:
+    - openshell.example.com

deploy/helm/openshell/ci/values-gateway.yaml

@@ -15,12 +15,14 @@
 #   kubectl -n openshell port-forward svc/<envoy-service> 8080:80
 #   # then: grpcurl -plaintext localhost:8080 ...
 
-grpcRoute:
-  enabled: true
+gatewayApi:
   gateway:
     create: true
     className: "eg"
-  # Set one or more hostnames to scope the route, e.g.:
-  #   hostnames:
-  #     - openshell.example.com
-  hostnames: []
+  routes:
+    grpc:
+      enabled: true
+      # Set one or more hostnames to scope the route, e.g.:
+      #   hostnames:
+      #     - openshell.example.com
+      hostnames: []

deploy/helm/openshell/skaffold.yaml

@@ -71,14 +71,14 @@ deploy:
       #    crds.enabled: true
       # Envoy Gateway — Kubernetes Gateway API implementation.
       # Installs the Gateway API CRDs and the "eg" GatewayClass.
-      # Required when grpcRoute.enabled is true in the openshell release.
+      # Required when Gateway API routes are enabled in the openshell release.
       #- name: envoy-gateway
       #  remoteChart: oci://docker.io/envoyproxy/gateway-helm
-      #  version: v1.7.2
+      #  version: v1.8.1
       #  namespace: envoy-gateway-system
       #  createNamespace: true
       #  # wait ensures Gateway API CRDs are registered before the openshell
-      #  # release attempts to create Gateway and HTTPRoute resources.
+      #  # release attempts to create Gateway and route resources.
       #  wait: true
       # SPIRE — installs SPIRE Server, Agent, Controller Manager, CSI Driver,
       # and OIDC Discovery Provider using the SPIFFE hardened charts.
@@ -114,8 +114,10 @@ deploy:
           # setup task first, then uncomment the line below:
           #   mise run keycloak:k8s:setup
           #- ci/values-keycloak.yaml
-          # To enable the Gateway API HTTPRoute (requires Envoy Gateway above):
+          # To enable the Gateway API Gateway and GRPCRoute (requires Envoy Gateway above):
           #- ci/values-gateway.yaml
+          # To enable TLS passthrough instead (requires Envoy Gateway above):
+          #- ci/values-gateway-tls.yaml
           # To enable SPIFFE/SPIRE provider token grants (requires the
           # spire-crds and spire releases above):
           #- ci/values-spire.yaml

deploy/helm/openshell/templates/_helpers.tpl

@@ -109,6 +109,26 @@ Name of the Secret holding gateway-minted sandbox JWT signing material.
 {{- .Values.server.sandboxJwt.signingSecretName | default (printf "%s-jwt-keys" (include "openshell.fullname" .)) -}}
 {{- end }}
 
+{{/*
+Name of the Kubernetes Gateway API Gateway resource created or referenced by
+the chart.
+*/}}
+{{- define "openshell.gatewayApiGatewayName" -}}
+{{- .Values.gatewayApi.gateway.name | default (include "openshell.fullname" .) -}}
+{{- end }}
+
+{{/*
+Namespace of the Kubernetes Gateway API Gateway resource created or referenced
+by the chart.
+*/}}
+{{- define "openshell.gatewayApiGatewayNamespace" -}}
+{{- if .Values.gatewayApi.gateway.create -}}
+{{- .Release.Namespace -}}
+{{- else -}}
+{{- .Values.gatewayApi.gateway.namespace | default .Release.Namespace -}}
+{{- 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
@@ -178,6 +198,12 @@ database requires persistent per-pod storage.
 Validate chart values that Helm would otherwise accept silently.
 */}}
 {{- define "openshell.validateValues" -}}
+{{- if hasKey .Values "grpcRoute" -}}
+{{- fail "grpcRoute values were replaced by gatewayApi; configure Gateway creation under gatewayApi.gateway and GRPCRoute creation under gatewayApi.routes.grpc." -}}
+{{- end -}}
+{{- if and .Values.gatewayApi.routes.tls.enabled .Values.server.disableTls -}}
+{{- fail "gatewayApi.routes.tls.enabled requires server.disableTls=false because TLS passthrough forwards the encrypted connection to the gateway server." -}}
+{{- end -}}
 {{- $workloadKind := include "openshell.workloadKind" . -}}
 {{- $workload := .Values.workload | default dict -}}
 {{- $replicaCount := int (default 1 .Values.replicaCount) -}}

deploy/helm/openshell/templates/gateway.yaml

@@ -1,33 +1,25 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- if and .Values.grpcRoute.enabled .Values.grpcRoute.gateway.create }}
+{{- if .Values.gatewayApi.gateway.create }}
 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
-  name: {{ default (include "openshell.fullname" .) .Values.grpcRoute.gateway.name }}
-  namespace: {{ .Release.Namespace }}
+  name: {{ include "openshell.gatewayApiGatewayName" . }}
+  namespace: {{ include "openshell.gatewayApiGatewayNamespace" . }}
   labels:
     {{- include "openshell.labels" . | nindent 4 }}
 spec:
-  gatewayClassName: {{ .Values.grpcRoute.gateway.className }}
+  gatewayClassName: {{ .Values.gatewayApi.gateway.className }}
   listeners:
-    - name: {{ ternary "https" "http" (eq .Values.grpcRoute.gateway.listener.protocol "HTTPS") }}
-      port: {{ .Values.grpcRoute.gateway.listener.port }}
-      protocol: {{ .Values.grpcRoute.gateway.listener.protocol }}
-      {{- if eq .Values.grpcRoute.gateway.listener.protocol "HTTPS" }}
-      {{- if not .Values.grpcRoute.gateway.listener.tls.certificateRefs }}
-      {{- fail "grpcRoute.gateway.listener.tls.certificateRefs is required when grpcRoute.gateway.listener.protocol is HTTPS" }}
-      {{- end }}
-      {{- if not .Values.server.disableTls }}
-      {{- fail "grpcRoute.gateway.listener.protocol=HTTPS terminates TLS at Envoy Gateway, which forwards plaintext gRPC to the gateway pod; set server.disableTls=true so the pod listens plaintext (this chart does not render a BackendTLSPolicy for re-encryption to a TLS backend)" }}
-      {{- end }}
+    - name: http
+      port: 80
+      protocol: HTTP
+    {{- if .Values.gatewayApi.routes.tls.enabled }}
+    - name: tls
+      port: 443
+      protocol: TLS
       tls:
-        mode: Terminate
-        certificateRefs:
-          {{- toYaml .Values.grpcRoute.gateway.listener.tls.certificateRefs | nindent 10 }}
-      {{- end }}
-      allowedRoutes:
-        namespaces:
-          from: {{ .Values.grpcRoute.gateway.listener.allowedRoutes }}
+        mode: Passthrough
+    {{- end }}
 {{- end }}

deploy/helm/openshell/templates/grpcroute.yaml

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-{{- if .Values.grpcRoute.enabled }}
+{{- if .Values.gatewayApi.routes.grpc.enabled }}
 apiVersion: gateway.networking.k8s.io/v1
 kind: GRPCRoute
 metadata:
@@ -11,11 +11,11 @@ metadata:
     {{- include "openshell.labels" . | nindent 4 }}
 spec:
   parentRefs:
-    - name: {{ default (include "openshell.fullname" .) .Values.grpcRoute.gateway.name }}
-      namespace: {{ default .Release.Namespace .Values.grpcRoute.gateway.namespace }}
-  {{- if .Values.grpcRoute.hostnames }}
+    - name: {{ include "openshell.gatewayApiGatewayName" . }}
+      namespace: {{ include "openshell.gatewayApiGatewayNamespace" . }}
+  {{- if .Values.gatewayApi.routes.grpc.hostnames }}
   hostnames:
-    {{- toYaml .Values.grpcRoute.hostnames | nindent 4 }}
+    {{- toYaml .Values.gatewayApi.routes.grpc.hostnames | nindent 4 }}
   {{- end }}
   rules:
     - backendRefs:

deploy/helm/openshell/templates/tlsroute.yaml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{{- if .Values.gatewayApi.routes.tls.enabled }}
+apiVersion: gateway.networking.k8s.io/v1
+kind: TLSRoute
+metadata:
+  name: {{ include "openshell.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "openshell.labels" . | nindent 4 }}
+spec:
+  parentRefs:
+    - name: {{ include "openshell.gatewayApiGatewayName" . }}
+      namespace: {{ include "openshell.gatewayApiGatewayNamespace" . }}
+  {{- if .Values.gatewayApi.routes.tls.hostnames }}
+  hostnames:
+    {{- toYaml .Values.gatewayApi.routes.tls.hostnames | nindent 4 }}
+  {{- end }}
+  rules:
+    - backendRefs:
+        - name: {{ include "openshell.fullname" . }}
+          port: {{ .Values.service.port }}
+{{- end }}