Связаться с намиПодключиться

Поля ресурса Gateway

Статья создана
Обновлена 21 июля 2025 г.

В ресурсе Gateway определяются правила приема входящего трафика и выбора маршрутов (ресурсов HTTPRoute, GRPCRoute и TLSRoute) для этого трафика. По этим правилам Gateway API Application Load Balancer создает:

Gateway предназначен для оператора кластера. Разработчики приложений должны использовать TLSRoute, HTTPRoute или GRPCRoute.

Gateway — ресурс Kubernetes, определенный проектом Kubernetes Gateway API. Ниже описаны поля и аннотации ресурса, с которыми работает Gateway API Application Load Balancer. Полное описание конфигурации ресурса см. в документации Kubernetes Gateway API.

Gateway

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: <string>
  namespace: <string>
  annotations:
    gateway.alb.yc.io/security-groups: <string>
    gateway.alb.yc.io/subnets: <string>
    gateway.alb.yc.io/autoScale.minZoneSize: <string>
    gateway.alb.yc.io/autoScale.maxSize: <string>
    gateway.alb.yc.io/zone.<зона_доступности>.receiveTraffic: <bool>
    gateway.alb.yc.io/logs.logGroupId: <string>
    gateway.alb.yc.io/logs.disable: <bool>
    gateway.alb.yc.io/logs.discardRule.<имя_правила>.httpCodes: <string>
    gateway.alb.yc.io/logs.discardRule.<имя_правила>.httpCodeIntervals: <string>
    gateway.alb.yc.io/logs.discardRule.<имя_правила>.grpcCodes: <string>
    gateway.alb.yc.io/logs.discardRule.<имя_правила>.discardPercent: <string>
spec: <GatewaySpec>

Где:

  • apiVersion: gateway.networking.k8s.io/v1

  • kind: Gateway

  • metadata (ObjectMeta, обязательное)

    Метаданные ресурса.

    • name (string, обязательное)

      Имя ресурса. Подробнее о формате см. в документации Kubernetes.

      Не является именем балансировщика в Application Load Balancer.

    • namespace (string)

      Пространство имен, к которому относится ресурс. Значение по умолчанию — default.

    • annotations (map[string]string, обязательное)

      Аннотации ресурса.

      Примечание

      Вы можете определить ресурс GatewayPolicy вместо аннотаций. Набор параметров ресурса GatewayPolicy и аннотации Gateway равнозначны.

      • gateway.alb.yc.io/security-groups (string, обязательное)

        Список групп безопасности Virtual Private Cloud для балансировщика. Идентификаторы групп перечисляются через запятую, например:

        gateway.alb.yc.io/security-groups: b0c2kotoidcoh6haf8cu,e2lnhhdj9a0aqmr78d36,e9bud5itjnl8mkjj7td1

        Для корректной работы балансировщика и Gateway API группы безопасности должны быть настроены, как описано в разделе Настройка групп безопасности для инструментов Application Load Balancer для Managed Service for Kubernetes.

      • gateway.alb.yc.io/subnet-ids (string)

        Список подсетей Virtual Private Cloud в зонах доступности, где размещен балансировщик. Идентификаторы подсетей перечисляются через запятую.

      • gateway.alb.yc.io/autoScale.minZoneSize (string)

        Минимальное количество ресурсных единиц в каждой зоне доступности. По умолчанию минимум равен 2. Указать минимальное значение меньше 2 нельзя.

      • gateway.alb.yc.io/autoScale.maxSize (string)

        Максимальное суммарное количество ресурсных единиц. По умолчанию количество не ограничено. Значение должно быть не меньше, чем количество зон доступности балансировщика, умноженное на минимальное количество ресурсных единиц в каждой зоне.

      • gateway.alb.yc.io/zone.<зона_доступности>.receiveTraffic (bool)

        Значение true выключает трафик на узлы балансировщика в указанной зоне доступности.

      • gateway.alb.yc.io/logs.disable (bool)

        Значение true выключает логирование балансировщика.

      • gateway.alb.yc.io/logs.logGroupId (string)

        Идентификатор лог-группы для записи логов балансировщика в Yandex Cloud Logging.

      • gateway.alb.yc.io/logs.discardRule.<имя_правила>.httpCodes (string)

        Список HTTP-кодов. Коды перечисляются через запятую. Параметр правила отбрасывания логов. Для имени правила используйте латинские буквы, цифры и дефис.

      • gateway.alb.yc.io/logs.discardRule.<имя_правила>.httpCodeIntervals (string)

        Список классов HTTP-кодов (например, HTTP_4XX). Классы перечисляются через запятую. Параметр правила отбрасывания логов. Для имени правила используйте латинские буквы и цифры.

      • gateway.alb.yc.io/logs.discardRule.<имя_правила>.grpcCodes (string)

        Список gRPC-кодов. Коды перечисляются через запятую. Параметр правила отбрасывания логов. Для имени правила используйте латинские буквы и цифры.

      • gateway.alb.yc.io/logs.discardRule.<имя_правила>.discardPercent (string)

        Доля отбрасываемых логов в процентах. Параметр правила отбрасывания логов. Для имени правила используйте латинские буквы и цифры.

  • spec (GatewaySpec, обязательное)

    Спецификация ресурса. Подробнее см. ниже.

GatewaySpec

gatewayClassName: yc-df-class
listeners:
  - name: <string>
    hostname: <string>
    port: <int32>
    protocol: <string>
    tls:
      mode: <string>
      certificateRefs:
        - group: <string>
          kind: <string>
          name: <string>
          namespace: <string>
        - ...
    allowedRoutes:
      namespaces:
        from: <string>
        selector:
          matchExpressions:
            - key: <string>
              operator: <string>
              values:
                - <string>
                - ...
          matchLabels:
            <string>: <string>
            ...
  - ...
addresses:
  - type: IPAddress
    value: <string>
  - ...

Где:

  • gatewayClassName: yc-df-class

  • listeners ([]Listener)

    Обработчики балансировщика.

    • name (string)

      Внутреннее имя обработчика.

      Используется только для нужд Kubernetes и не является именем обработчика в Application Load Balancer.

      Имя должно иметь формат доменного, то есть соответствовать следующему регулярному выражению:

      [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*

      Например, имена example, example.com, foo.example.com подходят, а example.com/bar, -example. — нет.

      Максимальная длина имени — 63 символа.

    • hostname (string)

      Доменное имя, для которого действует обработчик.

      Чтобы указать на все возможные поддомены любых уровней, вместо первого уровня доменного имени используйте звездочку *. В этом случае значение нужно обернуть в кавычки.

      Например, значение "*.example.com" соответствует доменным именам foo.example.com, foo-bar.example.com, foo.bar.example.com, foo.bar.baz.example.com и т. п. (но не example.com).

      Заменить звездочкой только часть первого уровня доменного имени, например *foo.example.com, нельзя.

      К обработчику будут привязаны только те маршруты (ресурсы HTTPRoute, GRPCRoute и TLSRoute), доменные имена которых (поле spec.hostnames) «пересекаются» с доменным именем в этом поле.

    • port (int32)

      Порт, на котором обработчик принимает входящий трафик.

    • protocol (string)

      Протокол, по которому обработчик принимает входящий трафик: HTTP, HTTPS или TLS.

    • tls (GatewayTlsConfig)

      Настройки TLS, которые используются при работе с входящим HTTPS- или TLS-трафиком.

      • mode (string)

        Режим терминирования TLS-соединений.

        Единственное поддерживаемое значение и значение по умолчанию — Terminate: соединения терминируются с использованием сертификатов из поля certificateRefs, расшифрованный трафик отправляется на бэкенды. Режим Passthrough (соединения не терминируются) не поддерживается.

      • certificateRefs ([]SecretObjectReference)

        Список ресурсов Kubernetes, в которых хранятся TLS-сертификаты.

        Используется, только если значение поля protocol — HTTPS или TLS. В этом случае в списке должен быть хотя бы один сертификат.

        В балансировщике используется только первый сертификат из списка, остальные игнорируются.

        Можно указать сертификат Certificate Manager (ресурс YCCertificate) либо добавить сертификат в кластер в виде секрета (ресурса Secret) через консоль управления Managed Service for Kubernetes или с помощью kubectl:

        kubectl create secret tls <имя_секрета> \
  -n <имя_пространства_имен> \
  --cert <путь_к_файлу_с_сертификатом> \
  --key <путь_к_файлу_с_закрытым_ключом_сертификата>

        • group (string)

          Имя группы API Kubernetes, к которой относится ресурс с сертификатом, например networking.k8s.io.

          Значение по умолчанию — пустая строка, обозначающая корневую группу API.

        • kind (string)

          Тип ресурса Kubernetes, в котором хранится сертификат.

          Значение по умолчанию — Secret. Для сертификата Certificate Manager используется значение YCCertificate.

        • name (string)

          Имя ресурса Kubernetes, в котором хранится сертификат.

        • namespace (string)

          Пространство имен, к которому относится имя ресурса с сертификатом.

    • allowedRoutes (AllowedRoutes)

      Правила, по которым для обработчика выбираются маршруты (ресурсы HTTPRoute, GRPCRoute и TLSRoute). Чтобы маршрут был выбран, в конфигурации этих ресурсов должно быть указание на Gateway в поле spec.parentRefs.

      По этим маршрутам создаются группы бэкендов, привязываемые к обработчику. При использовании HTTPRoute или GRPCRoute также создаются HTTP-роутеры.

      • namespaces (RouteNamespaces)

        Правило выбора пространств имен, к которым относятся ресурсы HTTPRoute, GRPCRoute и TLSRoute, привязываемые к обработчику.

        • from (string)

          Тип правила:

          • All — выбираются ресурсы из всех пространств имен.
          • Same — выбираются ресурсы только из того же пространства имен, что и ресурс Gateway (поле metadata.namespace).
          • Selector — выбираются ресурсы из пространств имен, соответствующих требованиям из поля selector.

        • selector (LabelSelector)

          Селектор — набор требований к пространствам имен. Выбираются только те пространства, которые удовлетворяют всем требованиям из полей matchExpressions и matchLabels.

          Подробнее см. в справочнике API Kubernetes.

          Если значение поля from — не Selector, то поле selector игнорируется.

  • addresses ([]GatewayAddress)

    Настройки публичных IP-адресов балансировщика.

    Если поле не указано, балансировщику будет автоматически присвоен один публичный адрес.

    • type: IPAddress

    • value (string)

      Публичный IP-адрес Yandex Virtual Private Cloud, присваиваемый балансировщику.

      Перед указанием адреса в этом поле его нужно зарезервировать по инструкции.

Предыдущая
Service для Ingress
Следующая
GatewayPolicy