Миграция с Ingress NGINX на ALB

В руководстве описана миграция публикации приложений и системных интерфейсов Deckhouse Kubernetes Platform (DKP) с модуля ingress-nginx на модуль alb, включая замену ресурсов Ingress приложений ресурсами Gateway API и переключение трафика на ALB.

Мотивация

Миграция с Ingress API на Gateway API переводит управление трафиком приложений на современную модель Kubernetes. Активное сопровождение upstream-проекта Ingress NGINX, используемого в DKP, прекращено, поэтому появления новых функций, исправлений и интеграций в нём не ожидается. Для новых и активно развиваемых сценариев публикации приложений рекомендуется использовать Gateway API.

Gateway API является современным стандартом Kubernetes для организации сетевого доступа к приложениям. По сравнению с Ingress API он предоставляет более гибкую и выразительную модель: отдельные ресурсы маршрутов для разных протоколов, явную настройку точек приёма трафика, контролируемое подключение маршрутов и специальные ресурсы для доступа между неймспейсами. Такая модель позволяет описывать сложные конфигурации трафика, не прибегая повсеместно к аннотациям, зависящим от конкретного контроллера.

Gateway API также задаёт чёткие границы ответственности. Администраторы кластера и сети управляют инфраструктурой обработки трафика и объектами Gateway через ClusterALBInstance или ALBInstance, а команды приложений определяют слушателей и правила маршрутизации с помощью ListenerSet и ресурсов маршрутов. Такое разделение упрощает делегирование, проверку конфигурации и поэтапную миграцию.

Область применения

Руководство охватывает миграцию с модели публикации приложений DKP на основе ingress-nginx на модель Gateway API, предоставляемую модулем alb. В нём описаны архитектурные различия, инфраструктурные изменения для внедрения ALBInstance или ClusterALBInstance и управляемого объекта Gateway, а также изменения приложений для замены ресурсов Ingress ресурсами Gateway API.

Руководство не является общим учебным материалом по Gateway API. В нём не рассматриваются миграция с других ingress-контроллеров, изменение архитектуры приложений, миграция на сервисную сетку и полный набор аннотаций ingress-nginx. Совместимость аннотаций рассматривается только в части, влияющей на миграцию на модуль alb.

Сравнение моделей

В этом разделе сравнивается, как описывается инфраструктура обработки трафика, как DKP создаёт её и как правила маршрутизации приложений преобразуются в конфигурацию прокси-сервера.

Ingress API и ingress-nginx

Ниже представлена схема ресурсов и прохождения трафика через модуль ingress-nginx.

Обработка HTTP- и HTTPS-трафика через модуль ingress-nginx настраивается следующим образом:

1. Администратор кластера создаёт кластерный объект IngressNginxController.
2. В IngressNginxController указывается имя используемого объекта IngressClass. Если имя не задано, используется nginx.
3. DKP обрабатывает объект и создаёт необходимую инфраструктуру, включая IngressClass. Несколько объектов IngressNginxController могут использовать один IngressClass.
4. По умолчанию ресурсы DKP публикуются через IngressClass с именем nginx. Другой класс можно выбрать в глобальной конфигурации DKP.
5. Администраторы сети или команды приложений создают объекты Ingress, которые явно или неявно выбирают требуемый IngressClass.
6. Итоговая конфигурация nginx объединяет параметры инфраструктуры из IngressNginxController с объектами Ingress, выбранными по IngressClass.

Gateway API и alb

Ниже представлена схема ресурсов и прохождения трафика через модуль alb.

Обработка трафика HTTP, HTTPS, gRPC, TLS, TCP и UDP через модуль alb настраивается следующим образом:

1. Администратор кластера создаёт кластерный объект ClusterALBInstance.
2. В ClusterALBInstance задаются параметры инфраструктуры и обязательный параметр gatewayName, который определяет управляемый объект Gateway.
3. Контроллер ALB обрабатывает объект и создаёт управляемый Gateway и необходимую инфраструктуру обработки трафика. Несколько объектов ClusterALBInstance могут использовать одинаковое значение gatewayName и, следовательно, один объект Gateway.
4. Если настроен Gateway DKP по умолчанию, модули DKP создают для него объекты ListenerSet, HTTPRoute и другие ресурсы Gateway API.
5. Администраторы сети или команды приложений создают ресурсы Gateway API и подключают их к управляемому объекту Gateway.
6. Итоговая конфигурация Envoy Proxy объединяет параметры инфраструктуры из ClusterALBInstance с конфигурацией, заданной ресурсами Gateway API, подключёнными к Gateway.

Ключевые архитектурные различия

На схемах представлены следующие архитектурные различия:

Миграция инфраструктуры

Выбор ALBInstance или ClusterALBInstance

Используйте ClusterALBInstance для общего или платформенного объекта Gateway, публикации системных интерфейсов DKP, а также если требуется инлет HostPort. Для публикации системных интерфейсов DKP выполните инструкции из раздела «Настройка доступа к системным компонентам DKP с использованием Gateway API». Используйте ALBInstance для объекта Gateway, выделенного приложению или команде и управляемого в пределах соответствующего неймспейса. Для ALBInstance поддерживается только инлет LoadBalancer.

Подробное сравнение приведено в разделе «Автоматическое создание и гибкая настройка инфраструктуры для объектов Gateway».

Настройка инлета

В IngressNginxController тип инлета одновременно определяет способ приёма трафика и дополнительные функции, например Proxy Protocol и сквозную передачу TLS-трафика. В модуле alb эти параметры настраиваются раздельно:

• ClusterALBInstance поддерживает инлеты LoadBalancer и HostPort.
• ALBInstance поддерживает инлет LoadBalancer.
• Proxy Protocol включается параметром spec.useProxyProtocol. Его можно включать и отключать в существующем экземпляре без перезапуска подов Envoy Proxy или пересоздания экземпляра.
• Сквозная передача TLS-трафика настраивается с помощью TLS-слушателя и объекта TLSRoute, а не отдельного типа инлета.

При выборе инлета для модуля alb используйте следующее соответствие:

Связанные параметры инлета переносятся следующим образом:

При переносе параметров учитывайте следующее:

• Переносите только аннотации объекта Service, поддерживаемые целевой реализацией балансировщика.
• Параметр spec.inlet.loadBalancer.loadBalancerClass нельзя изменить после создания объекта.
• По умолчанию используются порты HTTP 80 и HTTPS 443. В модуле alb соответствующий слушатель по умолчанию можно отключить, задав для порта значение 0.
• Параметры HostPort доступны только для ClusterALBInstance. Необходимо указать хотя бы один порт.
• Перенесите необходимые ограничения доступа по исходным CIDR-диапазонам в spec.acceptRequestsFrom.
• Явно укажите CIDR доверенных прокси-серверов. Не разрешайте обработку заголовков с адресом клиента от произвольных источников.
• Значение loadBalancerSourceRanges передаётся в объект Service типа LoadBalancer. Облачный провайдер может не поддерживать или игнорировать этот параметр. Проверьте его работу с целевой реализацией балансировщика.

TLS и сертификаты

Инструкции по настройке Issuer или ClusterIssuer с механизмом проверки HTTP-01 через Gateway API приведены в разделе «Добавление собственного HTTP-01 ClusterIssuer или Issuer для ALB».

Миграция интерфейсов DKP

Для публикации системных интерфейсов DKP через Gateway API выполните инструкции из раздела «Настройка доступа к системным компонентам DKP с использованием Gateway API» руководства администратора.

Миграция публикации приложений

Поддерживаемые ресурсы Gateway API

Модуль alb создаёт и обслуживает объекты Gateway, на которые ссылаются ресурсы ALBInstance и ClusterALBInstance. На один управляемый объект Gateway могут ссылаться один или несколько таких ресурсов. Это позволяет использовать единый граф ресурсов Gateway API, включая ListenerSet, маршруты и политики, через отдельные точки входа с разными инлетами и индивидуальными параметрами развёртывания прокси для каждого экземпляра.

Некоторые параметры экземпляров, например additionalPorts, frontendTLS и backendTLS, влияют на общий объект Gateway, поэтому они не могут одновременно иметь разные итоговые значения. Для таких параметров приоритет имеет экземпляр с наиболее ранней датой создания. Более новые экземпляры продолжают предоставлять собственные инлеты и рабочие нагрузки прокси, однако их конфликтующие параметры уровня Gateway игнорируются, а сведения о конфликте отображаются в статусе.

Не изменяйте управляемый объект Gateway вручную. Способ приёма трафика HTTP, HTTPS, gRPC и TLS задавайте с помощью ресурсов ListenerSet, а ресурсы маршрутов привязывайте к соответствующим слушателям. Слушатели TCP- и UDP-трафика создаются непосредственно в управляемом объекте Gateway на основе параметра additionalPorts соответствующего ресурса.

Модуль alb поддерживает следующие ресурсы Gateway API:

• Gateway — представляет точку входа трафика под управлением DKP. DKP создаёт ресурс и постоянно приводит его в соответствие с параметрами связанного ALBInstance или ClusterALBInstance. Не изменяйте Gateway вручную.
• ListenerSet — определяет слушателей управляемого объекта Gateway, включая порты, протоколы, имена хостов и параметры TLS. В модуле alb используйте ListenerSet как основной способ определения слушателей HTTP, HTTPS, gRPC и TLS вместо изменения Gateway.spec.listeners.
• HTTPRoute — направляет запросы HTTP и HTTPS от слушателя ListenerSet к объектам Service, выступающим в качестве бэкендов. Поддерживает сопоставление и обработку запросов по имени хоста, пути, заголовкам, параметрам запроса и другим атрибутам HTTP.
• GRPCRoute — направляет запросы gRPC от слушателя ListenerSet к объектам Service, выступающим в качестве бэкендов, с возможностью сопоставления по gRPC-сервису, методу или заголовкам.
• TCPRoute — направляет TCP-соединения от дополнительного TCP-слушателя к объекту Service, выступающему в качестве бэкенда. Слушатель и порт создаются в управляемом объекте Gateway на основе spec.inlet.additionalPorts.
• TLSRoute — направляет TLS-соединения по SNI без терминации TLS на Gateway. Используйте его со слушателем TLS или HTTPS в режиме Passthrough, определённым в ListenerSet, если TLS терминируется на стороне приложения.
• UDPRoute — направляет UDP-дейтаграммы от дополнительного UDP-слушателя к объекту Service, выступающему в качестве бэкенда. Слушатель и порт создаются в управляемом объекте Gateway на основе spec.inlet.additionalPorts.
• ReferenceGrant — явно разрешает поддерживаемые ссылки между неймспейсами, например если маршрут и его родительский ListenerSet находятся в разных неймспейсах.
• BackendTLSPolicy — настраивает TLS и проверку сертификата сервера для соединений от Gateway к объекту Service, выступающему в качестве бэкенда.

Конвертация Ingress в Gateway API

До преобразования ресурсов приложений создайте целевой ALBInstance или ClusterALBInstance, дождитесь его перехода в состояние готовности и получите неймспейс и имя управляемого объекта Gateway из статуса экземпляра. Преобразуйте каждый объект Ingress и связанную с ним конфигурацию в соответствующие ресурсы ListenerSet, маршруты и политики для этого Gateway. Встроенный инструмент конвертации позволяет получить черновой набор ресурсов, однако перед применением проверьте сгенерированные манифесты, поскольку не для каждой функции ingress-nginx существует прямой аналог в Gateway API.

Использование встроенного инструмента ingress2gateway

Контроллер Gateway предоставляет HTTP-эндпойнт, который принимает один объект, объект Kubernetes List или YAML с несколькими документами. Конвертер обрабатывает следующие входные ресурсы:

• Ingress — ресурсы, выбранные для преобразования.
• Service — ресурсы, используемые для определения именованных портов и метаданных объектов Service.
• DexAuthenticator — используется для определения spec.applicationDomain, если конфигурация внешней аутентификации ingress-nginx содержит переменные nginx, например $host.

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

1. Временно включите параметр migrations.ingress2Gateway.enabled в конфигурации модуля alb и дождитесь перезапуска контроллера Gateway:

   d8 k patch moduleconfig alb --type merge \
     --patch '{"spec":{"settings":{"migrations":{"ingress2Gateway":{"enabled":true}}}}}'
   d8 k -n d8-alb rollout status deployment/gateway-controller

2. Перенаправьте порт эндпойнта из пода контроллера Gateway:

   d8 k -n d8-alb port-forward deployment/gateway-controller 8082:8082

3. В другом терминале экспортируйте все распознаваемые типы ресурсов и передайте полученный Kubernetes List непосредственно конвертеру:

   d8 k get ingress,service,dexauthenticator --all-namespaces --output yaml | curl --fail-with-body --silent --show-error --request POST --header 'Content-Type: application/yaml' --data-binary @- --output gateway-api.yaml 'http://127.0.0.1:8082/ingress2gateway?gateway=<GATEWAY_NAMESPACE>/<GATEWAY_NAME>&scope=<SCOPE>&ingress-class=<INGRESS_CLASS>'

   где:

   • <GATEWAY_NAMESPACE> — неймспейс управляемого объекта Gateway;
   • <GATEWAY_NAME> — имя управляемого объекта Gateway;
   • <SCOPE> — область видимости инфраструктуры ALB: cluster или namespaced. Значение по умолчанию — cluster;
   • <INGRESS_CLASS> — объект IngressClass для отбора преобразуемых ресурсов. Значение по умолчанию — nginx.

Параметры запроса имеют следующие значения:

• gateway — целевой управляемый объект Gateway в формате <GATEWAY_NAMESPACE>/<GATEWAY_NAME>. Значение по умолчанию — d8-alb/public-gw;
• scope — область видимости целевой инфраструктуры ALB: cluster или namespaced. Значение по умолчанию — cluster;
• ingress-class — объект IngressClass для отбора преобразуемых ресурсов. Значение по умолчанию — nginx.

Перед применением сгенерированных ресурсов проверьте файл gateway-api.yaml и диагностические сообщения конвертера, добавленные в виде комментариев YAML. После завершения преобразования отключите эндпойнт:

d8 k patch moduleconfig alb --type merge \
  --patch '{"spec":{"settings":{"migrations":{"ingress2Gateway":{"enabled":false}}}}}'

Расширение Gateway API с помощью аннотаций

Спецификация Gateway API не охватывает все зависящие от реализации функции управления трафиком, необходимые для работы DKP. Поэтому модуль alb использует аннотации HTTPRoute для параметров, которые пока нельзя задать стандартными полями Gateway API. По мере развития Gateway API модуль alb будет постепенно заменять аннотации соответствующими стандартными ресурсами и полями. При миграции по возможности используйте стандартные поля Gateway API, а аннотации ingress-nginx заменяйте только поддерживаемыми аннотациями alb. Актуальный список приведён в разделе «Поддерживаемые аннотации HTTPRoute».

Переключение трафика на ALB

Используйте ingress-nginx и alb одновременно, пока обработка трафика через ALB не будет проверена и не завершится период, предусмотренный для отката. Переносите отдельные домены или неймспейсы, если для них можно использовать разные DNS-записи. В остальных случаях переключайте общую внешнюю точку входа, изменяя DNS-записи или пул бэкендов внешнего балансировщика.

Тестирование ALB через Ingress NGINX

Параметр spec.migrationGateway ресурса IngressNginxController позволяет тестировать обработку запросов от выбранных IP-адресов без изменения DNS. Запросы из sourceCIDRs продолжают поступать через существующую точку входа Ingress NGINX, но перенаправляются на внутренний объект Service целевого экземпляра ALB. Остальные запросы продолжают поступать в бэкенды, указанные в исходных ресурсах Ingress.

Несмотря на использование в данном руководстве для миграции на ALB, параметр migrationGateway не привязан к ALB. В serviceRef можно указать объект Service, предоставляющий точку входа любой реализации Gateway API и принимающий HTTP- и HTTPS-трафик на заданных портах.

Найдите конфигурационный объект Service ALB:

d8 k get service --all-namespaces --selector alb.deckhouse.io/configuration-service

Затем настройте исходный IngressNginxController. Сначала укажите в sourceCIDRs небольшое количество адресов тестовых клиентов:

apiVersion: deckhouse.io/v1
kind: IngressNginxController
metadata:
  name: <CONTROLLER_NAME>
spec:
  # Остальные параметры не показаны.
  migrationGateway:
    sourceCIDRs:
      - <SOURCE_CIDR>
    serviceRef:
      namespace: <SERVICE_NAMESPACE>
      name: <SERVICE_NAME>
      ports:
        http: <HTTP_PORT>
        https: <HTTPS_PORT>

где:

• <CONTROLLER_NAME> — имя исходного объекта IngressNginxController;
• <SOURCE_CIDR> — CIDR клиентов, чьи запросы во время тестирования перенаправляются на ALB;
• <SERVICE_NAMESPACE> — неймспейс конфигурационного Service ALB;
• <SERVICE_NAME> — имя конфигурационного Service ALB;
• <HTTP_PORT> — HTTP-порт целевого Service;
• <HTTPS_PORT> — HTTPS-порт целевого Service.

HTTP-запросы перенаправляются на указанный HTTP-порт. Для HTTPS nginx терминирует входящее TLS-соединение и устанавливает новое TLS-соединение через указанный HTTPS-порт, используя исходное имя хоста в заголовке Host и для SNI. Параметр применяется ко всем ресурсам Ingress, обслуживаемым контроллером, поэтому проверьте каждое имя хоста, доступное с адресов из sourceCIDRs.

Чтобы немедленно вернуть выбранных клиентов на бэкенды, указанные в исходных ресурсах Ingress, удалите spec.migrationGateway:

d8 k patch ingressnginxcontroller <CONTROLLER_NAME> --type json \
  --patch '[{"op":"remove","path":"/spec/migrationGateway"}]'

где <CONTROLLER_NAME> — имя исходного объекта IngressNginxController.

Обеспечение проверки HTTP-01 во время миграции

Параметр migrationGateway перенаправляет выбранные запросы приложений, а migrations.http01CertificateSolverBridging обеспечивает прохождение проверочных запросов HTTP-01 от cert-manager для Gateway API через Ingress NGINX, пока публичные DNS-записи указывают на него. Если используются объекты Issuer или ClusterIssuer с механизмом проверки HTTP-01, включите перенаправление проверок до запроса сертификатов для точки входа ALB:

d8 k patch moduleconfig alb --type merge \
  --patch '{"spec":{"settings":{"migrations":{"http01CertificateSolverBridging":{"enabled":true,"ingressClassName":"<INGRESS_CLASS>"}}}}}'
d8 k -n d8-alb rollout status deployment/gateway-controller

где <INGRESS_CLASS> — IngressClass, через который в данный момент принимается публичный трафик на порту 80.

Контроллер ALB создаёт временные ресурсы Ingress для объектов HTTPRoute, создаваемых cert-manager для проверки HTTP-01. Благодаря этому запросы проверки проходят через Ingress NGINX к соответствующему объекту Service. Для работы этой функции модуль ingress-nginx должен оставаться включённым.

Параметр http01CertificateSolverBridging позволяет выпустить сертификаты для точки входа Gateway API до переключения трафика. После этого конфигурацию TLS можно проверить через migrationGateway либо подключиться непосредственно к IP-адресу ALB, переопределив разрешение имени с помощью параметра curl --resolve.

После переключения DNS или внешнего балансировщика на ALB проверьте выпуск сертификата непосредственно через Gateway API и отключите перенаправление проверок:

d8 k patch moduleconfig alb --type merge \
  --patch '{"spec":{"settings":{"migrations":{"http01CertificateSolverBridging":{"enabled":false}}}}}'

Выбор способа переключения

Автоматически создаваемый балансировщик нагрузки

Если Ingress-контроллер использует объект Service типа LoadBalancer, автоматически создаваемый облачным провайдером Kubernetes, исходный и целевой контроллеры обычно получают разные IP-адреса или DNS-имена балансировщиков. Дождитесь готовности балансировщика ALB и успешного прохождения проверок состояния, заранее уменьшите TTL DNS и измените DNS-записи приложений, заменив адрес Ingress NGINX адресом ALB.

Используйте взвешенные DNS-записи для постепенного переключения только при их поддержке DNS-провайдером. Балансировщик под управлением облачного провайдера обычно не позволяет постепенно переключать отдельные узлы между двумя независимо управляемыми объектами Service. Если MetalLB или другая реализация использует фиксированный адрес, этот адрес нельзя одновременно назначить двум объектам Service: переносите его только в рамках согласованного переключения.

Балансировщик нагрузки под ручным управлением

Если облачный или частный балансировщик управляется вне Kubernetes, оставьте публичную DNS-запись без изменений и измените его пул бэкендов. Добавьте в пул узлы ALB и настроенные для них порты, убедитесь в успешном прохождении проверок состояния, затем постепенно переключите трафик с бэкендов Ingress NGINX. Удаляйте старые бэкенды только после проверки. Такой способ позволяет переключать отдельные узлы и распределять трафик по весам, если внешний балансировщик поддерживает эти функции.

Настройте проверки состояния по пути /healthz на HTTP-порту ALB. Сохраните исходный протокол и способ определения IP-адреса клиента: согласуйте настройки Proxy Protocol для пользовательского трафика и проверок состояния либо настройте доверие к заголовкам с адресом клиента, которые передаёт L7-балансировщик. Если оба контроллера работают на одних узлах, используйте разные порты хоста либо выберите непересекающиеся группы узлов.

Прямой доступ через HostNetwork или HostPort

Если DNS-записи указывают непосредственно на адреса узлов, разверните ALB на отдельной группе узлов или используйте непересекающиеся порты хоста. Для постепенного переключения добавляйте адреса узлов ALB в DNS-запись и удаляйте адреса узлов Ingress NGINX после проверки каждого узла. DNS не обеспечивает предсказуемое весовое распределение трафика и плавное завершение активных соединений, поэтому учитывайте TTL и кеширование на стороне клиентов.

DNS не позволяет выбрать контроллеры, использующие разные порты на одном адресе узла. Если клиенты должны продолжать использовать порты 80 и 443, используйте разные узлы либо добавьте балансировщик или правило NAT. Инлет HostWithFailover не имеет прямого аналога в ALB. Если требуется эквивалентная отказоустойчивость, используйте рекомендуемый инлет LoadBalancer с MetalLB.

Проверка переключения

Перед переключением пользовательского трафика:

• Убедитесь, что в статусе целевого ALBInstance или ClusterALBInstance установлены ready и synced, и проверьте поля конфликтов.
• Проверьте условия в статусах Gateway, ListenerSet и маршрутов, включая принятие ресурсов, разрешение ссылок и готовность слушателей.
• Для каждого имени хоста и протокола проверьте обработку трафика, подключившись напрямую к адресу ALB или с помощью migrationGateway: TLS-сертификаты, перенаправления, аутентификацию, долгоживущие соединения и политики приложений.
• Проверьте сохранение IP-адреса клиента, обработку Proxy Protocol или заголовков с адресом клиента, ограничения доступа по источнику и проверки состояния балансировщика.
• Убедитесь, что метрики, журналы, оповещения и дашборды позволяют различать трафик и ошибки обоих контроллеров.
• Сохраняйте ресурсы Ingress, Ingress-контроллер, его внешнюю точку входа и действительные сертификаты в течение всего периода, предусмотренного для отката.

Откат

Определите критерии отката до переключения. Если при проверке выявлены ошибки:

1. При тестировании через migrationGateway удалите spec.migrationGateway.
2. При переключении DNS верните адрес Ingress NGINX и дождитесь истечения предыдущего TTL DNS.
3. При использовании балансировщика под ручным управлением верните узлы и порты Ingress NGINX в его пул бэкендов.
4. Если публичный трафик снова поступает через Ingress NGINX, а объекты Issuer или ClusterIssuer для сертификатов Gateway API используют механизм проверки HTTP-01, повторно включите http01CertificateSolverBridging.

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

Очистка

После завершения периода отката удалите migrationGateway, отключите http01CertificateSolverBridging и ingress2Gateway, удалите устаревшие ресурсы Ingress и Ingress-контроллеры, а также неиспользуемые балансировщики, сертификаты, объекты Secret и DNS-записи. Верните обычные значения TTL DNS, убедившись, что клиенты больше не используют старую точку входа.