TLSRoute resource fields

Written by

Updated at April 22, 2025

TLSRoute
ObjectMeta
TLSRouteSpec
- ParentReference
- TLSRouteRule

The TLSRoute resource specifes routing rules for TLS traffic to Kubernetes services backends, i.e. Service resources. TLSRoute receives incoming traffic that has passed through Gateway resource filters.

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

TLSRoute is a Kubernetes Gateway API project resource. Below, we describe its fields and annotations used by Application Load Balancer Gateway API. For configuration details, see the Kubernetes Gateway API reference.

TLSRoute

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

Field	Value / Type	Description
`apiVersion`	`gateway.networking.k8s.io/v1alpha2`	This is a required field. Kubernetes API version.
`kind`	`TLSRoute`	This is a required field. Resource type.
`metadata`	`ObjectMeta`	This is a required field. Resource metadata.
`spec`	`TLSRouteSpec`	This is a required field. 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 / Type

Description

name

string

This is a required field.
Resource name.

Do not mistake this name for the Application Load Balancer route name.

namespace

string

Resource namespace.

The default value is default.

TLSRouteSpec

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

Field	Value / Type	Description
`parentRefs`	`[]ParentReference`	This is a required field. `Gateway` resources or their listeners admitting traffic for the `TLSRoute`. For the `TLSRoute` to receive `Gateway` traffic, it must comply with the rules specified in its configuration, i.e., `spec.listeners.allowedRoutes` field.
`hostnames`	`[]Hostname`	Domain names matching the `SNI` value in the `ClientHello` TLS handshake message. To match all subdomains at any level, use a wildcard `` in place of the first-level domain name. Wildcard domain values must be quoted. For example, `".example.com"` matches `foo.example.com`, `foo-bar.example.com`, `foo.bar.example.com`, and `foo.bar.baz.example.com`, but not `example.com`. Wildcards must replace complete domain levels; for example, `*foo.example.com` is invalid.
`rules`	`[]TLSRouteRule`	This is a required field. Request routing rules.

ParentReference

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

Field	Value / Type	Description
`name`	`string`	This is a required field. `Gateway` resource name.
`namespace`	`string`	`Gateway` resource namespace. By default, it matches the `TLSRoute` resource metadata.namespace value.
`sectionName`	`string`	Name of the listener specified in the `Gateway` resource.

TLSRouteRule

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

Field	Value / Type	Description
`backendRefs`	`[]BackendRef`	This is a required field. Kubernetes services acting as backends and processing requests. All services from this list will be placed in the same backend group.
`backendRefs.name`	`string`	This is a required field. Name of the Kubernetes service backend. The referred `Service` resource must be described per the standard configuration.
`backendRefs.namespace`	`string`	`Service` resource namespace. By default, it matches the `TLSRoute` resource metadata.namespace value.
`backendRefs.port`	`int32`	Service port number. The port number must match one of the `Service` resource spec.ports.port values.
`backendRefs.weight`	`int32`	Backend weight. Backends in a group receive traffic in proportion to their weights. You should either specify weights for all backends in a group, or not specify them at all. If weights are not specified, traffic will be equally distributed across backends. A backend with zero or negative weight will not be receiving traffic.

TLSRoute resource fields

TLSRouteTLSRoute

ObjectMetaObjectMeta

TLSRouteSpecTLSRouteSpec

ParentReferenceParentReference

TLSRouteRuleTLSRouteRule

Was the article helpful?

TLSRoute

ObjectMeta

TLSRouteSpec

ParentReference

TLSRouteRule