TLSRoute API Reference¶

Introduction¶

With integration of the Gateway API, AWS Gateway API Controller supports TLSRoute. This allows you to define and manage end-to-end TLS encrypted traffic routing to your Kubernetes clusters.

Considerations¶

TLSRoute sectionName must refer to a TLS protocol listener with mode: Passthrough in the parentRefs Gateway. The tls.mode field must be explicitly set on the listener.
TLSRoute only supports exactly one rule.
Each rule must have at least one backendRef.
TLSRoute does not support any rule matching condition.
The hostnames field with exactly one host name is required. IP addresses are not allowed.

Annotations¶

application-networking.k8s.aws/idle-timeout-seconds
Sets the idle connection timeout, in seconds, for the VPC Lattice Service that this route maps to. The idle timeout is the amount of time a connection can remain idle (no data sent) before VPC Lattice closes it. Valid range is 60–600. If the annotation has never been set, VPC Lattice applies its default of 60 seconds. The value must be quoted, e.g. "120". An out-of-range or non-integer value is ignored (left unset) and logged as a warning.

Note

The idle timeout is distinct from the fixed maximum connection duration (10 minutes) enforced by VPC Lattice, which is not configurable. Raising the idle timeout only affects connections that are idle, not long-lived active connections.

Note

The controller manages this value only while the annotation is present. Removing the annotation leaves the last applied value on the VPC Lattice Service rather than reverting it, so a value set out-of-band is preserved. To change it back, set the annotation to the desired value (e.g. "60").

Example Configuration¶

Here is a sample configuration that demonstrates how to set up a TLSRoute resource to route end-to-end TLS encrypted traffic to a nginx service:

apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: nginx-tls-route
spec:
  hostnames:
    - nginx-test.my-test.com
  parentRefs:
    - name: my-hotel-tls-passthrough
      sectionName: tls
  rules:
    - backendRefs:
        - name: nginx-tls
          kind: Service
          port: 443

In this example:

The TLSRoute is named nginx-tls-route and is associated with a parent gateway named my-hotel-tls-passthrough that has a listener section named tls:
```
    - name: tls
      protocol: TLS
      port: 443
      tls:
        mode: Passthrough
```
The TLSRoute is configured to route traffic to a k8s service named nginx-tls on port 443.
The hostnames field is set to nginx-test.my-test.com. The customer must use this hostname to send traffic to the nginx service.

Cross-Cluster Routing with ServiceImport¶

TLSRoute supports routing to services in other clusters via ServiceImport. The remote cluster must export the service using a ServiceExport with routeType: TLS.

apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: nginx-tls-route
spec:
  hostnames:
    - nginx-test.my-test.com
  parentRefs:
    - name: my-hotel-tls-passthrough
      sectionName: tls
  rules:
    - backendRefs:
        - name: nginx-tls
          kind: ServiceImport

For the detailed tls passthrough traffic connectivity setup, please refer the user guide here.

For the detailed Gateway API TLSRoute resource specifications, you can refer to the Kubernetes official documentation.

For the VPC Lattice tls passthrough Listener configuration details, you can refer to the VPC Lattice documentation.