Миграция с Ingress на Gateway API

Last update: May 27 2026

Gateway API — это современная альтернатива Ingress. В Ingress функции балансировщика и управление правилами маршрутизации объединены в одном объекте Service типа Loadbalancer. В Gateway API для этого используются два отдельных объекта:

• Gateway – определяет сетевые точки входа и правила маршрутизации трафика к кластеру;
• HTTPRoute – определяет правила маршрутизации трафика к сервисам.

Такое разделение позволяет сделать инфраструктуру более удобной в обслуживании. Подробнее о различиях Ingress и Gateway API в подразделе Key Differences Between Ingress API и Gateway API инструкции Migrating from Ingress в документации Gateway API.

Принцип миграции

При работе c Ingress и Gateway API используются разные объекты Kubernetes. Основные объекты:

• Ingress — IngressClass и Ingress;
• Gateway API — GatewayClass, Gateway и HTTPRoute.

Для миграции нужно заменить объекты Ingress на объекты Gateway API.

Чтобы упростить миграцию, часть объектов можно преобразовать автоматически с помощью утилиты:

• ingress2gateway — официальная утилита. Преобразует объекты Ingress в объекты Gateway API. Например, объект Service типа Loadbalancer в объекты Gateway и HTTPRoute;
• или ingress2eg — неофициальная экспериментальная версия утилиты ingress2gateway. Дополнительно из аннотаций NGINX генерирует объекты, которые специфичны для Envoy Gateway CRD (Custom Resource Definition). Например, BackendTrafficPolicy и SecurityPolicy.

Объекты, которые нельзя преобразовать автоматически нужно добавить вручную. Например, объект GatewayClass.

Пример миграции с Ingress NGINX на Envoy Gateway

1. Проверьте квоты.
2. Установите Envoy Gateway.
3. Создайте объект EnvoyProxy.
4. Создайте объект GatewayClass.
5. Преобразуйте объекты Ingress в Gateway API.

1. Проверить квоты

Убедитесь, что в пуле выделена квота минимум на один публичный IP-адрес и облачный балансировщик нагрузки. Для этого посмотрите потребление квот облачной платформы.

2. Установить Envoy Gateway

Используйте инструкцию Установить Envoy Gateway.

3. Создать объект EnvoyProxy

1. Создайте yaml-файл envoyproxy.yaml с манифестом для объекта EnvoyProxy.

   Пример манифеста EnvoyProxy:

   apiVersion: gateway.envoyproxy.io/v1alpha1
   kind: EnvoyProxy
   metadata:
     name: custom-proxy-config
     namespace: default
   spec:
     provider:
       type: Kubernetes
       kubernetes:
         envoyDaemonSet: {}
         envoyService:
           externalTrafficPolicy: Cluster

   Здесь:

   • externalTrafficPolicy: Cluster указывает, что все ноды будут принимать участие в балансировке трафика;
   • envoyDaemonSet: {} указывает, что реплики Envoy будут запущены на всех нодах.

2. Примените манифест:

   kubectl apply -f envoyproxy.yaml

   Здесь envoyproxy.yaml — имя yaml-файла с манифестом для создания объекта EnvoyProxy.

3. Убедитесь, что объект EnvoyProxy создан:

   kubectl get envoyproxy -n default

4. Создать объект GatewayClass

Чтобы использовать HTTPRoutes, нужен GatewayClass, который будет связан с контроллером Envoy Gateway.

1. Создайте yaml-файл gatewayclass.yaml с манифестом для объекта GatewayClass.

   Пример манифеста GatewayClass:

   apiVersion: gateway.networking.k8s.io/v1
   kind: GatewayClass
   metadata:
     name: eg
   spec:
     controllerName: gateway.envoyproxy.io/gatewayclass-controller
     parametersRef:
       group: gateway.envoyproxy.io
       kind: EnvoyProxy
       name: custom-proxy-config
       namespace: default

2. Примените манифест:

   kubectl apply -f gatewayclass.yaml

   Здесь gatewayclass.yaml — имя yaml-файла с манифестом для создания объекта GatewayClass.

3. Убедитесь, что объект GatewayClass создан:

   kubectl get gatewayclass

5. Преобразовать объекты Ingress в Gateway API

Если вы используете NGINX с аннотациями, используйте утилиту ingress2eg.

ingress2gateway

1. Установите утилиту ingress2gateway.

2. Преобразуйте объекты Ingress в объекты Gateway API. Все изменения будут только выведены в консоли и не будут сразу применены. Например:

   ingress2gateway print -A --providers ingress-nginx > gateway-resources.yaml

   Здесь:

   • --providers ingress-nginx — флаг для контроллера, с которого вы мигрируете;
   • -A — флаг, который указывает, что смотреть манифесты Ingress нужно во всех пространствах имен (namespace);
   • gateway-resources.yaml — имя yaml-файла с манифестами для новых объектов.

3. Откройте сохраненный файл gateway-resources.yaml.

4. Если был сгенерирован манифест Gateway:

   4.1. В поле gatewayClassName замените nginx на eg.

   4.2. Если вы используете HTTPS, укажите путь до секрета с сертификатом домена.

   Пример манифеста Gateway для HTTPS-протокола:

   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: example-gateway
     namespace: default
   spec:
     gatewayClassName: eg
     listeners:
       - name: https
         hostname: "*.example.com"
         port: 443
         protocol: HTTPS
         allowedRoutes:
           namespaces:
             from: All
         tls:
           mode: Terminate
           certificateRefs:
             - name: wildcard-certname-tls
               namespace: secret-namespace
               kind: Secret

5. Создайте объекты, указанные в манифестах:

   kubectl apply -f gateway-resources.yaml

6. Убедитесь, что все объекты созданы:

   kubectl get gateways -A
   kubectl get httproutes -A

7. Убедитесь, что ваши сервисы доступны по новому IP-адресу, который автоматически назначен новому облачному балансировщику. IP-адрес балансировщика можно посмотреть в панели управления: в верхнем меню нажмите Продукты и выберите Облачные серверы → раздел Балансировщики → вкладка Балансировщики → карточка балансировщика.

ingress2eg

1. Установите ingress2eg.

2. Проверьте исходный объект Ingress c аннотациями NGINX.

   Пример объекта Ingress с аннотациями NGINX для ограничения скорости запросов и CORS:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: example-ingress-nginx
     namespace: default
     annotations:
       nginx.ingress.kubernetes.io/limit-rps: "10"
       nginx.ingress.kubernetes.io/enable-cors: "true"
       nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, OPTIONS"
       nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"
   spec:
     rules:
     - host: example.com
       http:
         paths:
         - path: /api
           pathType: Prefix
           backend:
             service:
               name: api-service
               port:
                 number: 80

3. Преобразуйте объекты Ingress в объекты Gateway API и сохраните их в файл gateway-resources.yaml:

   ingress2eg print --namespace default > gateway-resources.yaml

4. Откройте сохраненный файл gateway-resources.yaml.

5. В файле gateway-resources.yaml проверьте сгенерированные объекты. Утилита ingress2eg может сгенерировать объекты:

   • Gateway;
   • HTTPRoute;
   • объекты, которые специфичны для Envoy Gateway CRD (Custom Resource Definition). Например, BackendTrafficPolicy и SecurityPolicy.
   Пример объекта BackendTrafficPolicy, сформированного из аннотации limit-rps

     apiVersion: gateway.envoyproxy.io/v1alpha1
     kind: BackendTrafficPolicy
     metadata:
       name: rate-limit-policy
       namespace: default
     spec:
       targetRefs:
       - group: gateway.networking.k8s.io
         kind: HTTPRoute
         name: example-httproute
       rateLimit:
         type: Local
         local:
           rules:
           - clientSelectors:
             - sourceCIDR:
                 type: Distinct
                 value: 0.0.0.0/0
             limit:
               requests: 10
               unit: Second

   Пример объекта SecurityPolicy, сформированного из аннотаций CORS enable-cors, cors-allow-methods и cors-allow-origin

   apiVersion: gateway.envoyproxy.io/v1alpha1
   kind: SecurityPolicy
   metadata:
     name: cors-policy
     namespace: default
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: example-httproute
     cors:
       allowOrigins:
       - "https://example.com"
       allowMethods:
       - GET
       - POST
       - OPTIONS

6. Создайте объекты, указанные в манифестах:

   kubectl apply -f gateway-resources.yaml

7. Убедитесь, что все объекты созданы:

   kubectl get gateways -A
   kubectl get httproutes -A
   kubectl get backendtrafficpolicies -A
   kubectl get securitypolicies -A

8. Проверьте статус объектов BackendTrafficPolicy и SecurityPolicy:

   kubectl describe backendtrafficpolicy rate-limit-policy
   kubectl describe securitypolicy cors-policy

   В ответе статус появится в поле Status.Conditions. Например:

   Status:
     Conditions:
     - LastTransitionTime:  2025-04-05T10:30:22Z
       Message:           Policy applied successfully
       Reason:            Applied
       Status:            True
       Type:              Accepted
     - LastTransitionTime:  2025-04-05T10:30:22Z
       Message:           Policy is ready
       Reason:            Ready
       Status:            True
       Type:              Programmed
     ObservedGeneration:  1

9. Убедитесь, что ваши сервисы доступны по новому IP-адресу, который автоматически назначен новому облачному балансировщику. IP-адрес балансировщика можно посмотреть в панели управления: в верхнем меню нажмите Продукты и выберите Облачные серверы → раздел Балансировщики → вкладка Балансировщики → карточка балансировщика.