TLSRoute¶

Overview¶

TLSRoute is a Gateway API resource that routes Transport Layer Security (TLS) traffic within a Kubernetes cluster. It forwards encrypted traffic to backend services without ending the TLS session at the gateway. This is called TLS passthrough.

TLSRoute uses the Server Name Indication (SNI) field in the TLS ClientHello message to make routing decisions. This lets you direct traffic to the correct backend based on the hostname the client requests.

Note

TLSRoute support is introduced with the 1.5.0 standard Gateway API bundle. It has graduated to the standard channel and does not require the experimental bundle.

Key aspects of TLSRoute:¶

TLS passthrough routing: The gateway forwards encrypted TLS traffic end-to-end to backend services without terminating the TLS session.
SNI-based routing: The system routes traffic based on the SNI hostname in the TLS ClientHello message.
Wildcard hostnames: Supports wildcard hostnames (for example, *.example.com) for Gateway listeners and TLSRoute hostnames.
Cross-namespace support: The TLSRoute uses a ReferenceGrant to reference backend services in different namespaces.

Note

Weighted traffic distribution across multiple backendRefs is not supported.

Update a backend service¶

When you edit a backend service, the dataplane configuration does not update automatically. Follow these steps:

Delete the service.
Modify the YAML file of the service.
Reapply the service.

Note

Perform Custom Resource (CR) operations only when the controller is in a running state.

TLSRoute status¶

Accepted¶

conditions.status	conditions.reason	Description
Unknown	Pending	Initial state. Waiting for the controller.
True	Accepted	The route is accepted.
False	- NoMatchingParent - NotAllowedByListeners - NoMatchingListenerHostname	- No matching parents by name, port, or section name. - The route is not allowed by listeners. - The route has no matching listener hostname.

ResolvedRefs¶

conditions.status	conditions.reason	Description
True	ResolvedRefs	All references are resolved.
False	- InvalidKind - BackendRef has an invalid Kind. - RefNotPermitted	- The `backendRef` has an invalid Kind. - The `backendRef` is not found. - A cross-namespace reference is not permitted by a ReferenceGrant.

PartiallyInvalid¶

conditions.status	conditions.reason	Description
True	UnsupportedValue	The route contains both valid and invalid rules.

Note

The descriptions in these tables may not match the exact text in the status section of the CR.

Examples¶

This section lists sample CRs for common TLSRoute use cases.

Shared resources¶

Apply these resources before any of the TLSRoute examples.

GatewayClass:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: f5-gateway-class
spec:
  controllerName: "f5.com/f5-bnk-f5-cne-controller"
  description: "F5 BIG-IP Kubernetes Gateway"

GatewaySettings

Note

Create one instance of this resource per namespace.

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-tls
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam

Basic TLSRoute¶

The Gateway listener uses hostname: "*.example.com" to accept any subdomain. The TLSRoute attaches to this listener through sectionName and specifies the exact SNI hostname abc.example.com. The controller generates an SNI-based traffic policy rule that forwards matching TLS connections to the backend service without terminating TLS at the gateway.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-tls-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-tls
  gatewayClassName: f5-gateway-class
  listeners:
    - name: tls
      protocol: TLS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Passthrough
      allowedRoutes:
        namespaces:
          from: "All"
        kinds:
          - kind: TLSRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: my-tlsroute
  namespace: app-ns
spec:
  parentRefs:
    - name: f5-tls-gateway
      sectionName: tls
      namespace: gateway-infra
  hostnames:
    - "abc.example.com"
  rules:
    - backendRefs:
        - name: tls-backend-service
          port: 443
          namespace: app-ns

TLSRoute with wildcard hostname¶

When the TLSRoute specifies a wildcard hostname (for example, *.example.com), the controller generates a wildcard SNI condition using a suffix match. Any TLS ClientHello with a server name ending in .example.com is forwarded to the backend. The Gateway listener hostname must encompass the route hostname for the route to be accepted.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-tls-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-tls
  gatewayClassName: f5-gateway-class
  listeners:
    - name: tls
      protocol: TLS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Passthrough
      allowedRoutes:
        namespaces:
          from: "All"
        kinds:
          - kind: TLSRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: my-tlsroute-wildcard
  namespace: app-ns
spec:
  parentRefs:
    - name: f5-tls-gateway
      sectionName: tls
      namespace: gateway-infra
  hostnames:
    - "*.example.com"
  rules:
    - backendRefs:
        - name: tls-backend-service
          port: 443
          namespace: app-ns

TLSRoute with cross-namespace backend¶

When the TLSRoute and its backend Service are in different namespaces, a ReferenceGrant in the backend namespace must explicitly permit the cross-namespace reference. Without it, the route status shows ResolvedRefs=False with reason RefNotPermitted.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-tls-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-tls
  gatewayClassName: f5-gateway-class
  listeners:
    - name: tls
      protocol: TLS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Passthrough
      allowedRoutes:
        namespaces:
          from: "All"
        kinds:
          - kind: TLSRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: my-tlsroute
  namespace: gateway-infra
spec:
  parentRefs:
    - name: f5-tls-gateway
      sectionName: tls
      namespace: gateway-infra
  hostnames:
    - "abc.example.com"
  rules:
    - backendRefs:
        - name: tls-backend-service
          port: 443
          namespace: app-ns  # Cross-namespace reference requires a ReferenceGrant
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-tlsroute-backend
  namespace: app-ns
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: TLSRoute
      namespace: gateway-infra
  to:
    - group: ""
      kind: Service

TLSRoute parameters¶

The table below describes the TLSRoute spec parameters.

Parameter	Description	Details
`parentRefs.name`	The name of the parent Gateway resource. For example, `tls-gateway`.	As per the Gateway API community standard.
`parentRefs.namespace`	The namespace of the parent Gateway resource. When not specified, this refers to the local namespace of the Route.	As per the Gateway API community standard.
`parentRefs.port`	The network port that this TLSRoute targets. For example, `443`.	As per the Gateway API community standard.
`parentRefs.sectionName`	The section name of the parent Gateway listener. For example, `tls`.	As per the Gateway API community standard.
`hostnames`	A list of SNI hostnames to match TLSRoute. For example, `secure.example.com`. Wildcard hostnames like `*.example.com` are supported.	Used for SNI-based routing on the TLS ClientHello event.
`rules.backendRefs.name`	Name of the backend service to which traffic must be sent. For example, `tls-backend-service`.	As per the Gateway API community standard.
`rules.backendRefs.port`	Port on which the backend service is listening. For example, `443`.	As per the Gateway API community standard.
`rules.backendRefs.weight`	The weight for load balancing traffic between multiple backends.	Not supported.
`rules.backendRefs.namespace`	The namespace of the backend service. When not specified, this refers to the local namespace of the Route.	As per the Gateway API community standard.

Note

Refer to TLSRoute for more details.