Подключиться
Yandex Application Load Balancer

Поля и аннотации ресурса Ingress

Статья создана

В ресурсе Ingress определяются правила распределения входящего трафика между сервисами Kubernetes. По этим правилам Ingress-контроллер Application Load Balancer создает балансировщик с нужными обработчиками и HTTP-роутерами. Сервисы, выступающие в роли бэкендов Application Load Balancer, могут быть указаны в Ingress напрямую или в составе групп бэкендов HttpBackendGroup.

Ingress — стандартный ресурс Kubernetes. В этом справочнике описаны поля и аннотации ресурса, с которыми работает Ingress-контроллер Application Load Balancer. Полный справочник ресурса см. в документации Kubernetes.

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <string>
  annotations:
    ...
spec: <IngressSpec>

Где:

  • apiVersion: networking.k8s.io/v1

  • kind: Ingress

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

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

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

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

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

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

      Аннотации ресурса. Подробнее см. ниже.

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

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

Аннотации (metadata.annotations)

metadata:
  annotations:
    ingress.alb.yc.io/group-name: <string>
    ingress.alb.yc.io/subnets: <string>
    ingress.alb.yc.io/security-groups: <string>
    ingress.alb.yc.io/external-ipv4-address: <string>
    ingress.alb.yc.io/internal-ipv4-address: <string>
    ingress.alb.yc.io/internal-alb-subnet: <string>
    ingress.alb.yc.io/protocol: <string>
    ingress.alb.yc.io/transport-security: <string>
    ingress.alb.yc.io/prefix-rewrite: <string>
    ingress.alb.yc.io/upgrade-types: <string>
    ingress.alb.yc.io/request-timeout: <string>
    ingress.alb.yc.io/idle-timeout: <string>

Где:

  • ingress.alb.yc.io/group-name (string, обязательное)

    Имя группы ресурсов Ingress, объединяемых в один балансировщик. Подробнее о формате см. в документации Kubernetes.

    Поле обязательно, даже если для балансировщика используется один Ingress.

  • ingress.alb.yc.io/subnets (string)

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

    ingress.alb.yc.io/subnets: b0c2kotoidcoh6haf8cu,e2lnhhdj9a0aqmr78d36,e9bud5itjnl8mkjj7td1

    Поле обязательно хотя бы для одного из Ingress, объединенных в группу (аннотация ingress.alb.yc.io/group-name) для создания одного балансировщика. В балансировщике используются все подсети, указанные в соответствующих Ingress.

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

  • ingress.alb.yc.io/security-groups (string)

    Примечание

    Группы безопасности находятся на стадии Preview. Если они недоступны в вашей сети, для ресурсов будет разрешен весь входящий и исходящий трафик, и дополнительной настройки не требуется.

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

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

    В балансировщике, созданном по группе из нескольких Ingress (аннотация ingress.alb.yc.io/group-name), используются все группы безопасности, указанные в этих Ingress.

    Для корректной работы балансировщика и Ingress-контроллера группы безопасности должны быть настроены, как описано в разделе Настройка групп безопасности Ingress-контроллера Application Load Balancer.

  • ingress.alb.yc.io/external-ipv4-address (string)

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

    Чтобы использовать зарезервированный IP-адрес, укажите его в значении аннотации. Чтобы балансировщик получил IP-адрес автоматически, укажите значение auto.

    Для балансировщика должен быть настроен либо публичный, либо внутренний IP-адрес (аннотация ingress.alb.yc.io/internal-ipv4-address), но не оба одновременно.

  • ingress.alb.yc.io/internal-ipv4-address (string)

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

    IP-адрес должен относиться к подсети, указанной в аннотации ingress.alb.yc.io/internal-alb-subnet. Чтобы использовать конкретный IP-адрес из этой подсети, укажите его в значении аннотации. Чтобы балансировщик получил IP-адрес автоматически, укажите значение auto.

    Для балансировщика должен быть настроен либо внутренний, либо публичный IP-адрес (аннотация ingress.alb.yc.io/external-ipv4-address), но не оба одновременно.

  • ingress.alb.yc.io/internal-alb-subnet (string)

    Идентификатор подсети внутреннего IP-адреса балансировщика.

    Поле обязательно, если для балансировщика настроен внутренний IP-адрес (аннотация ingress.alb.yc.io/internal-ipv4-address).

  • ingress.alb.yc.io/protocol (string)

    Протокол соединений между балансировщиком и бэкендами, описанными в Ingress:

    • http — HTTP/1.1. Значение по умолчанию.
    • http2 — HTTP/2.
    • grpc — gRPC.

  • ingress.alb.yc.io/transport-security (string)

    Протокол шифрования соединений между балансировщиком и бэкендами, указанными в Ingress напрямую (без HttpBackendGroup):

    • tls — TLS без проверки сертификата.

    Если аннотация не указана, балансировщик соединяется с бэкендами без шифрования.

    Для бэкендов, входящих в состав групп, значение аннотации игнорируется. Шифрование соединений балансировщика с бэкендами из групп настраивается с помощью поля spec.backend.tls ресурса HttpBackendGroup (см. справочник ресурса).

  • ingress.alb.yc.io/prefix-rewrite (string)

    Замена для путей в URI или имен gRPC-вызовов, перечисленных в спецификации Ingress (поле rules.http.paths), при маршрутизации запросов на бэкенды.

    Замена зависит от типа пути или имени: при pathType: Exact путь или имя заменяется целиком, при pathType: Prefix заменяется только указанное начало.

    Например, чтобы при всех входящих запросах к вашему API балансировщик отправлял бэкендам запросы к конкретной версии, настройте следующую замену:

    ...
metadata:
  annotations:
    ingress.alb.yc.io/prefix-rewrite: /api/v4/
...
spec:
  rules:
    - host: <доменное имя>
      http:
        paths:
          - path: /api/
            pathType: Prefix
            ...

    В Application Load Balancer замена будет настроена во всех HTTP-роутерах, созданных по ресурсу Ingress.

  • ingress.alb.yc.io/upgrade-types (string)

    Значения HTTP-заголовка Upgrade во входящих запросах, поддерживаемые балансировщиком. Значения перечисляются через запятую.

    Например, с помощью этой аннотации можно включить поддержку протокола WebSocket:

    ingress.alb.yc.io/upgrade-types: WebSocket

    В Application Load Balancer значения Upgrade будут настроены во всех HTTP-роутерах, созданных по ресурсу Ingress.

  • ingress.alb.yc.io/request-timeout (string)

    Максимальный период, на который может быть установлено соединение между узлом балансировщика и бэкендом. По истечении этого периода балансировщик отправляет клиенту ответ 504 Gateway Timeout.

    Значение по умолчанию: 60s.

    В Application Load Balancer таймаут будет настроен во всех HTTP-роутерах, созданных по ресурсу Ingress.

  • ingress.alb.yc.io/idle-timeout (string)

    Максимальный период, в течение которого соединение между узлом балансировщика и бэкендом может простаивать без передачи данных. По истечении этого периода балансировщик отправляет клиенту ответ 504 Gateway Timeout.

    Если аннотация не указана, соединение может простаивать в течение любого периода до истечения общего таймаута (аннотация ingress.alb.yc.io/request-timeout).

    В Application Load Balancer таймаут будет настроен во всех HTTP-роутерах, созданных по ресурсу Ingress.

IngressSpec

tls:
  - hosts:
      - <string>
      - ...
    secretName: <string>
  - ...
rules:
  - host: <string>
    http:
      paths:
        - path: <string>
          pathType: <string>
          backend: <IngressBackend>
  - ...

Где:

  • tls ([]IngressTLS)

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

    Если поле указано, для балансировщика будут созданы обработчики двух видов: одни будут принимать HTTPS-трафик на порте 443, а другие — перенаправлять запросы с HTTP (порт 80) на HTTPS. При этом правила распределения трафика для тех же доменных имен, явно указанные в других Ingress, без поля tls, будут иметь приоритет над перенаправлением с HTTP на HTTPS.

    Если поле не указано, для балансировщика будут созданы только обработчики для приема HTTP-трафика на порте 80.

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

      Доменные имена, которым соответствует TLS-сертификат secretName.

      Для каждого имени как для значения TLS-расширения Server Name Indication (SNI) в балансировщике будет создан отдельный обработчик.

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

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

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

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

      Указание на TLS-сертификат из Yandex Certificate Manager в формате yc-certmgr-cert-id-<идентификатор сертификата>. Под этим именем в Managed Service for Kubernetes доступен секрет с сертификатом.

      В Certificate Manager можно выпустить сертификат от Let's Encrypt® или загрузить собственный сертификат.

      Важно

      Поле secretName поддерживает только указания на сертификаты из Certificate Manager в формате yc-certmgr-cert-id-<идентификатор сертификата>. Не указывайте в этом поле собственные секреты Kubernetes.

  • rules ([]IngressRule, обязательное)

    Список правил распределения входящего трафика по бэкендам в зависимости от доменного имени (поле host) и запрашиваемого ресурса (поле http.paths).

    В Application Load Balancer правила соответствуют виртуальным хостам HTTP-роутеров.

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

      Доменное имя (значение заголовка Host для HTTP/1.1 или псевдозаголовка :authority для HTTP/2), для которого действует правило.

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

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

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

    • http (HTTPIngressRuleValue, обязательное)

      Правило распределения входящих запросов с доменным именем, указанным в поле rules.host, в зависимости от запрашиваемого ресурса.

      • paths ([]HTTPIngressPath, обязательное)

        Список маршрутов: запрашиваемых ресурсов, для которых действует правило, и соответствующих им бэкендов.

        Порядок маршрутов в списке важен: они сверяются с входящим запросом по очереди, и первый подошедший маршрут используется в маршрутизации. Поэтому рекомендуется помещать наиболее специфичные маршруты в начало списка. Эта логика отличается от описанной в документации Kubernetes, где приоритет имеют маршруты с самыми длинными путями (поле rules.http.paths.path).

        Важно

        Если балансировщик создается по нескольким Ingress (с одинаковым значением аннотации ingress.alb.yc.io/group-name) и в них есть правила для одного доменного имени, то порядок обработки маршрутов гарантируется только внутри каждого из Ingress, но не между ними.

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

          Тип указания на запрашиваемый ресурс:

          • Exact: путь в URI запроса или имя gRPC-вызова должно совпадать со значением поля rules.http.paths.path.
          • Prefix: путь в URI запроса или имя gRPC-вызова должно начинаться со значения поля rules.http.paths.path.

          Помимо распределения трафика, от типа зависит механизм замены пути или имени вызова в запросах к бэкендам, если замена настроена с помощью аннотации ingress.alb.yc.io/prefix-rewrite.

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

          Указание на запрашиваемый ресурс:

          • Для простого HTTP — путь в URI входящего запроса (если тип — Exact) или его начало (если тип — Prefix).
          • Для gRPC (когда значение аннотации ingress.alb.yc.io/protocol — grpc) — полное имя gRPC-вызова (если тип — Exact) или его начало (если тип — Prefix). Пример: /my.custom.server.Service/Method.

          В обоих случаях значение должно начинаться с /.

        • backend (IngressBackend, обязательное)

          Указание на бэкенд или группу бэкендов, которые должны обрабатывать запросы с указанным доменным именем и путем в URI или именем gRPC-вызова. Подробнее см. ниже.

IngressBackend

service:
  name: <string>
  port:
    name: <string>
    number: <int32>
resource:
  kind: HttpBackendGroup
  name: <string>
  apiGroup: alb.yc.io

Где:

  • service (IngressServiceBackend)

    Указание на сервис Kubernetes, который должен обрабатывать запросы в качестве бэкенда.

    Ресурс Service, на который указывает это поле, должен быть описан по спецификации.

    Для элемента списка spec.rules.http.paths должен быть указан либо сервис-бэкенд, либо группа бэкендов (resource), но не оба одновременно.

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

      Имя сервиса Kubernetes.

    • port (ServiceBackendPort, обязательное)

      Порт сервиса, к которому будет обращаться Ingress.

      Поле предназначено для работы Ingress-контроллера и не соответствует ни одному из полей ресурсов Application Load Balancer.

      • name (string)

        Имя порта сервиса.

        Имя должно совпадать с одним из имен портов, указанных в полях spec.ports.name ресурса Service. Подробнее см. в спецификации ресурса.

        Для порта сервиса должно быть указано либо имя, либо номер (number), но не оба одновременно.

      • number (int32)

        Номер порта сервиса.

        Номер должен совпадать с одним из номеров портов, указанных в полях spec.ports.port ресурса Service. Подробнее см. в спецификации ресурса.

        Для порта сервиса должен быть указан либо номер, либо имя (name), но не оба одновременно.

  • resource (TypedLocalObjectReference)

    Указание на группу бэкендов, которые должны обрабатывать запросы.

    Ресурс HttpBackendGroup, на который указывает это поле, реализован Ingress-контроллером как custom resource. Он должен быть описан по спецификации.

    Для элемента списка spec.rules.http.paths должна быть указана либо группа бэкендов, либо сервис-бэкенд (service), но не оба одновременно.

    • kind: HttpBackendGroup

    • name (string)

      Имя группы бэкендов.

      Имя должно совпадать с именем, указанным в поле metadata.name ресурса HttpBackendGroup. Подробнее см. в спецификации ресурса.

    • apiGroup: alb.yc.io

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