[Yandex Cloud documentation](../../index.md) > [Yandex Application Load Balancer](../index.md) > Tools for Managed Service for Kubernetes > Gwin > Resource configuration > IngressBackendGroup
# IngressBackendGroup
IngressBackendGroup is a Gwin custom resource for configuring backend groups in Yandex Application Load Balancer. It allows you to define backend targets, health checks, load balancing settings, and session affinity for your applications. It used as [Ingress](ingress.md) backend.
* [Cheatsheet](#cheatsheet)
* [IngressBackendGroupSpec](#ingressbackendgroupspec)
* [IngressBackend](#ingressbackend)
* [BackendObjectReference](#backendobjectreference)
* [HealthCheck](#healthcheck)
* [HealthCheckTransportSettings](#healthchecktransportsettings)
* [HealthcheckHTTP](#healthcheckhttp)
* [HealthcheckGRPC](#healthcheckgrpc)
* [HealthcheckStream](#healthcheckstream)
* [HTTPBackend](#httpbackend)
* [GRPCBackend](#grpcbackend)
* [StreamBackend](#streambackend)
* [LoadBalancingConfig](#loadbalancingconfig)
* [SessionAffinity](#sessionaffinity)
* [BackendTLS](#backendtls)
* [IngressBackendGroupAttach](#ingressbackendgroupattach)
* [BackendGroupAttach](#backendgroupattach)
* [IngressBackendGroupStatus](#ingressbackendgroupstatus)
## Cheatsheet
{% note info %}
Specification provided below is not valid configuration.
It's just demonstration of all `IngressBackendGroup` fields.
{% endnote %}
```yaml
apiVersion: gwin.yandex.cloud/v1
kind: IngressBackendGroup
metadata:
name: example-backend-group
namespace: example-ns
spec:
# Type of the backend group (HTTP, GRPC or STREAM)
type: HTTP
# Session affinity configuration
sessionAffinity:
connection:
sourceIP: true
cookie:
name: "session-cookie"
ttl: "3600s"
path: "/app"
header:
name: "X-Session-ID"
# Attach to existing ALB infrastructure
attach:
backendGroup:
id: "backend-group-id-1" # existing backend group ID
dontUpdatePaths: ["name", "description"] # fields not to update
ingressClass: "yandex-cloud-ingress" # ingress class filter
# List of backends
backends:
- name: "primary-backend"
weight: 80
backendRef:
name: primary-service
port: 8080
# HTTP-specific settings
http:
useHTTP2: true
# Health check configuration with transport settings
hc:
timeout: "5s"
interval: "10s"
healthyThreshold: 2
unhealthyThreshold: 3
port: 8080
# HTTP health check
http:
host: "health.example.com"
path: "/health"
useHTTP2: false
expectedStatuses: [200, 202]
# Transport settings for health checks
transportSettings:
# Use plaintext for health checks even if backend uses TLS
plaintext: true
# Or configure TLS settings for health checks
tls:
sni: "health.example.com"
trustedCA:
id: "certificate-id"
# or bytes: "-----BEGIN CERTIFICATE-----..."
# Load balancing configuration
balancing:
panicThreshold: 50
localityAwareRouting: 90
strictLocality: false
mode: "ROUND_ROBIN"
# TLS settings for backend connections
tls:
sni: "backend.example.com"
trustedCA:
id: "backend-cert-id"
- name: "secondary-backend"
weight: 20
backendRef:
name: secondary-service
port: 9090
# gRPC-specific settings
grpc: {}
# gRPC health check
hc:
timeout: "3s"
interval: "15s"
grpc:
serviceName: "health.v1.HealthService"
# Use same transport as backend
transportSettings:
tls:
sni: "grpc.example.com"
trustedCA:
bytes: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
status:
conditions: ...
```
| Field | Description |
|-------|-------------|
| metadata | **ObjectMeta**
Standard Kubernetes metadata. |
| spec | **[IngressBackendGroupSpec](#ingressbackendgroupspec)**
Backend group specification. |
| status | **[IngressBackendGroupStatus](#ingressbackendgroupstatus)**
Backend group status. |
## IngressBackendGroupSpec
IngressBackendGroupSpec defines the desired state of IngressBackendGroup.
*Appears in*: [IngressBackendGroup](#ingressbackendgroup)
| Field | Description |
|-------|-------------|
| type | **string**
Type of the backend group. Enum: `HTTP`, `GRPC`, `STREAM`.
Example: `HTTP` |
| sessionAffinity | **[SessionAffinity](#sessionaffinity)**
Session affinity configuration for the backend group
For details about the concept, see [documentation](../concepts/backend-group.md#session-affinity). |
| backends | **[[]IngressBackend](#ingressbackend)**
List of backends that the backend group consists of. Minimum: 1 backend required. |
| attach | **[IngressBackendGroupAttach](#ingressbackendgroupattach)**
Configures backend group attachment to existing cloud resources. |
### IngressBackend
IngressBackend defines a backend configuration for load balancing.
*Appears in*: [IngressBackendGroupSpec](#ingressbackendgroupspec)
| Field | Description |
|-------|-------------|
| name | **string**
Name of the backend. Pattern: `^[a-z][-a-z0-9]{1,61}[a-z0-9]$`.
Example: `primary-backend` |
| weight | **int32**
Weight of the backend for load balancing. Default: `1`.
Example: `80` |
| backendRef | **[BackendObjectReference](#backendobjectreference)**
Reference to the Kubernetes service.
Example: `{name: "my-service", port: 8080}` |
| http | **[HTTPBackend](#httpbackend)**
HTTP-specific backend settings. |
| grpc | **[GRPCBackend](#grpcbackend)**
gRPC-specific backend settings. |
| stream | **[StreamBackend](#streambackend)**
TCP stream-specific backend settings. |
| balancing | **[LoadBalancingConfig](#loadbalancingconfig)**
Load balancing configuration for the backend. |
| hc | **[HealthCheck](#healthcheck)**
Health check configuration. |
| tls | **[BackendTLS](#backendtls)**
TLS settings for backend connections. |
### BackendObjectReference
Reference to a Kubernetes Service that serves as a backend.
*Appears in*: [IngressBackend](#ingressbackend)
| Field | Description |
|-------|-------------|
| group | **string**
API group of the backend resource. Empty string for core Kubernetes resources.
Example: `""` |
| kind | **string**
Kind of the backend resource.
Example: `Service` |
| name | **string**
Name of the backend service.
Example: `my-service` |
| namespace | **string**
Namespace of the backend service.
Example: `my-namespace` |
| port | **int32**
Port number of the backend service.
Example: `8080` |
### HealthCheck
Health check configuration allows you to monitor the health of your backend targets. The `transportSettings` field is particularly useful when your health checks need different protocol settings than your backend traffic.
*Appears in*: [IngressBackend](#ingressbackend)
| Field | Description |
|-------|-------------|
| timeout | **duration**
Health check timeout — time allowed for the target to respond.
Example: `5s` |
| interval | **duration**
Base interval between consecutive health checks.
Example: `10s` |
| healthyThreshold | **int**
Number of consecutive successful checks to mark target as healthy. Default: `0`. (1 check required)
Example: `2` |
| unhealthyThreshold | **int**
Number of consecutive failed checks to mark target as unhealthy. Default: `0`. (1 check required)
Example: `3` |
| port | **int**
Port used for health checks. If not specified, backend port is used.
Example: `8080` |
| http | **[HealthcheckHTTP](#healthcheckhttp)**
HTTP-specific health check settings. |
| grpc | **[HealthcheckGRPC](#healthcheckgrpc)**
gRPC-specific health check settings. |
| stream | **[HealthcheckStream](#healthcheckstream)**
TCP stream-specific health check settings. |
| transportSettings | **[HealthCheckTransportSettings](#healthchecktransportsettings)**
Optional transport protocol for health checks. |
### HealthCheckTransportSettings
The `transportSettings` field allows you to configure different transport protocols for health checks than what your backend uses. This is particularly useful in scenarios like:
* **Plaintext health checks for TLS backends**: your backend serves HTTPS traffic, but you want simple HTTP health checks.
* **Different TLS settings**: your health check endpoint uses different certificates or SNI than your main backend.
* **Protocol isolation**: separate health check traffic from application traffic.
*Appears in*: [HealthCheck](#healthcheck)
| Field | Description |
|-------|-------------|
| plaintext | **bool**
Use plaintext protocol for health checks. Set to `true` to force HTTP health checks even for HTTPS backends.
Example: `true` |
| tls | **[BackendTLS](#backendtls)**
TLS settings for health checks. Use when health checks require different TLS configuration than backend. |
### HealthcheckHTTP
*Appears in*: [HealthCheck](#healthcheck)
| Field | Description |
|-------|-------------|
| host | **string**
Value for the HTTP/1.1 `Host` header or HTTP/2 `:authority` pseudo-header.
Example: `health.example.com` |
| path | **string**
HTTP path used in requests to targets.
Example: `/health` |
| useHTTP2 | **bool**
Enables HTTP/2 usage in health checks. Default: `false`.
Example: `true` |
| expectedStatuses | **[]int**
List of HTTP response statuses considered healthy. Default: `[200]`.
Example: `[200, 202, 204]` |
### HealthcheckGRPC
*Appears in*: [HealthCheck](#healthcheck)
| Field | Description |
|-------|-------------|
| serviceName | **string**
Name of the gRPC service to be checked. If not specified, overall health is checked. See [gRPC Health Checking Protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
Example: `health.v1.HealthService` |
### HealthcheckStream
*Appears in*: [HealthCheck](#healthcheck)
| Field | Description |
|-------|-------------|
| send | **string**
Message sent to targets during TCP data transfer. If not specified, no data is sent
Example: `PING` |
| receive | **string**
Data that must be contained in received messages for successful health check. If not specified, no messages are expected
Example: `PONG` |
### HTTPBackend
*Appears in*: [IngressBackend](#ingressbackend)
| Field | Description |
|-------|-------------|
| useHTTP2 | **bool**
Enables HTTP/2 usage in connections between load balancer nodes and backend targets. Default: `false` (HTTP/1.1 is used).
Example: `true` |
### GRPCBackend
*Appears in*: [IngressBackend](#ingressbackend)
Reserved for future gRPC-specific settings.
### StreamBackend
*Appears in*: [IngressBackend](#ingressbackend)
| Field | Description |
|-------|-------------|
| enableProxy | **bool**
If set, proxy protocol will be enabled for this backend.
Example: `true` |
| keepConnectionsOnHostHealthFailure | **bool**
If a backend host becomes unhealthy, keep connections to the failed host.
Example: `false` |
### LoadBalancingConfig
*Appears in*: [IngressBackend](#ingressbackend)
| Field | Description |
|-------|-------------|
| panicThreshold | **int**
Threshold for [panic mode](../concepts/backend-group.md#panic-mode) (percentage). If healthy backends drop below this threshold, traffic routes to all backends. Set to `0` to disable panic mode.
Example: `50` |
| localityAwareRouting | **int**
Percentage of traffic sent to backends in the same [availability zone](../../overview/concepts/geo-scope.md). Remaining traffic is divided equally between other zones. For details about zone-aware routing, see [documentation](../concepts/backend-group.md#locality).
Example: `90` |
| strictLocality | **bool**
Send traffic only to backends in the same [availability zone](../../overview/concepts/geo-scope.md). If `true`, `localityAwareRouting` is ignored. For details about strict locality, see [documentation](../concepts/backend-group.md#locality).
Example: `false` |
| mode | **string**
[Load balancing mode](../concepts/backend-group.md#balancing-mode). Options: `ROUND_ROBIN`, `LEAST_REQUEST`, `RANDOM`, `MAGLEV_HASH`.
Example: `ROUND_ROBIN` |
### SessionAffinity
Session affinity ensures that requests from the same client are routed to the same backend. For session affinity to work properly:
* Backend group should contain exactly one active backend with positive weight.
* Load balancing mode should be `MAGLEV_HASH`.
*Appears in*: [IngressBackendGroupSpec](#ingressbackendgroupspec)
| Field | Description |
|-------|-------------|
| connection | **[SessionAffinityConnection](#sessionaffinityconnection)**
Connection-based session affinity (by client IP). |
| cookie | **[SessionAffinityCookie](#sessionaffinitycookie)**
Cookie-based session affinity. |
| header | **[SessionAffinityHeader](#sessionaffinityheader)**
HTTP header-based session affinity. |
#### SessionAffinityConnection
*Appears in*: [SessionAffinity](#sessionaffinity)
| Field | Description |
|-------|-------------|
| sourceIP | **bool**
Use client IP address for session affinity.
Example: `true` |
#### SessionAffinityCookie
*Appears in*: [SessionAffinity](#sessionaffinity)
| Field | Description |
|-------|-------------|
| name | **string**
Name of the cookie used for session affinity.
Example: `session-cookie` |
| ttl | **duration**
Maximum age of generated session cookies. Set to `0` for session cookies (deleted on client restart). If not set, balancer only uses incoming cookies.
Example: `3600s` |
| path | **string**
Path attribute for the generated cookie. Used to set the path when a new cookie is generated. If unspecified or empty, no path is set for the cookie.
Example: `/app` |
#### SessionAffinityHeader
*Appears in*: [SessionAffinity](#sessionaffinity)
| Field | Description |
|-------|-------------|
| name | **string**
Name of the HTTP header field used for session affinity.
Example: `X-Session-ID` |
### BackendTLS
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), provide an empty `tls: {}` section.
Health check TLS settings work the same way, but are configured separately.
*Appears in*: [IngressBackend](#ingressbackend), [HealthCheckTransportSettings](#healthchecktransportsettings)
| Field | Description |
|-------|-------------|
| sni | **string**
Server Name Indication (SNI) string for TLS connections.
Example: `backend.example.com` |
| trustedCA | **[BackendTLSTrustedCA](#backendtlstrustedca)**
Validation context for TLS connections. |
#### BackendTLSTrustedCA
*Appears in*: [BackendTLS](#backendtls)
| Field | Description |
|-------|-------------|
| id | **string**
Cloud certificate ID.
Example: `fpq6gvvm6piu********` |
| bytes | **string**
X.509 certificate contents in PEM format.
Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----` |
## IngressBackendGroupAttach
IngressBackendGroupAttach configures ingress backend group attachment to existing cloud resources.
*Appears in*: [IngressBackendGroupSpec](#ingressbackendgroupspec)
| Field | Description |
|-------|-------------|
| ingressClass | **string**
Specifies the ingress class that should manage this backend group. If specified and the corresponding ingressClass is not managed by the controller, the backend group is ignored. This is useful for advanced scenarios where multiple controllers might be present.
Example: `yandex-cloud-ingress` |
| backendGroup | **[BackendGroupAttach](#backendgroupattach)**
Configures attachment to an existing cloud backend group. |
## BackendGroupAttach
BackendGroupAttach configures attachment to an existing cloud backend group.
*Appears in*: [IngressBackendGroupAttach](#ingressbackendgroupattach)
| Field | Description |
|-------|-------------|
| id | **string**
Cloud backend group ID that should be managed by this ingress backend group. The controller will attach to this existing backend group instead of creating a new one.
Example: `backend-group-id-1` |
| dontUpdatePaths | **[]string**
Specifies which fields should NOT be updated by the controller. Default is "name" - the controller doesn't touch the group name.
Example: `["name", "description"]` |
## IngressBackendGroupStatus
IngressBackendGroupStatus defines the observed state of IngressBackendGroup.
*Appears in*: [IngressBackendGroup](#ingressbackendgroup)
| Field | Description |
|-------|-------------|
| conditions | **[]Condition**
Current state conditions of the backend group. |