You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d8bd7f9
Browse filesBrowse the repository at this point in the historyBrowse files
feat(helm): add TLS termination for Envoy Gateway ingress
The chart's optional Gateway API ingress only rendered a plaintext HTTP
listener, so the gateway could not be exposed over TLS. Add an HTTPS
listener option that terminates TLS at the Envoy Gateway and forwards
plaintext gRPC to the gateway pod.
- gateway.yaml renders an HTTPS listener with `tls.mode: Terminate` and
`certificateRefs` when `grpcRoute.gateway.listener.protocol=HTTPS`,
keeping the default HTTP listener unchanged. Guards fail the render when
`certificateRefs` is empty or `server.disableTls` is not true (the chart
does not render a BackendTLSPolicy for re-encryption).
- values.yaml adds `grpcRoute.gateway.listener.tls.certificateRefs`.
- ci/values-gateway-tls.yaml exercises the HTTPS branch in lint/render.
- docs/kubernetes/ingress.mdx documents HTTPS setup and clarifies that
Envoy Gateway only terminates TLS (no OIDC SecurityPolicy); client
identity uses OIDC bearer tokens, with the client-credentials grant for
headless agents.
- debug-openshell-cluster skill gains HTTPS-ingress troubleshooting rows.
- Regenerated the chart README values table.
Signed-off-by: Huabing (Robin) Zhao <[email protected]>
Copy file name to clipboardExpand all lines: .agents/skills/debug-openshell-cluster/SKILL.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -297,6 +297,8 @@ openshell logs <sandbox-name>
297
297
| CLI TLS error | Local mTLS bundle does not match server cert/CA | Check `~/.config/openshell/gateways/<name>/mtls/`|
298
298
| Image pull failure | Gateway or sandbox image cannot be pulled | Runtime events and image pull credentials |
299
299
|`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 |
300
+
| 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>`|
301
+
| 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 |
Copy file name to clipboardExpand all lines: deploy/helm/openshell/README.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -151,8 +151,9 @@ add `ci/values-spire.yaml` to the OpenShell release values files.
151
151
| grpcRoute.gateway.className | string |`"eg"`| GatewayClass to reference. Envoy Gateway installs one named "eg". |
152
152
| 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. |
153
153
| grpcRoute.gateway.listener.allowedRoutes | string |`"Same"`| "Same" restricts attached routes to the release namespace; "All" allows any namespace. |
154
-
| grpcRoute.gateway.listener.port | int |`80`| Listener port for the generated Gateway resource. |
155
-
| grpcRoute.gateway.listener.protocol | string |`"HTTP"`| Listener protocol for the generated Gateway resource. |
154
+
| grpcRoute.gateway.listener.port | int |`80`| Listener port for the generated Gateway resource. Use 443 with protocol HTTPS. |
155
+
| 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). |
156
+
| 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). |
156
157
| grpcRoute.gateway.name | string |`""`| Name of the Gateway resource. Defaults to the chart fullname. |
157
158
| grpcRoute.gateway.namespace | string |`""`| Namespace of the Gateway referenced by the GRPCRoute parentRef. Defaults to the release namespace. |
158
159
| grpcRoute.hostnames | list |`[]`| Hostnames the GRPCRoute matches on. Leave empty to match all hosts. |
{{- if eq .Values.grpcRoute.gateway.listener.protocol "HTTPS" }}
19
+
{{- if not .Values.grpcRoute.gateway.listener.tls.certificateRefs }}
20
+
{{- fail "grpcRoute.gateway.listener.tls.certificateRefs is required when grpcRoute.gateway.listener.protocol is HTTPS" }}
21
+
{{- end }}
22
+
{{- if not .Values.server.disableTls }}
23
+
{{- 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)" }}
Envoy Gateway only terminates TLS here — it does not perform OIDC. Do not enable an Envoy Gateway OIDC `SecurityPolicy` in front of the gateway: that flow relies on browser redirects and cookies and cannot work with the OpenShell CLI or headless agents. Instead, the OpenShell gateway validates an OIDC bearer token that the client sends in the gRPC `authorization` metadata, which Envoy forwards untouched.
91
+
92
+
Because Envoy terminates TLS, the OpenShell gateway never sees a client certificate, so client mTLS cannot provide identity on this path. Use OIDC bearer tokens for client identity instead.
93
+
94
+
For headless agents and CI, the CLI obtains the token via the OAuth2 client-credentials grant (no browser): set `OPENSHELL_OIDC_CLIENT_SECRET` to the OAuth client secret before running `openshell gateway add`. The client id comes from `--oidc-client-id` (default `openshell-cli`); pass it explicitly if your IdP client uses a different id. Interactive human users get the browser-based Authorization Code + PKCE flow by default.
95
+
96
+
### Provide a TLS certificate
97
+
98
+
Create a `kubernetes.io/tls` Secret in the `openshell` namespace with the certificate for your external hostname:
The Secret may also be issued by cert-manager, or you can reference the chart's existing `openshell-server-tls` Secret if its SANs include the external hostname.
106
+
107
+
### Install with HTTPS termination
108
+
109
+
Enable an HTTPS listener, point it at the Secret, disable gateway-pod TLS so Envoy forwards plaintext, and configure an OIDC issuer for client identity:
0 commit comments