Миграция с NGINX Ingress Controller на Kubernetes Gateway API с использованием ingress2gateway

Практическое руководство для команд, готовящихся к прекращению поддержки NGINX Ingress

С официальным прекращением поддержки Ingress NGINX, запланированным на март 2026 года, пользователи Kubernetes сталкиваются с серьёзным архитектурным изменением. Это прекращение поддержки знаменует собой прекращение выпуска обновлений безопасности и исправлений ошибок, поэтому командам разработчиков крайне важно оценить планы миграции уже сейчас.

Один из самых простых и удобных в обслуживании путей — переход от традиционных ресурсов Ingress к Gateway API, современному стандарту сетевого взаимодействия в Kubernetes. Для упрощения этого процесса сообщество Kubernetes SIG Network предоставляет инструмент ingress2gateway с открытым исходным кодом, который автоматически преобразует объекты Ingress в ресурсы Gateway API.

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

🌐 Зачем переходить на API Gateway?

API Gateway улучшает Ingress по нескольким важным направлениям:

• Более взвешенная маршрутизация трафика.
  Поддержка взвешенной маршрутизации, совпадений по заголовкам и детализированных правил для хостов и путей.
• Модель ресурсов с учётом ролей.
  Инфраструктурные команды управляют Gateways, а команды приложений — Routes.
• Лучшее соответствие требованиям разных поставщиков.
  Снижает зависимость от конкретного вендора и сокращает количество аннотаций.
• Расширяемость без аннотаций.
  Функции, реализованные как реальные поля API.
• Активное управление и долгосрочная поддержка
  В отличие от ныне закрывающегося проекта Ingress NGINX.

Завершение поддержки Ingress NGINX создает естественную точку перелома для принятия Gateway API в качестве стабильной и современной альтернативы.

🧩 Пример: переход с NGINX Ingress на Gateway API

Рассмотрим простую, но типичную конфигурацию NGINX Ingress.

Исходный Ingress NGINX:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: my-app-service
                port:
                  number: 8080

Это правило направляет app.example.com/api на бэкенд-сервис на порту 8080, при этом применяется переписывание пути через аннотацию.

Эквивалент на Gateway API(вывод, сгенерированный с помощью ingress2gateway):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx-gateway
  namespace: production
spec:
  gatewayClassName: nginx
  listeners:
    - name: https
      hostname: app.example.com
      port: 443
      protocol: HTTPS
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: production
spec:
  parentRefs:
    - name: nginx-gateway
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              replacePrefixMatch: /
      backendRefs:
        - name: my-app-service
          port: 8080

Обратите внимание, что:

• Аннотация перезаписи теперь является полноценным фильтром URLRewrite.
• Ресурс Ingress разделен на Gateway (уровень инфраструктуры) и HTTPRoute (уровень приложения).
• Нет необходимости в аннотациях, специфичных для конкретного вендора.

⚙️ Пошаговая миграция с использованиемingress2gateway

Ниже представлен полный рабочий процесс миграции с NGINX Ingress на Gateway API с использованием официального инструмента перевода.

Шаг 1 — Установка инструмента ingress2gateway

Вы можете запустить его через Go:

go install sigs.k8s.io/ingress2gateway@latest

Шаг 2 — Экспортируйте существующие ресурсы Ingress

kubectl get ingress -A -o yaml > ingresses.yaml

Этот файл будет использоваться в качестве входных данных для конвертера.

Шаг 3 — Запуск ingress2gateway для генерации манифестов API Gateway

С помощью бинарника Go:

ingress2gateway \
  --input ingresses.yaml \
  --output gateway-api.yaml

Это даст:

• Gateway
• HTTPRoute
• ReferenceGrant (если требуется)
• Конфигурацию TLS (если присутствует)

Шаг 4 — Проверьте сгенерированные файлы

Ключевые моменты, которые нужно проверить вручную:

1. GatewayClass — есть ли он в вашем кластере?
2. Слушатели — правильное имя хоста? правильные порты?
3. TLS — Секретные имена и namespaces верны?
4. Правила перезаписи — Корректно ли преобразованы аннотации NGINX?
5. Пользовательские поведения, которые не поддерживаются в Gateway API — некоторые специфичные для NGINX логические операции аннотации могут потребовать ручного обновления.

Шаг 5 — Применение ресурсов Gateway API

kubectl apply -f gateway-api.yaml

Подтвердите, что:

• Gateway становится READY
• HTTPRoutes принимаются и подключаются

kubectl get gateways -A
kubectl get httproutes -A

Шаг 6 — Переключение трафика с Ingress на Gateway

После подтверждения:

1. Уменьшите NGINX Ingress Controller до минимума
2. Удалить старые правила Ingress
3. Мониторинг трафика и логов приложений
4. Полностью вывести из эксплуатации NGINX Ingress

🚀 Заключение

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

Это также прекрасная возможность:

• Упростить определения маршрутизации
• Удалить ненадежные аннотации NGINX
• Перейти на современный, независимый от вендора стандарт

Чем раньше вы начнете, тем более плавным будет ваш переход до марта 2026 года.