TLSRoute
Written by
Updated at September 24, 2025
TLSRoute provides a way to route TLS requests. This includes the capability to match requests by hostname and route them to backend services. TLSRoute is used for TCP traffic that is encrypted with TLS.
TLSRoute use only hosts with SNI matches to route traffic. Unlike HTTPRoute and GRPCRoute which use URLs, headers and more.
TLSRoute is a Kubernetes Gateway API project resource. Below, we describe its fields and annotations used by Gwin. For configuration details, see the upstream documentation.
TLSRoute resources must be attached to Gateway resources to function properly.
Cheatsheet
Note
Specification provided below is not valid configuration.
It's just demonstration of all TLSRoute fields.
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
name: example-tls-route
namespace: example-ns
annotations: ... # see annotations example below
spec:
parentRefs: # attach to Gateway resources
- group: gateway.networking.k8s.io
kind: Gateway
namespace: gateway-ns
name: example-gateway
sectionName: tls-listener # specific listener name
hostnames: # domains this route handles
- "secure.example.com" # TLS service domain
- "api.example.com" # API domain
rules:
- name: tls-rule # rule identifier
backendRefs: # where to route requests
- group: "" # core Kubernetes API
kind: Service # Kubernetes service
name: tls-service
namespace: tls-ns
port: 8443
weight: 80 # 80% of traffic
| Field | Description |
|---|---|
| metadata | TLSRouteMeta Name, namespace and annotations. |
| spec | TLSRouteSpec Resource specification. |
TLSRouteMeta
Appears in: TLSRoute
| Field | Description |
|---|---|
| name | string Name of the TLSRoute. |
| namespace | string Namespace of the TLSRoute. |
| annotations | map[string]string Annotations of the TLSRoute. |
Annotations cheatsheet
Note
You can also set policy parameters using RoutePolicy resource. The RoutePolicy resource parameters and TLSRoute annotations are equivalent.
Specification provided below is not valid configuration.It's just demonstration of all TLSRoute annotations.
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
annotations:
# Backend group configuration
gwin.yandex.cloud/rules.backends.balancing.mode: "ROUND_ROBIN" # load balancing algorithm
gwin.yandex.cloud/rules.backends.balancing.localityAwareRouting: "80" # prefer same zone
gwin.yandex.cloud/rules.backends.balancing.strictLocality: "false" # allow cross-zone routing
gwin.yandex.cloud/rules.backends.balancing.panicThreshold: "50" # panic mode threshold
# Health checks
gwin.yandex.cloud/rules.backends.hc.timeout: "5s" # health check timeout
gwin.yandex.cloud/rules.backends.hc.interval: "10s" # check interval
gwin.yandex.cloud/rules.backends.hc.healthyThreshold: "2" # checks to mark healthy
gwin.yandex.cloud/rules.backends.hc.unhealthyThreshold: "3" # checks to mark unhealthy
gwin.yandex.cloud/rules.backends.hc.port: "8443" # health check port
gwin.yandex.cloud/rules.backends.hc.stream.send: "PING" # TCP check data to send
gwin.yandex.cloud/rules.backends.hc.stream.receive: "PONG" # expected TCP response
# Health check transport settings
gwin.yandex.cloud/rules.backends.hc.transportSettings.plaintext: "true" # use plaintext for health checks
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.sni: "health.example.com" # SNI for health check TLS
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.id: "health-cert-123" # health check TLS cert ID
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.bytes: "-----BEGIN CERTIFICATE-----..." # health check TLS cert PEM
# Backend TLS configuration
gwin.yandex.cloud/rules.backends.tls.sni: "backend.example.com" # SNI for TLS
gwin.yandex.cloud/rules.backends.tls.trustedCA.id: "cert-123456" # cloud certificate ID
gwin.yandex.cloud/rules.backends.tls.trustedCA.bytes: "-----BEGIN CERTIFICATE-----..." # PEM certificate
# Stream backend configuration
gwin.yandex.cloud/rules.backends.stream.enableProxy: "true" # enable proxy protocol
gwin.yandex.cloud/rules.backends.stream.keepConnectionsOnHostHealthFailure: "false" # drop failed connections
# Session affinity
gwin.yandex.cloud/rules.sessionAffinity.header.name: "X-Session-ID" # header-based affinity
gwin.yandex.cloud/rules.sessionAffinity.cookie.name: "session" # cookie name
gwin.yandex.cloud/rules.sessionAffinity.cookie.ttl: "3600s" # cookie lifetime
gwin.yandex.cloud/rules.sessionAffinity.sourceIP: "true" # IP-based affinity
Annotations reference
Backend group configuration
| Annotation and description |
|---|
gwin.yandex.cloud/rules.backends.balancing.mode (string) Load balancing mode for backend group. Possible values: RANDOM, ROUND_ROBIN, LEAST_REQUEST. Example: ROUND_ROBIN |
gwin.yandex.cloud/rules.backends.balancing.localityAwareRouting (number) Percentage of traffic sent to backends in the same availability zone. Example: 80 |
gwin.yandex.cloud/rules.backends.balancing.strictLocality (boolean) Route traffic only to backends in the same availability zone. Example: false |
gwin.yandex.cloud/rules.backends.balancing.panicThreshold (number) Panic mode threshold percentage for load balancing. Example: 50 |
Health check configuration
Common health check settings
| Annotation and description |
|---|
gwin.yandex.cloud/rules.backends.hc.timeout (duration) Health check timeout. Example: 5s |
gwin.yandex.cloud/rules.backends.hc.interval (duration) Interval between health checks. Example: 10s |
gwin.yandex.cloud/rules.backends.hc.healthyThreshold (number) Number of successful checks to mark backend as healthy. Example: 2 |
gwin.yandex.cloud/rules.backends.hc.unhealthyThreshold (number) Number of failed checks to mark backend as unhealthy. Example: 3 |
gwin.yandex.cloud/rules.backends.hc.port (number) Port for health checks. Example: 8443 |
Stream health checks
| Annotation and description |
|---|
gwin.yandex.cloud/rules.backends.hc.stream.send (string) Data to send for TCP health checks. Example: PING |
gwin.yandex.cloud/rules.backends.hc.stream.receive (string) Expected response for TCP health checks. Example: PONG |
Health check transport settings
| Annotation and description |
|---|
gwin.yandex.cloud/rules.backends.hc.transportSettings.plaintext (boolean) Use plaintext protocol for health checks. Set to true to force HTTP health checks even for HTTPS backends. Example: true |
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.sni (string) Server Name Indication (SNI) for health check TLS connections. Example: health.example.com |
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.id (string) Cloud certificate ID for health check TLS validation. Example: health-cert-123 |
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.bytes (string) X.509 certificate contents in PEM format for health check TLS validation. Example: -----BEGIN CERTIFICATE-----... |
Backend TLS configuration
| Annotation and description |
|---|
gwin.yandex.cloud/rules.backends.tls.sni (string) Server Name Indication (SNI) for TLS connections to backends. Example: backend.example.com |
gwin.yandex.cloud/rules.backends.tls.trustedCA.id (string) Cloud certificate ID for backend TLS validation. Example: cert-123456 |
gwin.yandex.cloud/rules.backends.tls.trustedCA.bytes (string) X.509 certificate contents in PEM format for backend TLS validation. Example: -----BEGIN CERTIFICATE-----... |
Stream backend configuration
| Annotation and description |
|---|
gwin.yandex.cloud/rules.backends.stream.enableProxy (boolean) Enable proxy protocol for stream backends. Example: true |
gwin.yandex.cloud/rules.backends.stream.keepConnectionsOnHostHealthFailure (boolean) Keep connections when backend host becomes unhealthy. Example: false |
Session affinity
| Annotation and description |
|---|
gwin.yandex.cloud/rules.sessionAffinity.header.name (string) HTTP header name for session affinity. Example: X-Session-ID |
gwin.yandex.cloud/rules.sessionAffinity.cookie.name (string) Cookie name for session affinity. Example: session |
gwin.yandex.cloud/rules.sessionAffinity.cookie.ttl (duration) Cookie TTL for session affinity. Example: 3600s |
gwin.yandex.cloud/rules.sessionAffinity.sourceIP (boolean) Use source IP for session affinity. Example: true |
TLSRouteSpec
TLSRoute specification defines the desired state of TLSRoute.
Appears in: TLSRoute
| Field | Description |
|---|---|
| parentRefs | []ParentReference References to Gateway resources that this TLSRoute should attach to. |
| hostnames | []string Hostnames that should match against the TLS Server Name Indication (SNI). |
| rules | []TLSRouteRule Rules for routing TLS requests. |
ParentReference
Reference to a Gateway resource that this route should attach to.
Appears in: TLSRouteSpec
| Field | Description |
|---|---|
| group | string API group of the parent resource. Example: gateway.networking.k8s.io |
| kind | string Kind of the parent resource. Example: Gateway |
| namespace | string Namespace of the parent resource. Example: gateway-ns |
| name | string Name of the parent resource. Example: example-gateway |
| sectionName | string Name of the specific listener to attach to. Example: tls-listener |
| port | int32 Port number of the listener to attach to. Example: 443 |
TLSRouteRule
TLSRouteRule defines semantics for forwarding TLS requests to backend services.
Appears in: TLSRouteSpec
| Field | Description |
|---|---|
| name | string Name of the route rule. Must be unique within a Route if set. Example: tls-rule |
| backendRefs | []BackendRef Backend services to route requests to. |
BackendRef
BackendRef defines how a TLSRoute forwards a TLS request.
Appears in: TLSRouteRule
| Field | Description |
|---|---|
| group | string API group of the backend resource. Example: "", gwin.yandex.cloud. |
| kind | string Kind of the backend resource. Example: Service |
| name | string Name of the backend resource. Example: tls-service |
| namespace | string Namespace of the backend resource. Example: tls-ns |
| port | int32 Port of the backend service (for Service kind only). Example: 8443 |
| weight | int32 Weight for traffic distribution between backends. Example: 80 |