Миграция Ingress NGINX с Helm chart 4.x на 5.x: практическое руководство без простоя

Обновление Ingress NGINX Controller с Helm chart 4.x до 5.x затрагивает критические компоненты кластера Kubernetes. Основные breaking changes сконцентрированы вокруг перехода на стабильные API-версии, удаления устаревших параметров values.yaml и обязательной замены аннотаций на нативные поля Ingress. Игнорирование этих изменений приведет к ошибкам валидации манифестов и отказу контроллера обрабатывать трафик.

Эта инструкция построена на проверенной последовательности действий: аудит текущей конфигурации, тестовый прогон в изолированном окружении и атомарное обновление production-среды с возможностью мгновенного отката. Вы получите готовые команды и таблицы соответствия старых и новых параметров, которые исключат простой сервисов.

Ключевые изменения в Helm chart 5.x: что ломается и почему

Разработчики ingress-nginx провели рефакторинг чарта, приведя его в соответствие с современными стандартами Kubernetes. Изменения носят обязательный характер - старые параметры и аннотации перестают поддерживаться. Основной объем работ при миграции приходится на адаптацию values.yaml и Ingress-манифестов.

Изменения в API-версиях и манифестах

Helm chart 5.x требует Kubernetes не ниже версии 1.19 и полностью отказывается от устаревших API. Ресурс Ingress переведен на стабильную версию networking.k8s.io/v1, которая стала обязательной с Kubernetes 1.22. Ресурс ValidatingWebhookConfiguration теперь использует admissionregistration.k8s.io/v1 вместо v1beta1.

Diff манифеста Ingress до и после миграции выглядит так:

# Старая версия (extensions/v1beta1 или networking.k8s.io/v1beta1)
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        backend:
          serviceName: my-service
          servicePort: 80

# Новая версия (networking.k8s.io/v1)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  # аннотация удалена
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

Ключевые отличия: поле spec.ingressClassName обязательно, структура backend изменилась - теперь это объект с полями service.name и service.port.number, а поле pathType стало обязательным. Без этих правок контроллер не примет манифест.

Устаревшие параметры values.yaml и их замена

Разработчики переименовали и реструктурировали значительную часть параметров. При попытке использовать старые ключи Helm выдаст ошибку или молча проигнорирует их - поведение зависит от версии. Таблица ниже содержит критические замены, которые необходимо выполнить перед обновлением.

Пример фрагмента values.yaml после адаптации:

controller:
  ingressClassResource:
    name: nginx
    enabled: true
    default: false
  service:
    publishService:
      enabled: true
    internalIPs:
      enabled: true
  extraArgs:
    watch-namespace: "my-namespace"

Перед обновлением на production обязательно проверьте свой values.yaml на наличие всех перечисленных параметров. Пропуск даже одного приведет к неожиданному поведению контроллера.

Миграция аннотаций и ConfigMap

Самый частый источник ошибок при миграции - аннотация kubernetes.io/ingress.class. В chart 5.x она полностью заменяется полем spec.ingressClassName в манифесте Ingress. Контроллер перестает обрабатывать аннотацию, и все Ingress-ресурсы без явного указания класса перестанут работать.

Алгоритм замены:

1. Убедитесь, что ресурс IngressClass создан чартом (параметр controller.ingressClassResource.enabled: true).
2. Во всех Ingress-манифестах удалите аннотацию kubernetes.io/ingress.class.
3. Добавьте поле spec.ingressClassName: nginx (или ваше кастомное имя класса).

ConfigMap контроллера также претерпел изменения. Параметр proxy-body-size теперь задается без префикса proxy- - используйте body-size. Параметр ssl-redirect переименован в force-ssl-redirect с инвертированной логикой: значение true теперь принудительно включает редирект, а не разрешает его. Проверьте все кастомные настройки ConfigMap на соответствие документации chart 5.x.

Подготовка к миграции: аудит текущей конфигурации и тестирование

Перед любыми изменениями в production необходимо зафиксировать исходное состояние и проверить обновление на тестовом стенде. Пропуск этого этапа - основная причина аварийных ситуаций при миграции. Затраченные 30-40 минут на аудит сэкономят часы восстановления.

Снимаем дамп текущей конфигурации

Зафиксируйте три источника данных: пользовательские параметры values.yaml, содержимое ConfigMap контроллера и список всех Ingress-ресурсов кластера. Эти данные понадобятся для сравнения после обновления и для ручного восстановления в случае проблем с helm rollback.

# Сохраняем пользовательские параметры релиза
helm get values ingress-nginx -n ingress-nginx > values-backup.yaml

# Сохраняем ConfigMap контроллера
kubectl get configmap ingress-nginx-controller -n ingress-nginx -o yaml > configmap-backup.yaml

# Сохраняем все Ingress-ресурсы кластера
kubectl get ingress -A -o yaml > all-ingresses-backup.yaml

# Дополнительно: сохраняем историю релизов Helm
helm history ingress-nginx -n ingress-nginx > history-backup.txt

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

Использование helm diff и helm template для проверки изменений

Плагин helm-diff показывает, какие именно ресурсы будут созданы, изменены или удалены в результате обновления. Это основной инструмент предварительного анализа, который выявляет несовместимости до применения изменений.

# Установка плагина (однократно)
helm plugin install https://github.com/databus23/helm-diff

# Добавляем репозиторий ingress-nginx и обновляем кэш
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Сравниваем текущий релиз с целевой версией chart
helm diff upgrade ingress-nginx ingress-nginx/ingress-nginx \
  --version 5.0.0 \
  -f values-production.yaml \
  -n ingress-nginx

Анализируйте вывод плагина построчно. Удаление ресурсов с пометкой - должно иметь объяснение - либо ресурс переименован, либо его функциональность перенесена. Добавление новых ресурсов с пометкой + должно соответствовать ожидаемым изменениям из таблицы выше. Любые неожиданные удаления - повод остановиться и перепроверить values.yaml.

Для детального анализа сгенерируйте полные манифесты и сравните их визуально:

# Генерируем манифесты для текущей версии
helm template ingress-nginx ingress-nginx/ingress-nginx \
  --version 4.11.0 \
  -f values-production.yaml \
  -n ingress-nginx > manifests-v4.yaml

# Генерируем манифесты для целевой версии
helm template ingress-nginx ingress-nginx/ingress-nginx \
  --version 5.0.0 \
  -f values-production-adapted.yaml \
  -n ingress-nginx > manifests-v5.yaml

# Сравниваем diff
vimdiff manifests-v4.yaml manifests-v5.yaml

Этот метод незаменим при сложных конфигурациях с множеством кастомных параметров. Он выявляет изменения на уровне конкретных полей в манифестах.

Тестовый прогон в изолированном окружении

Создайте отдельный namespace и воспроизведите в нем текущую production-конфигурацию. Это финальная проверка перед обновлением боевого кластера.

# Создаем тестовый namespace
kubectl create namespace ingress-test

# Устанавливаем chart 4.x с вашими production-параметрами
helm install ingress-nginx-test ingress-nginx/ingress-nginx \
  --version 4.11.0 \
  -f values-production.yaml \
  -n ingress-test

# Разворачиваем тестовое приложение
kubectl create deployment test-app --image=nginx:alpine -n ingress-test
kubectl expose deployment test-app --port=80 -n ingress-test

# Создаем тестовый Ingress (с аннотацией, как в production)
cat <

После успешной проверки выполните обновление до chart 5.x с адаптированным values.yaml. Сразу после обновления проверьте доступность тестового приложения и логи контроллера. Только при полном успехе переходите к production.

Пошаговая миграция на production без простоя

Ingress NGINX Controller поддерживает стратегию RollingUpdate, которая обеспечивает нулевой простой при обновлении. Новые поды запускаются и принимают трафик до завершения старых. Процесс миграции сводится к одному выверенному действию - команде helm upgrade с правильными флагами и предварительно подготовленным values.yaml.

Обновление values.yaml и запуск миграции

Финальная команда обновления должна включать флаги --atomic и --cleanup-on-fail. Первый автоматически откатывает релиз при ошибке, второй удаляет созданные в процессе ресурсы при неудаче. Это минимально необходимый уровень защиты для production.

# Обновляем репозиторий
helm repo update

# Запускаем миграцию
helm upgrade ingress-nginx ingress-nginx/ingress-nginx \
  --version 5.0.0 \
  -f values-production-adapted.yaml \
  -n ingress-nginx \
  --atomic \
  --cleanup-on-fail \
  --timeout 10m

# Флаги:
# --atomic - откат при ошибке
# --cleanup-on-fail - удаление созданных ресурсов при откате
# --timeout - увеличенный таймаут для production-сред

Не используйте флаг --force без крайней необходимости. Он удаляет ресурсы при конфликтах, что может привести к кратковременной потере трафика. Стратегия RollingUpdate, заданная в values.yaml, обрабатывает обновление подов контроллера без разрыва соединений.

Мониторинг и проверка после обновления

Сразу после выполнения helm upgrade откройте второе окно терминала и запустите мониторинг состояния подов и логов. Ожидание завершения команды без параллельного наблюдения - рискованная практика.

# Мониторим статус подов в реальном времени
watch kubectl get pods -n ingress-nginx

# Параллельно смотрим логи нового контроллера
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller -f --tail=50

# После перехода всех подов в Running проверяем метрики
kubectl port-forward -n ingress-nginx deployment/ingress-nginx-controller 10254:10254
curl http://localhost:10254/metrics | grep nginx_ingress_controller_requests

Критические признаки проблем в логах: ошибки валидации Ingress-ресурсов, сообщения о непризнанных аннотациях, отказы в обновлении конфигурации. Здоровый контроллер после перезапуска выводит список обработанных Ingress и подтверждает применение конфигурации.

Финальная проверка - тестирование маршрутизации на реальных хостах. Выполните curl-запросы к вашим сервисам через Ingress и убедитесь, что они возвращают ожидаемые ответы. Проверьте как минимум три типа ресурсов: статические страницы, API-эндпоинты и сервисы с WebSocket-соединениями.

Безопасный откат: helm rollback и восстановление из бэкапа

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

Откат с помощью helm rollback

Helm хранит историю релизов с номерами ревизий. Каждое обновление создает новую ревизию, и вы можете вернуться к любой из них одной командой.

# Смотрим историю релизов
helm history ingress-nginx -n ingress-nginx

# Вывод:
# REVISION  UPDATED                   STATUS      CHART               DESCRIPTION
# 1         Mon Aug  3 14:22:10 2026  superseded  ingress-nginx-4.11.0 Install complete
# 2         Thu Aug  6 10:15:33 2026  deployed    ingress-nginx-5.0.0  Upgrade complete

# Откатываемся к предыдущей ревизии (в данном случае - 1)
helm rollback ingress-nginx 1 -n ingress-nginx --timeout 10m

После отката повторите процедуру проверки из предыдущего раздела: статус подов, логи контроллера, тестовые curl-запросы. Контроллер версии 4.x должен корректно обработать Ingress-ресурсы, если вы не успели изменить их манифесты. Если вы уже перевели Ingress на networking.k8s.io/v1 с spec.ingressClassName, старый контроллер проигнорирует их - потребуется ручное восстановление.

Ручное восстановление из бэкапов

В ситуации, когда helm rollback не срабатывает (повреждена история релизов, удален Secret релиза), используйте сохраненные ранее дампы. Это холодный путь восстановления, требующий ручного вмешательства.

# Устанавливаем предыдущую версию chart с сохраненным values.yaml
helm upgrade ingress-nginx ingress-nginx/ingress-nginx \
  --version 4.11.0 \
  -f values-backup.yaml \
  -n ingress-nginx \
  --atomic

# Восстанавливаем ConfigMap из бэкапа
kubectl apply -f configmap-backup.yaml

# Перезапускаем контроллер для применения ConfigMap
kubectl rollout restart deployment ingress-nginx-controller -n ingress-nginx

Если часть Ingress-ресурсов была переведена на новый формат и не работает со старым контроллером, примените сохраненный дамп all-ingresses-backup.yaml. Это вернет все Ingress-манифесты к состоянию до миграции.

Типичные ошибки и их решение

Собранные здесь проблемы встречаются в 90% случаев миграции. Каждая запись содержит симптом, по которому вы опознаете ошибку, причину и конкретную команду для исправления.

Если ошибка не соответствует ни одному из описанных сценариев, соберите максимум диагностической информации: полный вывод helm upgrade с флагом --debug, логи контроллера за последние 5 минут, список всех Ingress-ресурсов с их аннотациями. Этих данных достаточно для локализации проблемы в 95% случаев.

После успешной миграции обновите документацию вашего проекта: зафиксируйте новую версию chart в зависимостях, актуализируйте примеры Ingress-манифестов и шаблоны values.yaml для новых окружений. Это предотвратит повторение проблем при следующем развертывании.