Migrating from Ingress to Gateway API

Last update: October 05 2026Open in Markdown

Gateway API is a modern alternative to Ingress. In Ingress, the functions of a load balancer and routing rule management are combined in a single Service object of the LoadBalancer type. In Gateway API, two separate objects are used for this:

• Gateway — defines network entry points and traffic routing rules to the cluster;
• HTTPRoute — defines traffic routing rules to services.

This separation makes the infrastructure easier to maintain. Learn more about the differences between Ingress and Gateway API in the Key Differences Between Ingress API and Gateway API section of the Migrating from Ingress guide in the Gateway API documentation.

Migration principle

When working with Ingress and Gateway API, different Kubernetes objects are used. Main objects:

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

To migrate, you need to replace Ingress objects with Gateway API objects.

To simplify migration, some objects can be converted automatically using a utility:

• ingress2gateway is the official tool. It converts Ingress objects into Gateway API objects. For example, a LoadBalancer type Service object into Gateway and HTTPRoute objects;
• or ingress2eg — an unofficial experimental version of the ingress2gateway tool. Additionally, it generates objects specific to Envoy Gateway CRD (Custom Resource Definition) from NGINX annotations. For example, BackendTrafficPolicy and SecurityPolicy.

Objects that cannot be converted automatically must be added manually. For example, a GatewayClass object.

Migration example from Ingress NGINX to Envoy Gateway

1. Check quotas.
2. Install Envoy Gateway.
3. Create an EnvoyProxy object.
4. Create a GatewayClass object.
5. Convert Ingress objects into Gateway API objects.

1. Check quotas

Make sure that the pool has an allocated quota for at least one public floating IP address and a cloud load balancer. To do this, view the cloud platform quota consumption.

2. Install Envoy Gateway

Use the instructions in Install Envoy Gateway.

3. Create an EnvoyProxy object

1. Create an envoyproxy.yaml YAML file with a manifest for the EnvoyProxy object.

   EnvoyProxy manifest example:

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

   Where:

   • externalTrafficPolicy: Cluster specifies that all nodes will participate in traffic load balancing;
   • envoyDaemonSet: {} specifies that Envoy replicas will run on all nodes.

2. Apply the manifest:

   kubectl apply -f envoyproxy.yaml

   Here, envoyproxy.yaml is the name of the YAML file with the manifest for creating the EnvoyProxy object.

3. Ensure that the EnvoyProxy object is created:

   kubectl get envoyproxy -n default

4. Create a GatewayClass object

To use HTTPRoutes, you need a GatewayClass that will be associated with the Envoy Gateway controller.

1. Create a gatewayclass.yaml YAML file with a manifest for the GatewayClass object.

   GatewayClass manifest example:

   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. Apply the manifest:

   kubectl apply -f gatewayclass.yaml

   Here, gatewayclass.yaml is the name of the YAML file with the manifest for creating the GatewayClass object.

3. Ensure that the GatewayClass object is created:

   kubectl get gatewayclass

5. Convert Ingress objects to Gateway API

If you are using NGINX with annotations, use the ingress2eg tool.

ingress2gateway

1. Install the ingress2gateway tool.

2. Convert Ingress objects to Gateway API objects. All changes will only be printed to the console and will not be applied automatically. For example:

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

   Where:

   • --providers ingress-nginx — flag for the controller you are migrating from;
   • -A — flag indicating that Ingress manifests should be checked across all namespaces;
   • gateway-resources.yaml — name of the YAML file with manifests for the new objects.

3. Open the saved gateway-resources.yaml file.

4. If a Gateway manifest was generated:

   4.1. In the gatewayClassName field, replace nginx with eg.

   4.2. If you are using HTTPS, specify the path to the secret containing the domain certificate.

   Gateway manifest example for HTTPS protocol:

   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. Create the objects specified in the manifests:

   kubectl apply -f gateway-resources.yaml

6. Ensure that all objects are created:

   kubectl get gateways -A
   kubectl get httproutes -A

7. Make sure that your services are available at the new IP address automatically assigned to the new cloud load balancer. You can view the load balancer IP address in the Control panel: in the top menu, click Products and select Cloud Servers → Load Balancers section → Load Balancers tab → load balancer card.

ingress2eg

1. Install ingress2eg.

2. Check the original Ingress object with NGINX annotations.

   Example of an Ingress object with NGINX annotations for rate limiting and 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. Convert Ingress objects into Gateway API objects and save them to the gateway-resources.yaml file:

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

4. Open the saved gateway-resources.yaml file.

5. In the gateway-resources.yaml file, check the generated objects. The ingress2eg tool can generate the following objects:

   • Gateway;
   • HTTPRoute;
   • objects specific to Envoy Gateway CRD (Custom Resource Definition). For example, BackendTrafficPolicy and SecurityPolicy.
   Example of a BackendTrafficPolicy object generated from the limit-rps annotation

     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

   Example of a SecurityPolicy object generated from the CORS annotations enable-cors, cors-allow-methods, and 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. Create the objects specified in the manifests:

   kubectl apply -f gateway-resources.yaml

7. Ensure that all objects are created:

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

8. Check the status of BackendTrafficPolicy and SecurityPolicy objects:

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

   In the response, the status will appear in the Status.Conditions field. For example:

   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. Make sure that your services are available at the new IP address automatically assigned to the new cloud load balancer. You can view the load balancer IP address in the Control panel: in the top menu, click Products and select Cloud Servers → Load Balancers section → Load Balancers tab → load balancer card.