Сервис развивается: тестируем формат, собираем идеи, улучшаем сервис. Есть идеи?

Написать
Войти
Дайджесты
Иллюстрация к миграции на Kubernetes Gateway API
ЛонгридАвтоматизацияБезопасностьСтратегияРазработка
IT: разработка · 31.07.2026

Миграция сетевой инфраструктуры Kubernetes с NGINX Ingress Controller на Gateway API

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

DevOps&SRE LibraryNGINX Networking for Kubernetes
70

Миграция сетевой инфраструктуры Kubernetes с NGINX Ingress Controller на Gateway API

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

В результате реальные конфигурации Ingress превратились в сплошные наборы спецификаций nginx.org/ или nginx.ingress.kubernetes.io/. Для решения этой проблемы сообщество Kubernetes SIG-Network разработало универсальный стандарт нового поколения — Kubernetes Gateway API.

Ограничения классического Ingress API и преимущества ролевой модели

Главный недостаток традиционного Ingress — смешение ответственности в одном монолитном манифесте. Инженер-разработчик приложения, создавая Ingress-ресурс, вынужден одновременно задавать хосты, пути маршрутизации, параметры TLS-сертификатов и тонкие настройки балансировки.

Gateway API решает эту проблему через внедрение четкого ролевого разделения ресурсов:

  • GatewayClass (Infrastructure Provider): Описывает тип балансировщика и контроллера трафика (например, NGINX Gateway Fabric). Управляется инженерами платформы.
  • Gateway (Cluster Operator): Задает точку входа в кластер: сетевые порты, IP-адреса, TLS-сертификаты и правила доступа. Управляется DevOps/SRE-командой.
  • HTTPRoute / GRPCRoute / TLSRoute (Application Developer): Определяет правила маршрутизации конкретного приложения: сопоставление путей (path matching), заголовков (header matching), перенаправления (redirects) и веса для канареечного развертывания. Создается продуктовой командой.

Такое разделение повышает безопасность инфраструктуры: прикладная команда может самостоятельно управлять маршрутами HTTPRoute в своем namespace, не имея прав на изменение глобальных сетевых портов и TLS-ключей кластера.

Архитектурное устройство NGINX Gateway Fabric

Реализация Gateway API от F5/NGINX получила название NGINX Gateway Fabric (NGF). Это сетевой контроллер нового поколения, использующий в качестве Data Plane высокопроизводительный сервер NGINX.

Архитектура NGINX Gateway Fabric разделена на две части:

  1. Control Plane: Контроллер Kubernetes, написанный на базе controller-runtime. Он отслеживает создание и изменение ресурсов Gateway API (GatewayClass, Gateway, HTTPRoute, GRPCRoute), а также связанную инфраструктуру (Services, Endpoints, Secrets). При изменениях контроллер динамически генерирует файл конфигурации NGINX и передает его в Data Plane.
  2. Data Plane: Поды с сервером NGINX и агентом управления (NGINX Agent), которые выполняют непосредственную балансировку трафика. Поды Data Plane могут разворачиваться как в виде Deployment (с масштабированием по HPA), так и в виде DaemonSet на выделенных Ingress-узлах.

В отличие от классического NGINX Ingress Controller, NGF полностью строится вокруг декларативных стандартов Gateway API, обеспечивая нативную поддержку протоколов gRPC и гибкую политику подключения SSL-сертификатов к бэкендам (BackendTLSPolicy).

Автоматизированный разбор конфигураций с помощью ingress2gateway

Перенос сотен существующих Ingress-манифестов вручную — трудоемкий процесс, чреватый ошибками. Для автоматизации миграции сообщество Kubernetes развивает утилиту ingress2gateway (официальный subproject Kubernetes SIG-Network).

Утилита содержит встроенный провайдер nginx, поддерживающий конвертацию ресурсов NGINX Ingress Controller в объекты Gateway API.

Примеры запуска инструмента:

  • Извлечение данных из живого кластера: 
    ingress2gateway print --providers=nginx
  • Конвертация локального YAML-файла манифестов: 
    ingress2gateway print --providers=nginx --input-file=nginx-ingress.yaml

Команда ingress2gateway выполняет сопоставление классических аннотаций NGINX с нативными ресурсами Gateway API:

Исходная аннотация NGINX IngressРезультирующий ресурс Gateway API
nginx.org/ssl-servicesBackendTLSPolicy (безопасное TLS-соединение к бэкенду)
nginx.org/grpc-servicesGRPCRoute (нативная маршрутизация gRPC)
nginx.org/rewritesHTTPRoute с фильтром URLRewrite
nginx.org/redirect-to-httpsHTTPRoute с фильтром RequestRedirect
nginx.org/proxy-set-headersHTTPRoute с фильтром RequestHeaderModifier

Инструмент выводит сгенерированные манифесты Gateway, HTTPRoute и BackendTLSPolicy в стандартный вывод для последующего аудита.

Границы автоматической конвертации и области ручной проверки

Важно понимать, что утилита ingress2gateway не является решением для автоматической миграции «в один клик». Она создает первичный черновик конфигурации, требующий обязательного инспектирования инженерами.

Ограничения автоматической конвертации:

  1. Неполное покрытие Custom Resources: Кастомные ресурсы NGINX Ingress Controller, такие как VirtualServer, VirtualServerRoute и TransportServer, на текущем этапе не конвертируются автоматически и требуют выработки эквивалентной схемы HTTPRoute.
  2. Вспомогательные аннотации: Специфические аннотации таймаутов, буферизации, клиентских лимитов и произвольных фрагментов кода (configuration-snippets) требуют ручной настройки через расширения политики Policy Grants.
  3. Семантические различия: Разработчики должны проверить правила обработки путей (Prefix vs Exact matching) и перенаправления trailing slash (/).

Сгенерированные манифесты обязаны проходить валидацию и тестирование в изолированном окружении перед их применением в продуктовом кластере.

Пятиэтапный регламент безопасной миграции без простоя сервисов

Для переноса сетевой инфраструктуры с NGINX Ingress Controller на NGINX Gateway Fabric без перерыва в обслуживании пользователей рекомендуется использовать следующий регламент:

  1. Этап 1: Инвентаризация и аудит (Discovery) Сформировать реестр всех существующих Ingress, TLS-секретов и используемых аннотаций. Выделить критичные сервисы (gRPC, WebSocket, клиентские перенаправления). Зафиксировать исходные метрики latency и ошибок.
  2. Этап 2: Параллельная установка (Parallel Install) Установить в кластер Gateway API CRDs и контроллер NGINX Gateway Fabric. NGF разворачивается параллельно со старым NGINX Ingress Controller и не затрагивает действующий трафик. Подтвердить готовность GatewayClass и успешный запуск подов Data Plane.
  3. Этап 3: Генерация и аудит манифестов (Conversion & Review) Выполнить конвертацию через ingress2gateway print --providers=nginx --input-file=.... Сохранить полученные HTTPRoute в репозиторий GitOps (ArgoCD/Flux). Провести инженерный код-ревью правил URLRewrite, RequestRedirect и TLS-конфигураций.
  4. Этап 4: Тестирование в изолированном окружении (Testing) Применить сгенерированные HTTPRoute в тестовом namespace. Через тестовые доменные имена (или подмену IP в hosts) проведать работу всех типов запросов: HTTP/2, gRPC-стримы, заголовочную маршрутизацию и SSL-сертификаты.
  5. Этап 5: Переключение трафика и откат (Cutover & Monitoring) Перевод продуктового трафика выполняется канареечным способом путем изменения записи на внешнем DNS или балансировщике LoadBalancer. В течение нескольких дней вести мониторинг ответов 4xx/5xx и времени отклика. Старый NGINX Ingress Controller сохраняется в рабочем состоянии на случай немедленного отката DNS.

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