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 backend.
Cheatsheet
Note
Specification provided below is not valid configuration.
It's just demonstration of all IngressBackendGroup fields.
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"
header:
name: "X-Session-ID"
# 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 Backend group specification. |
| status | IngressBackendGroupStatus Backend group status. |
IngressBackendGroupSpec
IngressBackendGroupSpec defines the desired state of IngressBackendGroup.
Appears in: IngressBackendGroup
| Field | Description |
|---|---|
| type | string Type of the backend group. Enum: HTTP, GRPC, STREAM. Example: HTTP |
| sessionAffinity | SessionAffinity Session affinity configuration for the backend group For details about the concept, see documentation. |
| backends | []IngressBackend List of backends that the backend group consists of. Minimum: 1 backend required. |
IngressBackend
IngressBackend defines a backend configuration for load balancing.
Appears in: 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 Reference to the Kubernetes service. Example: {name: "my-service", port: 8080} |
| http | HTTPBackend HTTP-specific backend settings. |
| grpc | GRPCBackend gRPC-specific backend settings. |
| stream | StreamBackend TCP stream-specific backend settings. |
| balancing | LoadBalancingConfig Load balancing configuration for the backend. |
| hc | HealthCheck Health check configuration. |
| tls | BackendTLS TLS settings for backend connections. |
BackendObjectReference
Reference to a Kubernetes Service that serves as a backend.
Appears in: 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
| 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 HTTP-specific health check settings. |
| grpc | HealthcheckGRPC gRPC-specific health check settings. |
| stream | HealthcheckStream TCP stream-specific health check settings. |
| transportSettings | 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
| 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 TLS settings for health checks. Use when health checks require different TLS configuration than backend. |
HealthcheckHTTP
Appears in: 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
| Field | Description |
|---|---|
| serviceName | string Name of the gRPC service to be checked. If not specified, overall health is checked. See gRPC Health Checking Protocol Example: health.v1.HealthService |
HealthcheckStream
Appears in: 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
| 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
Reserved for future gRPC-specific settings.
StreamBackend
Appears in: 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
| Field | Description |
|---|---|
| panicThreshold | int Threshold for 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. Remaining traffic is divided equally between other zones. For details about zone-aware routing, see documentation. Example: 90 |
| strictLocality | bool Send traffic only to backends in the same availability zone. If true, localityAwareRouting is ignored. For details about strict locality, see documentation. Example: false |
| mode | string Load balancing mode. Options: ROUND_ROBIN, LEAST_REQUEST, RANDOM, RING_HASH, 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
| Field | Description |
|---|---|
| connection | SessionAffinityConnection Connection-based session affinity (by client IP). |
| cookie | SessionAffinityCookie Cookie-based session affinity. |
| header | SessionAffinityHeader HTTP header-based session affinity. |
SessionAffinityConnection
Appears in: SessionAffinity
| Field | Description |
|---|---|
| sourceIP | bool Use client IP address for session affinity. Example: true |
SessionAffinityCookie
Appears in: 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 |
SessionAffinityHeader
Appears in: SessionAffinity
| Field | Description |
|---|---|
| name | string Name of the HTTP header field used for session affinity. Example: X-Session-ID |
BackendTLS
Appears in: IngressBackend, HealthCheckTransportSettings
| Field | Description |
|---|---|
| sni | string Server Name Indication (SNI) string for TLS connections. Example: backend.example.com |
| trustedCA | BackendTLSTrustedCA Validation context for TLS connections. |
BackendTLSTrustedCA
Appears in: 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----- |
IngressBackendGroupStatus
IngressBackendGroupStatus defines the observed state of IngressBackendGroup.
Appears in: IngressBackendGroup
| Field | Description |
|---|---|
| conditions | []Condition Current state conditions of the backend group. |