Yandex Cloud
Search
Contact UsGet started
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • AI for business
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Center for Technologies and Society
    • Yandex Cloud Partner program
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
© 2025 Direct Cursus Technology L.L.C.
Yandex Managed Service for Kubernetes
  • Comparing with other Yandex Cloud services
  • Getting started
  • Access management
  • Pricing policy
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
    • Overview
      • Overview
      • Gwin policies
      • Installing Gwin
      • Migrating apps from an ALB ingress controller to Gwin
        • Gateway
        • GatewayPolicy
        • GRPCRoute
        • HTTPRoute
        • Ingress
        • IngressBackendGroup
        • IngressPolicy
        • RoutePolicy
        • Service
        • ServicePolicy
        • TLSRoute
        • YCCertificate
        • YCStorageBucket
  • Release notes

In this article:

  • Cheatsheet
  • IngressBackendGroupSpec
  • IngressBackend
  • BackendObjectReference
  • HealthCheck
  • HealthCheckTransportSettings
  • HealthcheckHTTP
  • HealthcheckGRPC
  • HealthcheckStream
  • HTTPBackend
  • GRPCBackend
  • StreamBackend
  • LoadBalancingConfig
  • SessionAffinity
  • BackendTLS
  • IngressBackendGroupStatus
  1. Application Load Balancer tools
  2. Gwin
  3. Resource configuration
  4. IngressBackendGroup

IngressBackendGroup

Written by
Yandex Cloud
Updated at September 24, 2025
  • Cheatsheet
  • IngressBackendGroupSpec
    • IngressBackend
    • BackendObjectReference
    • HealthCheck
    • HealthCheckTransportSettings
    • HealthcheckHTTP
    • HealthcheckGRPC
    • HealthcheckStream
    • HTTPBackend
    • GRPCBackend
    • StreamBackend
    • LoadBalancingConfig
    • SessionAffinity
    • BackendTLS
  • IngressBackendGroupStatus

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
  • IngressBackendGroupSpec
    • IngressBackend
    • BackendObjectReference
    • HealthCheck
    • HealthCheckTransportSettings
    • HealthcheckHTTP
    • HealthcheckGRPC
    • HealthcheckStream
    • HTTPBackend
    • GRPCBackend
    • StreamBackend
    • LoadBalancingConfig
    • SessionAffinity
    • BackendTLS
  • IngressBackendGroupStatus

CheatsheetCheatsheet

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.

IngressBackendGroupSpecIngressBackendGroupSpec

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.

IngressBackendIngressBackend

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.

BackendObjectReferenceBackendObjectReference

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

HealthCheckHealthCheck

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.

HealthCheckTransportSettingsHealthCheckTransportSettings

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.

HealthcheckHTTPHealthcheckHTTP

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]

HealthcheckGRPCHealthcheckGRPC

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

HealthcheckStreamHealthcheckStream

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

HTTPBackendHTTPBackend

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

GRPCBackendGRPCBackend

Appears in: IngressBackend

Reserved for future gRPC-specific settings.

StreamBackendStreamBackend

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

LoadBalancingConfigLoadBalancingConfig

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

SessionAffinitySessionAffinity

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.

SessionAffinityConnectionSessionAffinityConnection

Appears in: SessionAffinity

Field Description
sourceIP bool
Use client IP address for session affinity.
Example: true

SessionAffinityCookieSessionAffinityCookie

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

SessionAffinityHeaderSessionAffinityHeader

Appears in: SessionAffinity

Field Description
name string
Name of the HTTP header field used for session affinity.
Example: X-Session-ID

BackendTLSBackendTLS

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.

BackendTLSTrustedCABackendTLSTrustedCA

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-----

IngressBackendGroupStatusIngressBackendGroupStatus

IngressBackendGroupStatus defines the observed state of IngressBackendGroup.

Appears in: IngressBackendGroup

Field Description
conditions []Condition
Current state conditions of the backend group.

Was the article helpful?

Previous
Ingress
Next
IngressPolicy
© 2025 Direct Cursus Technology L.L.C.