Yandex Cloud
Поиск
Связаться с экспертомПопробовать бесплатно
  • Кейсы
  • Документация
  • Блог
  • Все сервисы
  • Статус работы сервисов
  • Marketplace
    • Популярные
    • Инфраструктура и сеть
    • Платформа данных
    • Искусственный интеллект
    • Безопасность
    • Инструменты DevOps
    • Бессерверные вычисления
    • Управление ресурсами
  • Все решения
    • По отраслям
    • По типу задач
    • Экономика платформы
    • Безопасность
    • Техническая поддержка
    • Каталог партнёров
    • Обучение и сертификация
    • Облако для стартапов
    • Облако для крупного бизнеса
    • Центр технологий для общества
    • Облако для интеграторов
    • Поддержка IT-бизнеса
    • Облако для фрилансеров
    • Обучение и сертификация
    • Блог
    • Документация
    • Контент-программа
    • Мероприятия и вебинары
    • Контакты, чаты и сообщества
    • Идеи
    • Калькулятор цен
    • Тарифы
    • Акции и free tier
  • Кейсы
  • Документация
  • Блог
Создавайте контент и получайте гранты!Готовы написать своё руководство? Участвуйте в контент-программе и получайте гранты на работу с облачными сервисами!
Подробнее о программе
Проект Яндекса
© 2026 ООО «Яндекс.Облако»
Yandex Managed Service for Kubernetes
  • Сопоставление с другими сервисами Yandex Cloud
  • Начало работы
  • Управление доступом
  • Правила тарификации
  • Справочник Terraform
  • Метрики Monitoring
  • Аудитные логи Audit Trails
    • Обзор
      • Обзор
      • Политики Gwin
      • Установка Gwin
      • Миграция приложений с ALB Ingress-контроллера на Gwin
      • Миграция приложений с Ingress NGINX на Gwin
      • Механизм Attachment для интеграции Gwin с Application Load Balancer
        • DirectResponse
        • Gateway
        • BackendTLSPolicy
        • GatewayPolicy
        • GRPCRoute
        • HTTPRoute
        • Ingress
        • IngressBackendGroup
        • IngressPolicy
        • ListenerSetPolicy
        • RoutePolicy
        • Service
        • ListenerSet
        • ServicePolicy
        • YCCertificate
        • TLSRoute
        • YCStorageBucket
    • Настройка групп безопасности
    • Работа с сервисными аккаунтами
    • Создание и изменение ресурсов по конфигурации
  • История изменений
  • Обучающие курсы

В этой статье:

  • Cheatsheet
  • ListenerSetMeta
  • Annotations cheatsheet
  • Annotations reference
  • ListenerSetSpec
  • ParentGatewayReference
  • ListenerEntry
  • ListenerTLSConfig
  • SecretObjectReference
  • AllowedRoutes
  • RouteNamespaces
  • LabelSelector
  • LabelSelectorRequirement
  • ListenerSetStatus
  • ListenerEntryStatus
  1. Инструменты Application Load Balancer
  2. Gwin
  3. Конфигурация ресурсов (англ.)
  4. ListenerSet

ListenerSet

Статья создана
Yandex Cloud
Обновлена 3 июля 2026 г.
Открыть в Markdown
  • Cheatsheet
  • ListenerSetMeta
    • Annotations cheatsheet
    • Annotations reference
  • ListenerSetSpec
    • ParentGatewayReference
    • ListenerEntry
    • ListenerTLSConfig
    • SecretObjectReference
    • AllowedRoutes
    • RouteNamespaces
    • LabelSelector
    • LabelSelectorRequirement
  • ListenerSetStatus
    • ListenerEntryStatus

ListenerSet allows attaching additional listeners to an existing Gateway. It enables different teams or namespaces to extend a shared Gateway with their own listeners without modifying the Gateway resource itself.

ListenerSet is a Kubernetes Gateway API project resource. Below, we describe its fields used by Gwin. For configuration details, see the upstream documentation.

  • Cheatsheet
  • ListenerSetMeta
    • Annotations cheatsheet
    • Annotations reference
  • ListenerSetSpec
    • ParentGatewayReference
    • ListenerEntry
    • ListenerTLSConfig
    • SecretObjectReference
    • AllowedRoutes
    • RouteNamespaces
    • LabelSelector
    • LabelSelectorRequirement
  • ListenerSetStatus
    • ListenerEntryStatus

CheatsheetCheatsheet

Примечание

Specification provided below is not valid configuration.

It's just demonstration of all ListenerSet fields.

apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: my-listenerset
  namespace: my-ns  # ListenerSet namespace, may differ from Gateway namespace
spec:
  parentRef:
    name: my-gateway  # Gateway to attach listeners to
    namespace: gateway-ns  # omit if Gateway is in the same namespace
  listeners:
    - name: https  # listener identifier, unique within this ListenerSet
      hostname: "*.example.com"  # accept requests for this domain
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate  # decrypt TLS at load balancer
        certificateRefs:
          - group: gwin.yandex.cloud
            kind: YCCertificate  # Yandex Cloud certificate
            name: some-certificate
            namespace: some-ns
          - kind: Secret  # Kubernetes secret certificate
            name: some-secret
            namespace: some-ns
      allowedRoutes:  # which routes can use this listener
        namespaces:
          from: Selector  # select by labels (Any or Same can be used as alternative)
          selector:
            matchLabels:
              app: my-app
            matchExpressions:
              - key: app
                operator: In
                values:
                  - my-app
    - name: http
      port: 8080
      protocol: HTTP
      hostname: "service.example.com"
      allowedRoutes:
        namespaces:
          from: Same  # only routes in the same namespace as this ListenerSet
Field Description
metadata ListenerSetMeta
Name and namespace.
spec ListenerSetSpec
Resource specification.
status ListenerSetStatus
Resource status populated by the controller.

ListenerSetMetaListenerSetMeta

Field Description
name string
Name of the ListenerSet.
namespace string
Namespace of the ListenerSet. May differ from the parent Gateway's namespace.
annotations map[string]string
Annotations of the ListenerSet.

Annotations cheatsheetAnnotations cheatsheet

Примечание

You can also set policy parameters using ListenerSetPolicy resource. The ListenerSetPolicy resource parameters and ListenerSet annotations are equivalent.

Specification provided below is not valid configuration.
It's just demonstration of all ListenerSet annotations.

apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: my-listenerset
  annotations:
    # Listener configuration (applies to all listeners in this ListenerSet)
    gwin.yandex.cloud/listeners.http.protocolSettings.allowHTTP10: "true"  # support old HTTP
    gwin.yandex.cloud/listeners.http.protocolSettings.http2Options.maxConcurrentStreams: "100"  # limit connections
    gwin.yandex.cloud/listeners.stream.idleTimeout: "300s"  # stream backend idle timeout

    # Specific listener configuration
    gwin.yandex.cloud/listener.my-listener.http.protocolSettings.allowHTTP10: "true"  # per-listener HTTP setting
    gwin.yandex.cloud/listener.my-listener.stream.idleTimeout: "300s"  # per-listener timeout

    # ALB resource naming
    gwin.yandex.cloud/listener.my-listener.albListenerName: "my-alb-listener"  # custom listener name
    gwin.yandex.cloud/listener.my-listener.albHTTPRouterName: "my-http-router"  # custom HTTP router name

    # Virtual host attachment
    gwin.yandex.cloud/listener.my-listener.attach.virtualHosts.httpRouterID: "http-router-id"  # manage virtual hosts in an existing HTTP router
    ...

Annotations referenceAnnotations reference

Примечание

Any listeners annotation can be applied to a specific listener by prefixing with listener.{listener-name}.

For example: gwin.yandex.cloud/listener.my-listener.http.protocolSettings.allowHTTP10: "true".

Gateway policies are not inherited by ListenerSets. Each ListenerSet manages its own listener settings independently.

Listener configurationListener configuration

Annotation and description
gwin.yandex.cloud/listeners.http.protocolSettings.allowHTTP10
(boolean)
Enables support for incoming HTTP/1.0 and HTTP/1.1 requests and disables it for HTTP/2 requests. Applies to all HTTP listeners in this ListenerSet.
Example: true
gwin.yandex.cloud/listeners.http.protocolSettings.http2Options.maxConcurrentStreams
(number)
Maximum number of concurrent HTTP/2 streams in a connection. Applies to all HTTP listeners in this ListenerSet.
Example: 100
gwin.yandex.cloud/listeners.stream.idleTimeout
(duration)
The idle timeout is duration during which no data is transmitted or received on either the upstream or downstream connection. Applies to all stream listeners in this ListenerSet.
Example: 300s

ALB resource namingALB resource naming

Custom names for ALB resources created by the controller. By default, the controller generates names automatically.

Annotation and description
gwin.yandex.cloud/listener.{listener-name}.albListenerName
(string)
Custom name for the ALB listener associated with the specified listener.
Example: my-alb-listener
gwin.yandex.cloud/listener.{listener-name}.albHTTPRouterName
(string)
Custom name for the ALB HTTP router associated with the specified listener.
Example: my-http-router

Virtual host attachmentVirtual host attachment

Make the controller manage virtual hosts inside an existing ALB HTTP router instead of creating its own. Attachment is configured per listener and follows the parent Gateway rule: either all listeners are attached or none.

Annotation and description
gwin.yandex.cloud/listener.{listener-name}.attach.virtualHosts.httpRouterID
(string)
Cloud HTTP router ID whose virtual hosts are managed by this listener. The controller manages the full lifecycle (create, update, delete) of those virtual hosts and does not create an HTTP router of its own for this listener.
Example: http-router-id

ListenerSetSpecListenerSetSpec

ListenerSet specification.

Appears in: ListenerSet

Field Description
parentRef ParentGatewayReference
Reference to the Gateway this ListenerSet attaches to. The Gateway must explicitly allow attachment via its spec.allowedListeners field.
listeners []ListenerEntry
Listeners to add to the parent Gateway. Must contain between 1 and 64 entries. Listener names must be unique within this ListenerSet, but may overlap with listener names in the parent Gateway.

ParentGatewayReferenceParentGatewayReference

Reference to the parent Gateway.

Appears in: ListenerSetSpec

Field Description
group string
API group of the parent Gateway. Defaults to gateway.networking.k8s.io.
Example: gateway.networking.k8s.io
kind string
Kind of the parent resource. Defaults to Gateway.
Example: Gateway
name string
Name of the parent Gateway.
Example: my-gateway
namespace string
Namespace of the parent Gateway. Defaults to the ListenerSet's own namespace.
Example: gateway-ns

ListenerEntryListenerEntry

A listener to add to the parent Gateway. The fields are identical to the Gateway's Listener.

Appears in: ListenerSetSpec

Field Description
name string
Listener internal name. Unique within this ListenerSet. Does not need to be unique across the parent Gateway. The name must match [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)* and be at most 63 characters.
Example: http, example.com.
hostname string
Virtual hostname to match. Supports wildcard prefix (*.example.com). If omitted, all hostnames are matched.
Example: *.example.com
port int32
Network port to listen on (1–65535).
Example: 80, 443.
protocol string
Protocol for incoming traffic: HTTP, HTTPS, or TLS.
Example: HTTP, HTTPS, TLS.
tls ListenerTLSConfig
TLS settings. Required when protocol is HTTPS or TLS. Must not be set for HTTP.
allowedRoutes AllowedRoutes
Namespaces from which routes may attach to this listener. Defaults to Same namespace.

ListenerTLSConfigListenerTLSConfig

TLS settings for HTTPS and TLS traffic termination.

Appears in: ListenerEntry

Field Description
mode string
TLS termination mode. Only Terminate is supported (incoming traffic is decrypted using certificateRefs).
Example: Terminate
certificateRefs []SecretObjectReference
Kubernetes resources containing TLS certificates. Required when protocol is HTTPS or TLS. Must contain at least one entry.

SecretObjectReferenceSecretObjectReference

Reference to a Kubernetes resource containing a TLS certificate. Identical to the Gateway's SecretObjectReference.

You can specify a certificate from Certificate Manager (YCCertificate) or from a Secret resource. When using a cross-namespace reference, a ReferenceGrant in the target namespace is required. Note that ReferenceGrant objects applied to the parent Gateway are not inherited by the ListenerSet.

Appears in: ListenerTLSConfig

Field Description
group string
Kubernetes API group of the certificate resource. Default is empty (core API group).
Example: gwin.yandex.cloud
kind string
Kind of the certificate resource. Default is Secret. Use YCCertificate for a Yandex Cloud certificate.
Example: Secret, YCCertificate.
name string
Name of the certificate resource.
Example: some-certificate
namespace string
Namespace of the certificate resource. Defaults to the ListenerSet's namespace. Requires a ReferenceGrant when referencing a different namespace.
Example: some-ns

AllowedRoutesAllowedRoutes

Rules for selecting which routes can use this listener. Identical to Gateway's AllowedRoutes.

Appears in: ListenerEntry

Field Description
namespaces RouteNamespaces
Namespace selection rule for routes.

RouteNamespacesRouteNamespaces

Namespace selection rules for routes that may attach to this listener.

Appears in: AllowedRoutes

Field Description
from string
Selection rule: All — any namespace; Same — only the ListenerSet's own namespace; Selector — namespaces matching selector. Default is Same.
Example: All, Same, Selector.
selector LabelSelector
Namespace label selector. Used only when from is Selector.

LabelSelectorLabelSelector

Label-based selection criteria for namespaces.

Appears in: RouteNamespaces

Field Description
matchLabels map[string]string
Simple label matching requirements.
Example: app: my-app
matchExpressions []LabelSelectorRequirement
Advanced label matching expressions.

LabelSelectorRequirementLabelSelectorRequirement

Advanced label matching expression with operator and values.

Appears in: LabelSelector

Field Description
key string
Label key to match.
Example: app
operator string
Matching operator.
Example: In, NotIn, Exists.
values []string
Values to match against.
Example: ["my-app"]

ListenerSetStatusListenerSetStatus

Status populated by the controller.

Appears in: ListenerSet

Field Description
conditions []Condition
Overall ListenerSet conditions. Known types: Accepted and Programmed.
listeners []ListenerEntryStatus
Per-listener status.

ListenerEntryStatusListenerEntryStatus

Status for an individual listener in this ListenerSet.

Appears in: ListenerSetStatus

Field Description
name string
Name of the listener this status corresponds to.
supportedKinds []RouteGroupKind
Route kinds supported by this listener.
attachedRoutes int32
Number of routes with Accepted: true attached to this listener.
conditions []Condition
Listener conditions. Known types: Accepted, Programmed, ResolvedRefs, Conflicted.

Была ли статья полезна?

Предыдущая
Service
Следующая
ServicePolicy
Создавайте контент и получайте гранты!Готовы написать своё руководство? Участвуйте в контент-программе и получайте гранты на работу с облачными сервисами!
Подробнее о программе
Проект Яндекса
© 2026 ООО «Яндекс.Облако»