Contact UsGet started

TLSRoute resource fields

Written by
Updated at April 1, 2025

The TLSRoute resource defines the rules for routing traffic across backends, i.e., Kubernetes services (the Service resources). TLSRoute handles incoming traffic from the Gateway resources whose criteria it meets.

TLSRoute is designed for application developers. Cluster operators should use Gateway.

TLSRoute is a Kubernetes resource specified by the Kubernetes Gateway API project. Below, you can find the descriptions of the resource fields Application Load Balancer Gateway API interfaces with. For a full description of the resource configuration, see the Kubernetes Gateway API documentation.

TLSRoute

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata: <ObjectMeta>
spec: <TLSRouteSpec>

Field

Value or type

Description

apiVersion

gateway.networking.k8s.io/v1alpha2

Required.
Kubernetes API version.

kind

TLSRoute

Required.
Resource type.

metadata

ObjectMeta

Required.
Resource metadata.

spec

TLSRouteSpec

Required.
Resource specification.
Example
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: sample-route
  namespace: route-namespace
spec:
  parentRefs:
  - name: sample-gateway
    sectionName: sample-listener
    namespace: gateway-namespace
  hostnames:
  - "sample.example.com"
  rules:
  - backendRefs:
    - name: sample-service
      port: 80

ObjectMeta

name: <string>
namespace: <string>

Field

Value or type

Description

name

string

Required.
Resource name.

This name is not the route name in Application Load Balancer.

namespace

string

Namespace the resource belongs to.

The default value is default.

TLSRouteSpec

parentRefs: <[]ParentReference>
hostnames: <[]Hostname>
rules: <[]TLSRouteRule>

Field

Value or type

Description

parentRefs

[]ParentReference

Required.
List of Gateway resources or their listeners TLSRoute must be linked to.

To get linked, the route must meet the rules described in the Gateway configuration (the spec.listeners.allowedRoutes field).

hostnames

[]Hostname

List of domain names matching the SNI attribute of the ClientHello message used during the TLS handshake.

To refer to every possible subdomain at any level, replace the first-level domain name with an asterisk (*). In this case, the value must be wrapped in quotes.

For instance, the "*.example.com" value matches foo.example.com, foo-bar.example.com, foo.bar.example.com, foo.bar.baz.example.com, etc., but does not match example.com.

You cannot replace only a part of a first-level domain name with an asterisk, as in *foo.example.com.

rules

[]TLSRouteRule

Required.
Request routing rules.

ParentReference

name: <string>
namespace: <string>
sectionName: <string>

Field

Value or type

Description

name

string

Required.
Gateway resource name.

namespace

string

Namespace the Gateway resource belongs to.

By default, it matches the TLSRoute resource namespace (the metadata.namespace field).

sectionName

string

Name of the listener specified in the Gateway resource.

TLSRouteRule

backendRefs:
  - name: <string>
    namespace: <string>
    port: <int32>
    weight: <int32>

Field

Value or type

Description

backendRefs

[]BackendRef

Required.
List of Kubernetes services acting as backends and processing requests.

All the listed services will be placed in the same backend group.

backendRefs.name

string

Required.
Name of the Kubernetes service acting as a backend.

The Service resource this field refers to must be described in line with the standard configuration.

backendRefs.namespace

string

Namespace the Service resource belongs to.

By default, it matches the namespace of the TLSRoute resource (the metadata.namespace field).

backendRefs.port

int32

Service port number.

This number must match one of the port numbers specified in the spec.ports.port fields of the Service resource.

backendRefs.weight

int32

Relative backend weight. In a backend group, traffic between backends is distributed in proportion to their weights.

Weights must be specified either for all backends in a group, or for none. If weights are not specified, traffic is distributed to the backends as if they had identical positive weights.

If a non-positive weight is specified, a backend will not receive traffic.
Previous
HTTPRoute
Next
Service for Gateway API