[Документация Yandex Cloud](../../index.md) > [Yandex Managed Service for Kubernetes](../index.md) > Инструменты Application Load Balancer > Gwin > Конфигурация ресурсов (англ.) > TLSRoute
# TLSRoute
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](httproute.md) and [GRPCRoute](grpcroute.md) which use URLs, headers and more.
TLSRoute is a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) project resource. Below, we describe its fields and annotations used by Gwin. For configuration details, see the [upstream documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute).
TLSRoute resources must be attached to [Gateway](gateway.md) resources to function properly.
* [Cheatsheet](#cheatsheet)
* [TLSRouteMeta](#tlsroutemeta)
* [Annotations cheatsheet](#annotations-cheatsheet)
* [Annotations reference](#annotations-reference)
* [TLSRouteSpec](#tlsroutespec)
* [ParentReference](#parentreference)
* [TLSRouteRule](#tlsrouterule)
* [BackendRef](#backendref)
## Cheatsheet
{% note info %}
Specification provided below is not valid configuration.
It's just demonstration of all `TLSRoute` fields.
{% endnote %}
```yaml
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](#tlsroutemeta)**
Name, namespace and annotations. |
| spec | **[TLSRouteSpec](#tlsroutespec)**
Resource specification. |
## TLSRouteMeta
*Appears in:* [TLSRoute](#cheatsheet)
| 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 info %}
You can also set policy parameters using [RoutePolicy](routepolicy.md) resource. The RoutePolicy resource parameters and TLSRoute annotations are equivalent.
{% endnote %}
Specification provided below is not valid configuration.It's just demonstration of all `TLSRoute` annotations.
```yaml
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.cookie.path: "/app" # cookie path attribute
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`, `MAGLEV_HASH`.
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
TLS settings for backend connections. \
Use when the load balancer must connect to its targets over TLS. \
If you only need “TLS as is” (no SNI and no backend certificate verification), set `gwin.yandex.cloud/rules.backends.tls.sni: ""`. \
Health check TLS settings work the same way, but are configured separately.
| 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.cookie.path`
_(string)_
Path attribute for the generated session cookie. If unspecified or empty, no path is set for the cookie.
Example: `/app` |
| `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](#cheatsheet)
| Field | Description |
|-------|-------------|
| parentRefs | **[[]ParentReference](#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](#tlsrouterule)**
Rules for routing TLS requests. |
### ParentReference
Reference to a Gateway resource that this route should attach to.
*Appears in:* [TLSRouteSpec](#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](#tlsroutespec)
| Field | Description |
|-------|-------------|
| name | **string**
Name of the route rule. Must be unique within a Route if set.
Example: `tls-rule` |
| backendRefs | **[[]BackendRef](#backendref)**
Backend services to route requests to. |
### BackendRef
BackendRef defines how a TLSRoute forwards a TLS request.
*Appears in:* [TLSRouteRule](#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` |