Ingress NGINX Migration: переход на Traefik

31 мая 2026 г.

#ingress#kubernetes#migration#nginx#traefik
Скриншот отчёта о миграции

Ingress NGINX Migration — инструмент, который анализирует ресурсы NGINX Ingress в Kubernetes и помогает спланировать миграцию на Traefik.

Возможности

Инструмент создаёт и отдаёт интерактивный HTML-отчёт. Для этого он:

  • анализирует все ресурсы Ingress в кластере Kubernetes или в указанных пространствах имён;

  • определяет аннотации контроллера Ingress NGINX и их совместимость с Traefik;

  • поддерживает как развёртывание внутри кластера, так и внешний доступ через kubeconfig;

  • формирует HTML-отчёт о миграции с отметкой времени, показывающий общее число ресурсов Ingress, сколько из них мигрируют автоматически, какие требуют ручного вмешательства, а также неподдерживаемые аннотации и частоту их использования;

  • предоставляет гибкую фильтрацию по классу контроллера, имени ingress-класса и пространству имён.

Поддерживаемые аннотации NGINX

Инструмент проверяет совместимость с распространёнными аннотациями контроллера Ingress NGINX, в том числе:

  • аутентификация (auth-type, auth-secret, auth-realm, auth-url, auth-signin и др.);

  • клиентская TLS-аутентификация (auth-tls-secret, auth-tls-verify-client);

  • SSL/TLS (force-ssl-redirect, ssl-redirect, ssl-passthrough);

  • перезапись путей (use-regex, rewrite-target, app-root);

  • редиректы (permanent-redirect, temporal-redirect, from-to-www-redirect и др.);

  • привязка сессий (affinity, session-cookie-*);

  • настройка бэкенда (service-upstream, backend-protocol, proxy-ssl-*);

  • таймауты прокси (proxy-connect-timeout);

  • CORS (enable-cors, cors-allow-*);

  • списки разрешённых IP (whitelist-source-range, allowlist-source-range);

  • пользовательские заголовки (custom-headers, upstream-vhost);

  • буферизация (proxy-request-buffering, proxy-body-size, proxy-buffering и др.);

  • ModSecurity (enable-modsecurity, enable-owasp-core-rules и др.) — только Traefik Hub.

Полный список аннотаций и их эквивалентов в Traefik приведён в документации Traefik.

Установка

Быстрая установка (рекомендуется)

curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | bash

Установить конкретную версию:

curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | TAG=v0.0.1 bash

Установить без sudo (в ~/bin):

curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | bash -s -- --no-sudo

Ручная загрузка

Скачайте подходящий для вашей платформы бинарник со страницы релизов.

Использование

USAGE:
   ingress-nginx-migration [global options] [command [command options]]

GLOBAL OPTIONS:
   --addr string              Адрес для отдачи отчёта (по умолчанию ":8080") [$ADDR]
   --kubeconfig string        Файл kubeconfig для подключения к кластеру [$KUBECONFIG]
   --namespaces string        Пространства имён для анализа (пусто — все) [$NAMESPACES]
   --ingress-class string     Имя ingress-класса контроллера [$INGRESS_CLASS]
   --controller-class string  Класс контроллера Ingress для анализа [$CONTROLLER_CLASS]
   --help, -h                 Показать справку
Tip
 Быстрый старт — запустите инструмент со своим kubeconfig: ingress-nginx-migration --kubeconfig ~/.kube/config.

Необходимые права

Инструменту нужны права только на чтение. Он рассчитан на запуск SRE и администраторами с доступом к кластеру через kubeconfig, но те же требования действуют и для запуска внутри кластера. Учётной записи нужны разрешения:

  • networking.k8s.io/v1 / ingressclasses — list, get, watch (на уровне кластера);

  • networking.k8s.io/v1 / ingresses — list, get, watch (на уровне пространств имён).

Note
 При указании конкретных пространств имён права требуются только для них; без указания — для всех. Инструмент использует informer-ы client-go и никогда не изменяет ресурсы кластера — все операции только на чтение.

Отправка отчёта

Инструмент включает необязательную возможность поделиться анонимной статистикой с Traefik Labs, чтобы команда Traefik понимала реальные сценарии использования NGINX Ingress. Чувствительные данные не передаются — только агрегированные счётчики, никогда конфигурации, имена ресурсов или пространств имён. Пример:

{
  "version": "v1.0.0",
  "ingressCount": 42,
  "compatibleIngressCount": 38,
  "unsupportedIngressCount": 4,
  "unsupportedIngressAnnotations": {
    "nginx.ingress.kubernetes.io/custom-annotation": 2
  }
}

E2E-тесты

E2E-тесты поднимают кластер k3s через testcontainers и разворачивают контроллеры Traefik и NGINX Ingress для проверки совместимости аннотаций. Нужна переменная TRAEFIK_IMAGE с образом Traefik, включающим провайдер kubernetesIngressNginx:

TRAEFIK_IMAGE=traefik/traefik:v100.0.0 make e2e-test

Чтобы переиспользовать кластер, задайте E2E_REUSE_CLUSTER=true (создание с нуля — ~60–90 с, переиспользование — ~20 с).

Исходный код: github.com/traefik/ingress-nginx-migration.

Похожее

© 2026 meganuke