feat: serve TLSRoute in Passthrough mode (backport apache/apisix-ingress-controller#2882)

.github/workflows/apisix-conformance-test.yml

@@ -32,6 +32,9 @@ concurrency:
 permissions:
   pull-requests: write
 
+env:
+  ADC_VERSION: dev
+
 jobs:
   conformance-test:
     env:
@@ -70,7 +73,6 @@ jobs:
           ARCH: amd64
           ENABLE_PROXY: "false"
           BASE_IMAGE_TAG: "debug"
-          # ADC_VERSION: "dev"
         run: |
           echo "building images..."
           make build-image

api/adc/types.go

@@ -170,7 +170,14 @@ type StreamRoute struct {
 	RemoteAddr string  `json:"remote_addr,omitempty"`
 	ServerAddr string  `json:"server_addr,omitempty"`
 	ServerPort int32   `json:"server_port,omitempty"`
-	SNI        string  `json:"sni,omitempty"`
+	// SNI and SNIs are the singular and plural forms of the same match; APISIX
+	// rejects a stream route carrying both, so only one is ever set.
+	SNI  string   `json:"sni,omitempty"`
+	SNIs []string `json:"snis,omitempty"`
+	// TLSPassthrough forwards the TLS stream to the upstream untouched instead
+	// of terminating it on the gateway. APISIX only consults it on a stream
+	// listen configured with both tls and tls_passthrough.
+	TLSPassthrough *bool `json:"tls_passthrough,omitempty"`
 }
 
 // +k8s:deepcopy-gen=true

docs/en/latest/concepts/gateway-api.md

@@ -85,6 +85,6 @@ The fields below are specified in the Gateway API specification but are either p
 | `spec.listeners[].port`               | Not supported*  | The configuration is required but ignored. This is due to limitations in the data plane: it cannot dynamically open new ports. Since the Ingress Controller does not manage the data plane deployment, it cannot automatically update the configuration or restart the data plane to apply port changes.    |
 | `spec.listeners[].tls.certificateRefs[].group` | Partially supported | Only `""` is supported; other group values cause validation failure. |
 | `spec.listeners[].tls.certificateRefs[].kind`        | Partially supported  | Only `Secret` is supported.                                                                    |
-| `spec.listeners[].tls.mode`                          | Partially supported  | `Terminate` is implemented; `Passthrough` is effectively unsupported for Gateway listeners.    |
+| `spec.listeners[].tls.mode`                          | Partially supported  | `Terminate` and `Passthrough` are both implemented. A `Passthrough` listener needs APISIX to be listening on that port with [`tls_passthrough`](https://apisix.apache.org/docs/apisix/stream-proxy/); the controller cannot open data plane ports itself. A single port cannot mix the two modes: listeners that disagree on `tls.mode` for one port are reported `Accepted=False` with `ProtocolConflict`. |
 | `spec.listeners[].tls.frontendValidation`            | Partially supported  | Enables downstream (client) mTLS. `caCertificateRefs` may reference a `ConfigMap` (Gateway API Core support) or a `Secret` (implementation-specific) holding the CA certificate under the `ca.crt` key; clients are then required to present a certificate signed by one of the referenced CAs. |
 | `spec.addresses`                                     | Not supported        | Controller does not read or act on `spec.addresses`.                                           |

internal/adc/translator/l4route_test.go

@@ -251,13 +251,20 @@ func TestTranslateTLSRouteWithL4RoutePolicy(t *testing.T) {
 			require.NoError(t, err)
 			require.Len(t, result.Services, 1)
 
-			// Verify stream routes are created per SNI hostname
-			if len(tt.hostnames) > 0 {
-				assert.Len(t, result.Services[0].StreamRoutes, len(tt.hostnames))
+			// One stream route carries every hostname: the singular sni for a
+			// single one, the plural snis beyond that. APISIX rejects both at once.
+			require.Len(t, result.Services[0].StreamRoutes, 1)
+			switch len(tt.hostnames) {
+			case 1:
+				assert.Equal(t, tt.hostnames[0], result.Services[0].StreamRoutes[0].SNI)
+				assert.Empty(t, result.Services[0].StreamRoutes[0].SNIs)
+			default:
+				assert.Equal(t, tt.hostnames, result.Services[0].StreamRoutes[0].SNIs)
+				assert.Empty(t, result.Services[0].StreamRoutes[0].SNI)
 			}
 
 			// Plugins are attached at the stream_route level so the APISIX stream proxy
-			// applies them; with multiple SNIs each stream_route carries its own copy.
+			// applies them.
 			require.NotEmpty(t, result.Services[0].StreamRoutes)
 			plugins := result.Services[0].StreamRoutes[0].Plugins
 			if tt.wantNoPlugins {

internal/adc/translator/tcproute.go

@@ -54,6 +54,26 @@ func listenerPortSet(tctx *provider.TranslateContext) map[int32]struct{} {
 	return portSet
 }
 
+// l4StreamRoutePorts returns the listener ports to emit one StreamRoute for
+// each, or the single sentinel 0 meaning one StreamRoute with no server_port
+// match at all. See buildL4StreamRoutes for why the injection is opt-in.
+func (t *Translator) l4StreamRoutePorts(tctx *provider.TranslateContext) []int32 {
+	var ports []int32
+	if portSet := listenerPortSet(tctx); t.shouldInjectServerPortVars(tctx.HasExplicitListenerMatch, portSet) {
+		ports = make([]int32, 0, len(portSet))
+		for port := range portSet {
+			ports = append(ports, port)
+		}
+		sort.Slice(ports, func(i, j int) bool { return ports[i] < ports[j] })
+	}
+	if len(ports) == 0 {
+		// No server_port isolation: a single StreamRoute that matches all
+		// connections on the stream listener, as before.
+		return []int32{0}
+	}
+	return ports
+}
+
 // buildL4StreamRoutes builds the StreamRoutes for one L4 route rule.
 //
 // A StreamRoute without a server_port match matches every connection on any
@@ -68,19 +88,7 @@ func listenerPortSet(tctx *provider.TranslateContext) map[int32]struct{} {
 // or more than one listener port). When it is not injected we keep the previous
 // single portless StreamRoute, preserving backward compatibility.
 func (t *Translator) buildL4StreamRoutes(tctx *provider.TranslateContext, namespace, name string, ruleIndex int, typ, routeKind string, labels map[string]string) []*adctypes.StreamRoute {
-	var ports []int32
-	if portSet := listenerPortSet(tctx); t.shouldInjectServerPortVars(tctx.HasExplicitListenerMatch, portSet) {
-		ports = make([]int32, 0, len(portSet))
-		for port := range portSet {
-			ports = append(ports, port)
-		}
-		sort.Slice(ports, func(i, j int) bool { return ports[i] < ports[j] })
-	}
-	if len(ports) == 0 {
-		// No server_port isolation: a single StreamRoute that matches all
-		// connections on the stream listener, as before.
-		ports = []int32{0}
-	}
+	ports := t.l4StreamRoutePorts(tctx)
 	streamRoutes := make([]*adctypes.StreamRoute, 0, len(ports))
 	for _, port := range ports {
 		streamRoute := adctypes.NewDefaultStreamRoute()

internal/adc/translator/tlsroute.go

@@ -20,6 +20,7 @@ package translator
 import (
 	"fmt"
 
+	"k8s.io/utils/ptr"
 	gatewayv1 "sigs.k8s.io/gateway-api/apis/v1"
 
 	adctypes "github.com/apache/apisix-ingress-controller/api/adc"
@@ -34,10 +35,7 @@ func (t *Translator) TranslateTLSRoute(tctx *provider.TranslateContext, tlsRoute
 	result := &TranslateResult{}
 	rules := tlsRoute.Spec.Rules
 	labels := label.GenLabel(tlsRoute)
-	hosts := make([]string, 0, len(tlsRoute.Spec.Hostnames))
-	for _, hostname := range tlsRoute.Spec.Hostnames {
-		hosts = append(hosts, string(hostname))
-	}
+	snis := tlsRouteSNIs(tctx, tlsRoute)
 	for ruleIndex, rule := range rules {
 		service := adctypes.NewDefaultService()
 		service.Labels = labels
@@ -143,16 +141,33 @@ func (t *Translator) TranslateTLSRoute(tctx *provider.TranslateContext, tlsRoute
 			}
 		}
 
-		for _, host := range hosts {
+		for _, port := range t.l4StreamRoutePorts(tctx) {
 			streamRoute := adctypes.NewDefaultStreamRoute()
-			streamRouteName := adctypes.ComposeStreamRouteName(tlsRoute.Namespace, tlsRoute.Name, fmt.Sprintf("%d", ruleIndex), "TLS")
+			ruleKey := fmt.Sprintf("%d", ruleIndex)
+			if port != 0 {
+				// Include the port in the name key so multiple listeners produce
+				// distinct StreamRoute names/IDs instead of colliding.
+				ruleKey = fmt.Sprintf("%d-%d", ruleIndex, port)
+				streamRoute.ServerPort = port
+			}
+			streamRouteName := adctypes.ComposeStreamRouteName(tlsRoute.Namespace, tlsRoute.Name, ruleKey, "TLS")
 			streamRoute.Name = streamRouteName
 			streamRoute.ID = id.GenID(streamRouteName)
-			streamRoute.SNI = host
+			// A single SNI keeps using the singular form: it is what every
+			// APISIX version understands, and snis only earns its place once
+			// there is more than one to match.
+			if len(snis) == 1 {
+				streamRoute.SNI = snis[0]
+			} else {
+				streamRoute.SNIs = snis
+			}
+			if tlsPassthroughOnPort(tctx.Listeners, port) {
+				streamRoute.TLSPassthrough = ptr.To(true)
+			}
 			streamRoute.Labels = labels
 			// Attach L4RoutePolicy plugins at the stream_route level: the APISIX stream proxy
-			// applies plugins from the stream_route, not from the service. With multiple SNIs
-			// each stream_route carries its own copy of the plugins.
+			// applies plugins from the stream_route, not from the service. With multiple
+			// listener ports each stream_route carries its own copy of the plugins.
 			streamRoute.Plugins = make(adctypes.Plugins)
 			t.AttachL4RoutePolicyPlugins(tctx.L4RoutePolicies, tlsRoute.Namespace, tlsRoute.Name, "TLSRoute", streamRoute.Plugins, tctx.Secrets)
 			service.StreamRoutes = append(service.StreamRoutes, streamRoute)
@@ -162,3 +177,64 @@ func (t *Translator) TranslateTLSRoute(tctx *provider.TranslateContext, tlsRoute
 	}
 	return result, nil
 }
+
+// tlsRouteSNIs returns the SNIs the route's stream routes match on.
+//
+// A TLSRoute without hostnames matches everything its listeners accept, so it
+// falls back to the matched listener hostnames and, when those carry none
+// either, to the catch-all "*". Emitting nothing - which is what the per
+// hostname loop used to do - left such a route attached but unserved.
+func tlsRouteSNIs(tctx *provider.TranslateContext, tlsRoute *gatewayv1.TLSRoute) []string {
+	if len(tlsRoute.Spec.Hostnames) > 0 {
+		snis := make([]string, 0, len(tlsRoute.Spec.Hostnames))
+		for _, hostname := range tlsRoute.Spec.Hostnames {
+			snis = append(snis, string(hostname))
+		}
+		return snis
+	}
+
+	snis := make([]string, 0, len(tctx.Listeners))
+	seen := make(map[string]struct{}, len(tctx.Listeners))
+	for _, listener := range tctx.Listeners {
+		if listener.Hostname == nil || *listener.Hostname == "" {
+			continue
+		}
+		hostname := string(*listener.Hostname)
+		if _, ok := seen[hostname]; ok {
+			continue
+		}
+		seen[hostname] = struct{}{}
+		snis = append(snis, hostname)
+	}
+	if len(snis) == 0 {
+		return []string{"*"}
+	}
+	return snis
+}
+
+// tlsPassthroughOnPort reports whether the stream routes bound to port must
+// forward the connection untouched instead of having the gateway terminate it.
+// port 0 means the StreamRoute carries no server_port match, so every matched
+// listener applies.
+//
+// Every matched TLS listener on the port has to agree. Within one Gateway a
+// port carrying both modes is already reported ProtocolConflict and attaches
+// no routes; across Gateways the combination is unrepresentable, since the
+// physical stream listen has a single mode - so the terminating behaviour wins
+// rather than a guess.
+func tlsPassthroughOnPort(listeners []gatewayv1.Listener, port int32) bool {
+	matched := false
+	for _, listener := range listeners {
+		if listener.Protocol != gatewayv1.TLSProtocolType {
+			continue
+		}
+		if port != 0 && listener.Port != port {
+			continue
+		}
+		if listener.TLS == nil || listener.TLS.Mode == nil || *listener.TLS.Mode != gatewayv1.TLSModePassthrough {
+			return false
+		}
+		matched = true
+	}
+	return matched
+}