feat(helm): add TLS termination for Envoy Gateway ingress#2015
Open
zhaohuabing wants to merge 1 commit into
Open
feat(helm): add TLS termination for Envoy Gateway ingress#2015zhaohuabing wants to merge 1 commit into
zhaohuabing wants to merge 1 commit into
Conversation
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 <zhaohuabing@gmail.com>
zhaohuabing
requested review from
a team,
derekwaynecarr,
maxamillion and
mrunalp
as code owners
TaylorMutch
reviewed
Jun 26, 2026
TaylorMutch
left a comment
TaylorMutch
left a comment
Collaborator
There was a problem hiding this comment.
Couple small comments, but I think this is looking good so far.
| {{- 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)" }} |
Collaborator
There was a problem hiding this comment.
Could we document a way to enable this? Possibly as a follow-up; it would be great to support end-to-end TLS, but I think this PR is a good first step.
| # 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). | ||
| certificateRefs: [] |
Collaborator
There was a problem hiding this comment.
If a certificate is provided by e.g. cert-manager, would that be supported automatically?
Contributor
Author
There was a problem hiding this comment.
Yes. A Gateway API certificateRefs entry just points at a kubernetes.io/tls Secret by name, and cert-manager can write that Secret when it issues a Certificate. Nothing here is coupled to how the Secret gets populated (manual, cert-manager, external-secrets, etc.).
Collaborator
|
Ah, just realized this is in draft still. Sorry! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The chart's optional Gateway API ingress only rendered a plaintext HTTP listener, so the OpenShell gateway could not be exposed over TLS. This adds an HTTPS listener option that terminates TLS at the Envoy Gateway and forwards plaintext gRPC to the gateway pod, with guardrails and docs for the supported configuration.
Related Issue
Close #2017
Changes
templates/gateway.yaml— renders an HTTPS listener withtls.mode: TerminateandcertificateRefswhengrpcRoute.gateway.listener.protocol=HTTPS; the default HTTP listener is unchanged. Twofailguards: emptycertificateRefs, and HTTPS withoutserver.disableTls=true(the chart does not render aBackendTLSPolicyfor re-encryption, so the backend hop must be plaintext).values.yaml— addsgrpcRoute.gateway.listener.tls.certificateRefsand clarifies protocol/port usage.ci/values-gateway-tls.yaml— new CI overlay exercising the HTTPS branch in lint/render.docs/kubernetes/ingress.mdx— documents HTTPS termination setup, and clarifies that Envoy Gateway only terminates TLS (no OIDCSecurityPolicy, which is browser-only); client identity uses OIDC bearer tokens, with the client-credentials grant for headless agents..agents/skills/debug-openshell-cluster/SKILL.md— adds HTTPS-ingress troubleshooting rows (plaintext-backend mismatch, unauthenticated-after-connect).README.md— regenerated chart values table.Testing
helm lint(defaults + all CI variants) andhelm templateverified: default renders the unchanged HTTP listener; HTTPS rendersTerminate+certificateRefs; bothfailguards fire as expected.mise run markdown:lint:md,mise run license:check, andmise run helm:docs:checkpass.codex exec review --uncommittedrun to convergence — no remaining findings.mise run pre-commitpasses — relevant checks (helm lint, markdown, license, helm-docs) pass;rust:lintfails on a pre-existing local env issue (missingz3.hsystem header), unrelated to these Helm/docs-only changesUnit tests added/updated — N/A (Helm template + docs only) - considering adding unit tests in a follow-up PR, as there is no existing unit tests for EG ingress yet.
E2E tests added/updated (if applicable) — not run locally (requires a live k3d + Envoy Gateway cluster); recommend running the Gateway API e2e path in CI - considering adding e2e tests in a follow-up PR, as there is no existing e2e tests for EG ingress yet.
Checklist
architecture/change needed; user-facing docs (docs/kubernetes/ingress.mdx) and the chart README/skill updated per AGENTS.md