Why Migrate from Ingress to Gateway API?

by Jan Bosmans

First, you might ask yourself why you’d even migrate away from the Ingress API, and what the Gateway API is anyway.

I first learned about this because it was a hot topic at KubeCon 2025 in London.

It’s important to note that the Ingress API will be deprecated in 2027 due to its limited flexibility and scalability for modern traffic management. If you’re preparing for the CKA exam now or planning to take it in the coming months, be aware that the Gateway API is already a required topic. It offers a more robust and extensible alternative for managing ingress traffic in Kubernetes.

It’s also worth noting that Istio ambient. The next generation of the Istio service mesh is standardizing on the Gateway API. As a matter of fact, all SIG-Network projects are standardising around Gateway API.

So, that’s three good reasons. Another important one is that the core Ingress API is very limited, as it only supports HTTP routing. In case you need more advanced features, you’re forced to use vendor-specific annotations, which is not a great experience.

The Gateway API, on the other hand, separates network and application configurations into different resources.

  • GatewayClass: Typically managed by the Platform Team, this defines the controller to be used, like NGINX, Traefik, Istio, or Cilium.

    Example:

    apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx-gateway-class
spec:
  controllerName: "nginx.org/gateway-controller"

     

  • Gateway: Typically managed by the Platform Team. Ports, Protocals and TLS configurations are usually managed in this resource.

    Example:

    apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: nginx-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: default

     

  • HTTPRoute: Detailed routing rules, like path-based routing, are configured here. This resource would typically be managed by the application teams.

    Example of Path-Based Routing: This HTTPRoute sends traffic for /api to one service and all other traffic to another service.

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-route
  namespace: default
spec:
  parentRefs:
  - name: my-gateway
    namespace: default
  hostnames:
  - "[www.myapp.com](https://www.myapp.com)"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: my-api-service
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: my-app-service
      port: 80

     

This separation of resources enables role-based management. This would, for example, prevent an application developer from making changes to critical network settings and breaking other applications.

What to Look Out for When Migrating

It’s important to select the right Gateway API controller for your needs. You can find an overview in the official documentation: https://gateway-api.sigs.k8s.io/implementations/

Most of you will be migrating away from NGINX Ingress. The tricky part here is that NGINX Ingress happens to have a lot of annotations, 118 to be more precise. You should make sure that all the functionality of these annotations is available before you migrate.

The ingress2gateway tool is a great help. It can translate NGINX Ingress annotations to HTTPRoute rules if they’re available. You can find the tool here: https://github.com/kubernetes-sigs/ingress2gateway When navigating the ingress2gateway project, I noted that many NGINX Ingress annotations still lack an equivalent implementation in the Gateway API. This is an important consideration, as the project is actively being developed to handle a broader range of functionalities. While this work is ongoing, a significant amount of effort remains to be done.

Finally, since the Gateway API has a role-based setup, make sure you use it!

Menu