Getting traffic from the internet into a Kubernetes cluster is one of the first real problems every team solves. For years the answer was Ingress. Today, the Kubernetes Gateway API offers a more powerful and more flexible alternative, and many controllers now support it.
This guide explains how Ingress and the Gateway API work, the key differences between them, and how to decide which one to use for new and existing clusters.
A Quick Refresher: How Traffic Reaches Pods
Inside a cluster, pods are reached through Services. A Service gives a stable address to a changing group of pods. To expose an application outside the cluster you can use a Service of type NodePort or LoadBalancer, but creating one cloud load balancer per application quickly becomes expensive and hard to manage.
Layer 7 routing solves this: one entry point that can route requests to many Services based on hostname or URL path. Both Ingress and the Gateway API provide this. For a full overview of cluster networking, read Kubernetes networking explained simply.
What Is Kubernetes Ingress?
Ingress is a Kubernetes API object that defines HTTP and HTTPS routing rules. A single Ingress resource can say, for example, that requests for shop.example.com go to the shop Service and requests for example.com/api go to the API Service. It also supports TLS termination using certificates stored in Secrets.
An Ingress resource does nothing by itself. You need an Ingress controller, such as Ingress-NGINX, Traefik, HAProxy, or a cloud provider's controller like the AWS Load Balancer Controller, to read the rules and configure a real proxy or load balancer.
Limitations of Ingress
- Limited features in the standard spec. Ingress covers host and path routing and TLS. Anything else, such as header-based routing, traffic splitting, rewrites, timeouts or rate limits, depends on controller-specific annotations.
- Annotations are not portable. Annotations for one controller rarely work with another, so switching controllers means rewriting configuration.
- HTTP-focused. Ingress was designed for HTTP and HTTPS. TCP, UDP and gRPC support varies by controller.
- One resource, many owners. The same object mixes infrastructure settings and application routes, which makes it hard to split responsibility between platform teams and developers.
The Ingress API is stable and still supported, but it is feature-frozen. New development in Kubernetes traffic management is happening in the Gateway API.
What Is the Kubernetes Gateway API?
The Gateway API is an official Kubernetes project (maintained by SIG Network) that defines a family of resources for managing traffic. Its core HTTP routing features reached general availability in 2023, and it is supported by many implementations including Envoy Gateway, Istio, Cilium, NGINX Gateway Fabric, Traefik, Kong, Contour and the major cloud providers' load balancer controllers.
Instead of one object, the Gateway API splits configuration across several resources, each matched to a role in the organisation.
GatewayClass
Defines a type of gateway and which controller implements it, similar to how a StorageClass defines a type of storage. Usually managed by the infrastructure provider or platform team.
Gateway
Represents an actual traffic entry point, such as a load balancer, with listeners for specific ports, protocols, hostnames and TLS certificates. Typically owned by the platform or cluster operations team.
Route resources
HTTPRoute, GRPCRoute, TLSRoute, TCPRoute and UDPRoute define how traffic is matched and forwarded to backend Services. Application teams usually own these in their own namespaces and attach them to a shared Gateway.
Ingress vs Gateway API: Key Differences
1. Role-oriented design
Ingress mixes infrastructure and routing in one object. The Gateway API separates them, so a platform team controls the Gateway and certificates while developers manage their own routes safely. This fits the self-service model behind Internal Developer Platforms.
2. Expressive routing without annotations
Header matching, query parameter matching, HTTP method matching, request and response header modification, redirects, URL rewrites and request mirroring are part of the standard Gateway API specification instead of vendor annotations.
3. Built-in traffic splitting
An HTTPRoute can send traffic to multiple backends with weights, for example 90% to the stable version and 10% to a new version. That makes canary and blue-green deployments possible with standard resources.
4. More protocols
The Gateway API covers HTTP, gRPC, TLS passthrough, TCP and UDP through dedicated route types, whereas Ingress is mainly HTTP and HTTPS.
5. Portability
Because more functionality lives in the standard spec, it is easier to move between implementations. Conformance tests show which features each implementation supports.
6. Cross-namespace control
The Gateway API explicitly controls which namespaces may attach routes to a Gateway and uses ReferenceGrant to allow safe cross-namespace references. This makes multi-team clusters more secure by design.
Gateway API and Service Meshes
The Gateway API was originally designed for north-south traffic (into the cluster). Through the GAMMA initiative, the same route resources can also describe east-west traffic between services inside the mesh. Istio, Linkerd and Cilium support this, which means teams can learn one routing API for both ingress and service-to-service traffic. Learn more in what is a service mesh and Istio vs Linkerd.
Should You Migrate from Ingress to the Gateway API?
Stay on Ingress for now if:
- You have simple host and path routing that works well.
- Your controller and tooling do not yet support the Gateway features you need.
- There is no pressing need for traffic splitting, multi-team ownership or non-HTTP protocols.
Choose or migrate to the Gateway API if:
- You are building a new cluster or platform.
- You rely heavily on controller-specific annotations and want portable configuration.
- Multiple teams share the same entry point and need clear ownership boundaries.
- You want progressive delivery with weighted traffic splitting.
- Your current Ingress controller is reaching end of life or end of support. For example, the Kubernetes project announced the retirement of the community Ingress-NGINX controller, which has pushed many teams to plan a move.
How to migrate safely
- Choose a Gateway API implementation and confirm it supports the features you use today.
- Use the ingress2gateway tool from the Kubernetes project to convert existing Ingress resources into Gateway and HTTPRoute resources as a starting point.
- Run the new Gateway alongside the existing Ingress controller, ideally on a separate load balancer.
- Test routes, TLS and headers, then shift DNS or traffic gradually.
- Remove the old Ingress resources once all traffic is flowing through the Gateway.
Manage both sets of resources in Git and roll them out through your pipeline, following the practices in our GitOps guide.
Best Practices
- Let the platform team own GatewayClasses and Gateways, and let application teams own Routes.
- Automate certificates with cert-manager, which supports the Gateway API.
- Restrict which namespaces can attach routes to shared Gateways.
- Monitor gateway latency, error rates and saturation as part of your SLOs; see SLOs, SLIs and error budgets.
- Put a CDN or web application firewall in front for caching and protection where it makes sense.
Conclusion
Ingress remains a simple, stable way to expose HTTP services, and it will keep working for many clusters. The Gateway API, however, is where Kubernetes traffic management is heading: role-based, more expressive, multi-protocol and portable across implementations. For new platforms, starting with the Gateway API is usually the better long-term choice, and existing clusters can migrate gradually with tooling like ingress2gateway.
