5 неочевидных особенностей Ingress-NGINX для безопасной миграции

В ноябре 2025 года команда Kubernetes объявила о выводе из эксплуатации популярного Ingress-контроллера Ingress-NGINX — процесс завершится в марте 2026. Несмотря на широкое распространение, Ingress-NGINX полон неочевидных умолчаний и побочных эффектов, которые годами незаметно работают в вашем кластере. Эта статья выделяет пять таких особенностей, чтобы вы могли безопасно мигрировать и осознанно решить, какое поведение сохранить. Мы также сравним Ingress-NGINX с Gateway API и покажем, как перенести привычную логику в новый API. Повторяющийся паттерн риска везде один: внешне корректный перевод конфигурации может вызвать отказ, если не учесть quirks Ingress-NGINX. Предполагается, что читатель знаком с Ingress-NGINX и Ingress API. Большинство примеров используют httpbin в качестве бэкенда. Важно отметить: Ingress-NGINX и NGINX Ingress — это разные контроллеры. Первый поддерживается сообществом Kubernetes и уходит в отставку в марте 2026, второй — продукт компании F5. Оба используют NGINX в качестве dataplane, но в остальном не связаны. Далее речь идёт только об Ingress-NGINX.

Регулярные выражения: префиксное совпадение и регистронезависимость

Допустим, вы хотите направлять все запросы, путь которых состоит ровно из трёх заглавных букв, на сервис httpbin. Вы создаёте Ingress с аннотацией nginx.ingress.kubernetes.io/use-regex: "true" и паттерном /[A-Z]{3}. Однако из-за того, что regex-совпадения в Ingress-NGINX являются префиксными и регистронезависимыми, контроллер будет маршрутизировать любой запрос, начинающийся с любых трёх букв, на httpbin. Например, curl -H "Host: regex-match.example.com" http://your-ingress/ABC сработает, но и curl -H "Host: regex-match.example.com" http://your-ingress/abcDEF тоже попадёт в httpbin, хотя по замыслу должен был обрабатываться иначе. Это поведение кардинально отличается от стандартных регулярных выражений в большинстве языков программирования. В Gateway API такого сюрприза нет: совпадения по умолчанию точные, а регистр учитывается. Чтобы сохранить префиксное поведение, в Gateway API нужно явно указать тип совпадения PathPrefix.

Перенаправление с HTTP на HTTPS: скрытый редирект для всех хостов

Ingress-NGINX по умолчанию включает глобальное перенаправление с HTTP на HTTPS, если в кластере есть хотя бы один Ingress-ресурс с TLS. Это означает, что даже если ваш сервис не использует TLS, запросы к нему по HTTP будут принудительно перенаправлены на HTTPS. Часто это остаётся незамеченным, пока не возникает необходимость отключить редирект для определённого хоста. В Gateway API такого глобального поведения нет: перенаправление нужно настраивать явно для каждого слушателя или маршрута. При миграции важно проверить, какие хосты действительно должны получать HTTPS-редирект, и явно задать это в ресурсах Gateway и HTTPRoute.

Прокси-заголовки: неожиданные изменения Host и X-Forwarded-For

Ingress-NGINX по умолчанию перезаписывает заголовок Host на внутреннее имя сервиса, а также добавляет или модифицирует X-Forwarded-For, X-Forwarded-Proto и другие заголовки. Это может нарушить работу приложений, которые полагаются на оригинальный Host (например, виртуальный хостинг). В Gateway API поведение с заголовками более предсказуемо: по умолчанию заголовки не изменяются, если не заданы фильтры. Чтобы сохранить старую логику, потребуется явно добавить фильтры модификации заголовков в HTTPRoute.

Лимиты соединений и таймауты: недокументированные значения по умолчанию

Ingress-NGINX устанавливает ряд лимитов, которые редко меняют: максимальный размер тела запроса — 1 МБ, таймаут чтения — 60 секунд, таймаут соединения — 5 секунд. Если ваше приложение передаёт большие файлы или требует долгих соединений (например, Server-Sent Events), эти умолчания могут стать причиной ошибок 413 или разрывов соединений. В Gateway API таких глобальных умолчаний нет — таймауты и лимиты задаются индивидуально для каждого маршрута или бэкенда. При миграции стоит заранее определить необходимые значения и перенести их в соответствующие поля HTTPRoute.

Балансировка нагрузки: алгоритм по умолчанию — round-robin, но с нюансами

Ingress-NGINX использует round-robin для распределения запросов между подами, однако из-за особенностей реализации NGINX это не совсем честный round-robin: веса могут смещаться при медленных или разрывающихся соединениях. Кроме того, Ingress-NGINX не поддерживает взвешенную балансировку на уровне Ingress-ресурса — для этого нужны отдельные аннотации. В Gateway API балансировка настраивается через политики, например, BackendTrafficPolicy, что даёт больше гибкости: можно задать алгоритм (round-robin, least-request, random) и веса. При миграции стоит пересмотреть требования к балансировке и выбрать подходящую политику.

Предыстория и контекст

Ingress-NGINX долгое время был де-факто стандартным Ingress-контроллером в Kubernetes. Он появился ещё в эпоху, когда Ingress API был единственным способом организации внешнего доступа к сервисам. Однако со временем стали очевидны его ограничения: сложность конфигурации через аннотации, нестандартное поведение, отсутствие гибкости в маршрутизации. В 2022 году Kubernetes представил Gateway API как более современную и выразительную альтернативу. К 2025 году экосистема созрела: большинство облачных провайдеров и производителей контроллеров поддерживают Gateway API. Решение о выводе Ingress-NGINX из эксплуатации — логичный шаг, позволяющий сообществу сфокусироваться на развитии нового API. Однако на практике миллионы кластеров всё ещё используют Ingress-NGINX, и многие администраторы не подозревают о скрытых особенностях его работы.

Чем Ingress-NGINX отличается от Gateway API?

Ключевое отличие — в модели конфигурации. Ingress-NGINX использует аннотации для расширения возможностей базового Ingress-ресурса, что приводит к разрозненной и трудно поддерживаемой конфигурации. Gateway API вводит разделение на роли: инфраструктурная команда управляет ресурсами Gateway, а команды приложений — HTTPRoute. Это упрощает управление и повышает безопасность. Кроме того, Gateway API поддерживает точное совпадение путей, фильтры заголовков, взвешенную балансировку и многое другое «из коробки», без аннотаций. Однако при миграции важно не просто скопировать правила, а переосмыслить их в терминах нового API.

Технические подробности: как сохранить поведение Ingress-NGINX в Gateway API

Для каждого из описанных пяти поведений Gateway API предлагает явные механизмы. Регулярные выражения: в HTTPRoute можно задать path.type: RegularExpression, но совпадение будет точным и регистрозависимым. Чтобы получить префиксное поведение, нужно комбинировать RegularExpression с pathPrefix или использовать несколько правил. Перенаправление HTTP→HTTPS: в Gateway API это делается через фильтр RequestRedirect в HTTPRoute, привязанный к конкретному слушателю. Прокси-заголовки: фильтр RequestHeaderModifier позволяет добавлять, изменять или удалять заголовки. Лимиты: параметры таймаутов и размеров задаются в BackendTrafficPolicy. Балансировка: алгоритм и веса настраиваются в BackendTrafficPolicy или HTTPRoute с помощью поля backendRefs.weight. Важно помнить, что Gateway API не поддерживает глобальные настройки — каждая конфигурация применяется к конкретному маршруту или бэкенду.

Кого затронет и как

Миграция затронет всех, кто использует Ingress-NGINX в production. Разработчики приложений могут столкнуться с изменением поведения маршрутизации и заголовков. Администраторам платформ придётся переписывать конфигурации и, возможно, обновлять инструменты CI/CD. Команды безопасности должны проверить, не полагаются ли политики доступа на недокументированные особенности Ingress-NGINX. Для российских компаний, использующих Kubernetes, миграция может совпасть с переходом на отечественные дистрибутивы, что добавляет сложности. Gateway API уже поддерживается такими решениями, как Deckhouse и SberCloud, но требуется тщательное тестирование.

Что будет дальше

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