New Topic: TLS Offloading Service Configuration

[Rajakavitha1]

Is there an existing issue for this?

• [X] I have searched the existing issues

Problem Statement

Requested by @mflendrich

How to do TLS termination using Gateway API resources

Proposed Solution

No response

Additional information

No response

Acceptance Criteria

• Provide instructions how to do TLS termination using Gateway API resources
• Instructions may be provided as a response to this issue and @Rajakavitha1 will port to the WIP KIC 3.0 branch in docs

[rainest]

https://gateway-api.sigs.k8s.io/guides/migrating-from-ingress/#tls-termination and https://gateway-api.sigs.k8s.io/guides/tls/#clientserver-and-tls are the major upstream docs for understanding the Gateway API TLS model. We should link these.

https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway (the conformance profile bit under the Listener section) and https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.TLSModeType are additional references that we probably do not need to link to.

In brief, TLS termination or passthrough in GWAPI are configured via a combination of a Gateway's listeners[].tls.mode and the attached route type:

• Passthrough mode listeners inspect the TLS stream hostname via server name indication and pass the TLS stream unaltered upstream. These listeners do not use certificate configuration. They only accept TLSRoutes.
• Terminate mode listeners decrypt the TLS stream and inspect the request it wraps before passing it upstream. They require certificate Secret reference in the listeners[].tls.[]certificateRefs field. They accept HTTPRoutes, TCPRoutes, and GRPCRoutes (presumably--the doc doesn't mention GRPCRoutes, but likely because GRPCRoute was added the TLS sections were originally written: https://github.com/kubernetes-sigs/gateway-api/pull/2518).

To terminate TLS, you would create a Gateway with a listener with .tls.mode: "Terminate", create a TLS Secret and add it to the listener .tls.certificateRefs array, and then create one of the supported route types with matching criteria that will bind it to the listener (route hostname matches the listener hostname for HTTPRoute or GRPCRoute; route port matches the listener port for TCPRoute).

Reencryption is not yet specified in the final specification, but is under development in GEP 1897. Pending a final specification, we will presumably continue to rely on the existing konghq.com/protocol annotation on the upstream Service. https, tls, and grpcs values will reencrypt upstream traffic; http, tcp, and grpc values will send plaintext upstream.