Migrating from Ingress to Gateway API

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

• Gateway – defines network entry points and traffic routing rules for a cluster;
• HTTPRoute – defines traffic routing rules to services.

This separation makes infrastructure easier to maintain. For more details on the differences between Ingress and Gateway API, see the Key Differences Between Ingress API and Gateway API guide in the Migrating from Ingress section of 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 — an official utility. Converts Ingress objects to Gateway API objects. For example, a Service object of type Loadbalancer to Gateway and HTTPRoute objects;
• or ingress2eg — an unofficial experimental version of the ingress2gateway utility. Additionally, it generates objects from NGINX annotations that are specific to Envoy Gateway CRD (Custom Resource Definition). For example, BackendTrafficPolicy and SecurityPolicy.

Objects that cannot be converted automatically must be added manually. For example, the 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 to Gateway API.

1. Check quotas

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

2. Install Envoy Gateway

Follow the instructions on how to install Envoy Gateway.

3. Create an EnvoyProxy object

1. Create a yaml file envoyproxy.yaml with the 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 indicates that all nodes will participate in traffic balancing;
   • envoyDaemonSet: {} indicates that Envoy replicas will be launched 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 yaml file gatewayclass.yaml with the 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 utility.

ingress2gateway

1. Install the ingress2gateway utility.

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 — a flag for the controller you are migrating from;
   • -A — a flag indicating that Ingress manifests should be looked up in all namespaces (namespaces);
   • gateway-resources.yaml — the name of the yaml file containing manifests for the new objects.

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

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. Ensure that your services are available via the new IP address that was 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 to Gateway API objects and save them to the gateway-resources.yaml file:

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

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

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

   • Gateway;
   • HTTPRoute;
   • objects specific to Envoy Gateway CRD (Custom Resource Definition). For example, BackendTrafficPolicy and SecurityPolicy.
   BackendTrafficPolicy object example formed 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

   SecurityPolicy object example formed from 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. Ensure that your services are available via the new IP address that was 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.