Поля и аннотации ресурса 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: <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
ObjectMeta
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/security-profile-id: <string>
ingress.alb.yc.io/use-regex: <string>
Поле |
Значение или тип |
Описание |
|
|
Обязательное. |
|
|
Обязательное. |
Аннотации (metadata.annotations)
Аннотации — это коллекция пар ключ:значение
, которые используются для присвоения метаданных объекту. Значения аннотаций всегда имеют тип данных string
. Подробнее об аннотациях см. в документации 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/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
.
IngressSpec
ingressClassName: <string>
tls:
- <IngressTLS>
- ...
rules:
- <IngressRule>
- ...
Поле |
Значение или тип |
Описание |
|
|
Имя ресурса IngressClass, к которому относится ресурс
|
|
|
Обязательное. Если поле указано, для балансировщика будут созданы обработчики двух видов: одни будут принимать HTTPS-трафик на порте 443, а другие — перенаправлять запросы с HTTP (порт 80) на HTTPS. При этом правила распределения трафика для тех же доменных имен, явно указанные в других Если поле не указано, для балансировщика будут созданы только обработчики для приема HTTP-трафика на порте 80. |
|
|
Обязательное. В Application Load Balancer правила соответствуют виртуальным хостам HTTP-роутеров. |
IngressTLS
hosts:
- <string>
- ...
secretName: <string>
Поле |
Значение или тип |
Описание |
|
|
Обязательное. Для каждого имени, как для значения TLS-расширения Server Name Indication (SNI), в балансировщике будет создан отдельный обработчик. Чтобы указать на все возможные поддомены любых уровней, вместо первого уровня доменного имени используйте звездочку
Заменить звездочкой только часть первого уровня доменного имени, например |
|
|
Обязательное. В Certificate Manager можно выпустить сертификат от Let's Encrypt® или загрузить собственный сертификат. Если сертификат пока не добавлен в Certificate Manager, укажите секрет Kubernetes с сертификатом в поле |
IngressRule
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 могут возникнуть коллизии. Чтобы избежать их, узнайте, применимы ли ограничения при обновлении к вашей инфраструктуре.
Поле |
Значение или тип |
Описание |
|
|
Обязательное. Чтобы указать на все возможные поддомены любых уровней, вместо первого уровня доменного имени используйте звездочку
Заменить звездочкой только часть первого уровня доменного имени, например |
|
|
Обязательное. |
|
|
Обязательное. Порядок маршрутов в списке важен: они сверяются с входящим запросом по очереди, и первый подошедший маршрут используется в маршрутизации. Поэтому рекомендуется помещать наиболее специфичные маршруты в начало списка. Эта логика отличается от описанной в документации Kubernetes Важно Если балансировщик создается по нескольким |
|
|
Обязательное.
В обоих случаях значение должно начинаться с |
|
|
Обязательное.
Помимо распределения трафика, от типа зависит механизм замены пути или имени вызова в запросах к бэкендам, если замена настроена с помощью аннотации ingress.alb.yc.io/prefix-rewrite. |
|
|
Обязательное. |
IngressBackend
service:
name: <string>
port:
name: <string>
number: <int32>
resource:
kind: HttpBackendGroup
name: <string>
apiGroup: alb.yc.io
Поле |
Значение или тип |
Описание |
|
|
Обязательное. Ресурс Для элемента списка
|
|
|
Обязательное. Ресурс Для элемента списка
|
IngressGroupSettings
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
— процент отбрасываемых логов.