Поля и аннотации ресурса 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-контроллера группы безопасности должны быть настроены, как описано в разделе Настройка групп безопасности для инструментов Application Load Balancer для Managed Service for Kubernetes.
-
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
.
В обоих случаях значение должно начинаться с
/
. - Для простого HTTP — путь в URI входящего запроса (если тип —
-
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
-