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

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

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

IngressIngress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata: <ObjectMeta>
spec: <IngressSpec>

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: alb-demo-tls
  annotations:
    ingress.alb.yc.io/subnets: <список_идентификаторов_подсетей>
    ingress.alb.yc.io/security-groups: <список_идентификаторов_групп_безопасности>
    ingress.alb.yc.io/external-ipv4-address: <auto_или_статический_IP-адрес>
    ingress.alb.yc.io/group-name: my-ingress-group
spec:
  tls:
    - hosts:
        - <доменное_имя>
      secretName: yc-certmgr-cert-id-<идентификатор_TLS-сертификата>
  rules:
    - host: <доменное_имя>
      http:
        paths:
          - path: /app1
            pathType: Prefix
            backend:
              service:
                name: alb-demo-1
                port:
                  number: 80
          - path: /app2
            pathType: Prefix
            backend:
              service:
                name: alb-demo-2
                port:
                  number: 80
          - pathType: Prefix
            path: "/"
            backend:
              service:
                name: alb-demo-2
                port:
                  name: http

ObjectMetaObjectMeta

name: <string>
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/group-settings-name: <string>
  ingress.alb.yc.io/group-order: <string>
  ingress.alb.yc.io/transport-security: <string> # Только до версии 0.2.0 невключительно.
  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/modify-header-response-append: <string>
  ingress.alb.yc.io/modify-header-response-replace: <string>
  ingress.alb.yc.io/modify-header-response-rename: <string>
  ingress.alb.yc.io/modify-header-response-remove: <string>
  ingress.alb.yc.io/modify-header-request-append: <string>
  ingress.alb.yc.io/modify-header-request-replace: <string>
  ingress.alb.yc.io/modify-header-request-rename: <string>
  ingress.alb.yc.io/modify-header-request-remove: <string>
  ingress.alb.yc.io/security-profile-id: <string>
  ingress.alb.yc.io/use-regex: <string>
  ingress.alb.yc.io/balancing-panic-threshold: <string>
  ingress.alb.yc.io/balancing-locality-aware-routing: <string>
  ingress.alb.yc.io/autoscale-max-size: <string>
  ingress.alb.yc.io/autoscale-min-zone-size: <string>
  ingress.alb.yc.io/session-affinity-header: <string>
  ingress.alb.yc.io/session-affinity-cookie: <string>
  ingress.alb.yc.io/session-affinity-connection: <string>

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

Аннотации — это коллекция пар ключ:значение, которые используются для присвоения метаданных объекту. Значения аннотаций всегда имеют тип данных string.

Значением аннотации могут быть несколько пар <ключ>=<значение>, перечисленные через запятую:

аннотация: <ключ>=<значение>,<ключ>=<значение>,<ключ>=<значение>

При этом одному ключу может соответствовать несколько значений. Например, чтобы добавить заголовок ответа X-Robots со значением noarchive,nofollow,noindex, запишите аннотацию так:

ingress.alb.yc.io/modify-header-response-replace: X-Robots-Tag=noarchive,X-Robots-Tag=nofollow,X-Robots-Tag=noindex

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

Для объекта ObjectMeta можно передать следующие аннотации:

• ingress.alb.yc.io/group-name

  Имя группы ресурсов Ingress. Для каждой группы создается отдельный балансировщик. Несколько ресурсов Ingress можно объединить в одну группу, чтобы не создавать балансировщик для каждого отдельного ресурса Ingress. Подробнее о формате см. в документации Kubernetes.

  Поле обязательно, даже если ресурс Ingress — единственный в группе.

• ingress.alb.yc.io/subnets

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

  ingress.alb.yc.io/subnets: b0c2kotoidco********,e2lnhhdj9a0a********,e9bud5itjnl8********
  

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

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

• ingress.alb.yc.io/security-groups

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

  ingress.alb.yc.io/security-groups: b0c2kotoidco********,e2lnhhdj9a0a********,e9bud5itjnl8********
  

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

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

• ingress.alb.yc.io/external-ipv4-address

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

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

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

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

• ingress.alb.yc.io/internal-ipv4-address

  Настройка внутреннего 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

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

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

• ingress.alb.yc.io/protocol

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

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

• ingress.alb.yc.io/group-settings-name

  Имя для настроек группы ресурсов Ingress.

  Чтобы задать настройки, создайте дополнительный ресурс IngressGroupSettings.

• ingress.alb.yc.io/group-order

  Порядковый номер ресурса Ingress. Если для нескольких ресурсов в группе ресурсов Ingress указать порядковые номера, будет задана последовательность добавления маршрутов для внутреннего трафика. Ресурсы Ingress сортируются по неубыванию.

  Аннотация не применяется к маршрутам, заданным одним ресурсом Ingress.

  В значении аннотации укажите целое число. Значение по умолчанию — 0.

• ingress.alb.yc.io/transport-security

  Важно

  В ALB Ingress Controller версии 0.2.0 и позднее используйте аннотацию только в объекте Service.

  Если указать аннотацию в ресурсах Ingress, где используется один сервис с одинаковыми настройками для групп бэкендов, аннотация применится корректно. Но такой механизм устарел, в дальнейшем он не будет поддерживаться.

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

  Допустимое значение: tls — TLS без проверки сертификата.

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

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

• ingress.alb.yc.io/prefix-rewrite

  Замена для путей в 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

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

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

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

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

• ingress.alb.yc.io/request-timeout

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

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

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

• ingress.alb.yc.io/idle-timeout

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

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

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

• ingress.alb.yc.io/modify-header-response-append

  Добавляет строку к значению заголовка ответа. Заголовок и строка указываются в формате:

  ingress.alb.yc.io/modify-header-response-append: <ключ>=<значение>
  

  Где:

  • <ключ> — имя изменяемого заголовка.
  • <значение> — строка, которая будет добавлена к значению заголовка.

• ingress.alb.yc.io/modify-header-response-replace

  Заменяет значение заголовка ответа. Заголовок и его новое значение указываются в формате:

  ingress.alb.yc.io/modify-header-response-replace: <ключ>=<значение>
  

  Где:

  • <ключ> — имя изменяемого заголовка.
  • <значение> — новое значение заголовка.

• ingress.alb.yc.io/modify-header-response-rename

  Переименовывает заголовок ответа. Заголовок и его новое имя указываются в формате:

  ingress.alb.yc.io/modify-header-response-rename: <ключ>=<значение>
  

  Где:

  • <ключ> — имя изменяемого заголовка.
  • <значение> — новое имя заголовка.

• ingress.alb.yc.io/modify-header-response-remove

  Удаляет заголовок ответа. Заголовок для удаления указывается в формате:

  ingress.alb.yc.io/modify-header-response-remove: <ключ>=true
  

  Где <ключ> — имя удаляемого заголовка.

• ingress.alb.yc.io/modify-header-request-append

  Добавляет строку к значению заголовка запроса. Заголовок и строка указываются в формате:

  ingress.alb.yc.io/modify-header-request-append: <ключ>=<значение>
  

  Где:

  • <ключ> — имя изменяемого заголовка.
  • <значение> — строка, которая будет добавлена к значению заголовка.

• ingress.alb.yc.io/modify-header-request-replace

  Заменяет значение заголовка запроса. Заголовок и его новое значение указываются в формате:

  ingress.alb.yc.io/modify-header-request-replace: <ключ>=<значение>
  

  Где:

  • <ключ> — имя изменяемого заголовка.
  • <значение> — новое значение заголовка.

• ingress.alb.yc.io/modify-header-request-rename

  Переименовывает заголовок запроса. Заголовок и его новое имя указываются в формате:

  ingress.alb.yc.io/modify-header-request-rename: <ключ>=<значение>
  

  Где:

  • <ключ> — имя изменяемого заголовка.
  • <значение> — новое имя заголовка.

• ingress.alb.yc.io/modify-header-request-remove

  Удаляет заголовок запроса. Заголовок для удаления указывается в формате:

  ingress.alb.yc.io/modify-header-request-remove: <ключ>=true
  

  Где <ключ> — имя удаляемого заголовка.

• ingress.alb.yc.io/security-profile-id

  Включает поддержку сервиса Yandex Smart Web Security, который позволяет защититься от DDoS-атак и ботов, а также задействовать WAF и ограничить нагрузку на защищаемый ресурс.

  Примечание

  Для подключения профиля безопасности к виртуальному хосту Application Load Balancer у сервисного аккаунта, от имени которого работает Ingress-контроллер, должна быть роль smart-web-security.editor на каталог, в котором размещены ресурсы Application Load Balancer и Smart Web Security. Подробнее см. Назначение роли сервисному аккаунту.

  Сервис проверяет HTTP-запросы, которые поступают к защищаемому ресурсу через виртуальный хост L7-балансировщика. В зависимости от результатов проверки сервис направляет запросы на защищаемый ресурс, блокирует их или отправляет в Yandex SmartCaptcha для дополнительной верификации.

  Чтобы включить поддержку сервиса, в аннотации Ingress укажите идентификатор профиля безопасности Smart Web Security:

  ingress.alb.yc.io/security-profile-id: <идентификатор_профиля_безопасности>
  

  Профиль содержит список условий проверки и действий, которые применяются к приходящим HTTP-запросам по результатам проверки.

  Если у вас нет профиля безопасности, создайте его.

• ingress.alb.yc.io/use-regex

  Включает поддержку регулярных выражений стандарта RE2 при сопоставлении пути запроса, если передана строка true. Применимо только если для параметра pathType указано значение Exact.

• ingress.alb.yc.io/balancing-panic-threshold

  Задает пороговое значения для активации режима паники. Режим включится, если процент работоспособных эндпоинтов опустится ниже указанного значения.

  Значение по умолчанию — 0, при котором режим паники не активируется никогда.

• ingress.alb.yc.io/balancing-locality-aware-routing

  Задает процент входящего трафика, который балансировщик передает бэкендам из своей зоны доступности. Остальной трафик поровну делится между другими зонами.

  Значение по умолчанию — 0.

  Подробнее о локализации трафика.

• ingress.alb.yc.io/autoscale-max-size

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

  Подробнее о настройках автомасштабирования.

• ingress.alb.yc.io/autoscale-min-zone-size

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

  Подробнее о настройках автомасштабирования.

• ingress.alb.yc.io/session-affinity-header

  HTTP-заголовок для привязки сессий.

  • name — имя HTTP-заголовка.

• ingress.alb.yc.io/session-affinity-cookie

  Параметры cookie для привязки сессий.

  • name — имя cookie.

  • ttl — время жизни cookie. Значение следует указывать с единицами измерения, например: 300ms, 1.5h. Допустимые единицы измерения:

    • ns — наносекунды.
    • us — микросекунды.
    • ms — миллисекунды.
    • s — секунды.
    • m — минуты.
    • h — часы.

  Параметры перечисляются через запятую. Пример:

  ...
  annotations:
    ingress.alb.yc.io/session-affinity-cookie: name=X-Example,ttl=30m
    ...
  

• ingress.alb.yc.io/session-affinity-connection

  Признак использования IP-адреса клиента для привязки сессий.

  • source-ip — значение true или false.

IngressSpecIngressSpec

ingressClassName: <string>
tls:
  - <IngressTLS>
  - ...
rules:
  - <IngressRule>
  - ...
defaultBackend:
  - <IngressBackend>
  - ...

IngressTLSIngressTLS

- hosts:
    - <string>
    - ...
  secretName: <string>

IngressRuleIngressRule

- host: <string>
  http:
    paths:
      - path: <string>
        pathType: <string>
        backend: <IngressBackend>

В версиях ALB Ingress Controller до 0.2.0 каждая группа бэкендов соответствует связке параметров host, http.paths.path и http.paths.pathType. В версиях 0.2.0 и позднее группа бэкендов соответствует параметру backend.service (IngressBackend). Из-за этого при обновлении ALB Ingress Controller могут возникнуть коллизии. Чтобы избежать их, узнайте, применимы ли ограничения при обновлении к вашей инфраструктуре.

IngressBackendIngressBackend

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

DefaultBackendDefaultBackend

Бэкенд по умолчанию, на который перенаправляется трафик, когда правила распределения входящего трафика по бэкендам не заданы. Если в описании Ingress нет поля spec.rules, то должно быть поле spec.defaultBackend.

Если доменное имя и запрашиваемый ресурс не соответствуют тем, что указаны в правилах, трафик также перенаправляется на бэкенд по умолчанию.

Поле spec.defaultBackend указывает либо на сервис-бэкенд (service), либо на группу бэкендов (resource) и заполняется так же, как IngressBackend.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: testapp-ingress-with-default-backend
  namespace: testapp-ns
  annotations:
    ...
spec:
  defaultBackend:
    service:
      name: testapp-service
      port:
        name: http

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-1
  annotations:
    ...
spec:
  defaultBackend:
    resource:
      apiGroup: alb.yc.io
      kind: HttpBackendGroup
      name: bg-with-bucket

IngressGroupSettingsIngressGroupSettings

apiVersion: alb.yc.io/v1alpha1
kind: IngressGroupSettings
metadata:
  name: non-default-settings
logOptions:
  logGroupID: <идентификатор_лог-группы>
  discardRules:
    - discardPercent: 50
      grpcCodes:
        - OK
        - CANCELLED
        - UNKNOWN
    - discardPercent: 67
      httpCodeIntervals:
        - HTTP_1XX
    - discardPercent: 20
      httpCodes:
        - 200
        - 404

Укажите идентификатор лог-группы и параметры правил отбрасывания логов:

• httpCodes — HTTP-коды.
• httpCodeIntervals — классы HTTP-кодов.
• grpcCodes — gRPC-коды.
• discardPercent — процент отбрасываемых логов.