Связаться с намиПодключиться

TLSRoute

Статья создана
Обновлена 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

Примечание

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

Примечание

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
Предыдущая
ServicePolicy
Следующая
YCCertificate