The Kubernetes Gateway API is the successor to Ingress: a family of Kubernetes objects you use to route traffic into the cluster from outside and between services. The core objects GatewayClass, Gateway, and HTTPRoute have been stable since version 1.0 (October 2023), and the current version is 1.6.3. The Kubernetes project now explicitly recommends using Gateway instead of Ingress. Ingress stays available but is no longer being developed. Unlike Ingress, the Gateway API is not built into Kubernetes: you install its object types as CRDs and need a controller that implements them.
I run Kubernetes clusters in production, on k3s with Traefik as the ingress controller, and I wrote the Kubernetes practical guide published by Rheinwerk (2024). In this article I show how the Gateway API is structured, how it differs from Ingress, and why the question of switching became more urgent in 2026. You can find all my articles on Kubernetes collected on the Kubernetes page.
What the Gateway API is
The Kubernetes documentation describes the Gateway API as "a family of API kinds that provide dynamic infrastructure provisioning and advanced traffic routing". The most important idea behind it is the separation of roles. The objects are cut along three roles that exist in many organizations anyway:
A GatewayClass says which controller is responsible, for example Traefik, Envoy Gateway, or a cloud provider's controller. A Gateway is a concrete entry point with listeners, such as HTTPS on port 443 for a domain. Routes attach to a Gateway and describe which traffic goes to which Service. The application team can change its HTTPRoute without touching the Gateway, and the cluster team decides from which namespaces routes may be attached at all.
Gateway API vs Ingress
I explained Ingress in detail in Kubernetes Ingress and Ingress Controllers. It bundles entry point and routing into one object and, by default, only handles host and path. Everything beyond that, such as redirects, rewrites, or weighting between two versions, lives in annotations, and those differ from controller to controller. If you switch controllers, you rewrite the annotations.
The documentation is unambiguous about the status of Ingress: "The Ingress API has been frozen." It is generally available and the project has no plans to remove it, but it will not get any further changes. So you do not have to rebuild anything in a hurry. New features, however, only go into the Gateway API.
Which parts are stable
The Gateway API is published in two channels. The Standard channel contains what is considered stable; the Experimental channel contains new features that may still change. For production, use the Standard channel. Key steps in recent versions according to the release notes:
Which version you can use depends not only on the CRDs but also on which version your controller supports. That is the point you should check first before any rollout.
A Gateway and an HTTPRoute
Here is a minimal example: a Gateway accepts HTTP on port 80, and an HTTPRoute sends everything under shop.example.com to the Service shop, with 10 percent of requests going to a new version.
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web
namespace: infra
spec:
gatewayClassName: example # name of your controller's GatewayClass
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: shop
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
hostnames:
- shop.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: shop
port: 80
weight: 90
- name: shop-new
port: 80
weight: 10
kubectl get gatewayclass shows you the name of the GatewayClass. Whether the Gateway was accepted is in its status: kubectl describe gateway web -n infra shows under Conditions whether it is Accepted and Programmed, and kubectl describe httproute shop -n shop shows whether the route is attached to the Gateway. If one of these conditions is missing, the cause is almost always a wrong name in parentRefs or allowedRoutes that do not permit the namespace.
The weighting in backendRefs is exactly the kind of feature you would need a controller annotation for with Ingress. Here it is part of the standard.
Why the question is more urgent in 2026: the end of ingress-nginx
Many clusters use ingress-nginx, the Kubernetes community's ingress controller. In November 2025, SIG Network and the Security Response Committee announced its retirement: best-effort maintenance until March 2026, then no more releases, no bug fixes, and no updates for security vulnerabilities. The repository is now archived. Existing installations keep running, but just like with the archived Kubernetes Dashboard, nobody fixes new vulnerabilities any more.
The project itself recommends two paths: switch to the Gateway API, which it calls "the modern replacement for Ingress", or, if you must stay with Ingress, use a different ingress controller. So if you run ingress-nginx, you have to change something anyway. Then it is worth checking whether to go straight to the Gateway API instead of only swapping the controller.
For translating existing Ingress objects there is ingress2gateway, a tool from the Gateway API project (currently v1.2.0). It translates Ingress objects and some provider-specific resources into Gateway API objects. It explicitly does not just copy annotations over; you have to check yourself what is hidden in them in your setup. The result is a starting point, not a finished manifest.
Gateway API with k3s and Traefik
k3s ships with Traefik v3, and Traefik supports the Gateway API as an option. According to the k3s documentation, you enable it with a HelmChartConfig:
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
name: traefik
namespace: kube-system
spec:
valuesContent: |-
providers:
kubernetesGateway:
enabled: true
The documentation names two limitations (as of October 14, 2026): the bundled Traefik is compatible with Gateway API v1.4, and for experimental resources such as TCPRoute you need the experimental CRDs of that version plus the option providers.kubernetesGateway.experimentalChannel=true in the Traefik values. And before the k3s releases of April 2026, the Gateway API CRDs were removed if Traefik was disabled after having been enabled. If you run an older k3s version, do not disable Traefik while Gateway resources exist in the cluster. The standalone Traefik documentation lists support for Gateway API v1.6.3 for the current Traefik version. Which Traefik version is inside your k3s is listed in the release notes of your k3s version.
When you should switch
My assessment, consistent with what I wrote in the Ingress article:
- You run ingress-nginx: plan the switch now. Consider the Gateway API as the target, especially if you use many annotations.
- New cluster with several teams: start with the Gateway API. The separation between Gateway and routes pays off as soon as more than one team maintains routes.
- One application, one domain, TLS, a maintained controller: Ingress is still enough. You do not have to rebuild anything as long as annotations do not get in your way.
Frequently asked questions
Does the Gateway API replace Ingress?
Yes, it is designed as the successor, and the Kubernetes project recommends Gateway instead of Ingress. Ingress is not being removed, though: it is frozen, stays stable and available, and just does not get new features.
Is the Gateway API included in Kubernetes?
Not built in. The object types are CRDs that you install, and a controller such as Traefik, Envoy Gateway, or your cloud provider's controller implements them. Some distributions and controllers ship the CRDs.
Is the Gateway API production ready?
The core objects GatewayClass, Gateway, and HTTPRoute have been stable since v1.0 in October 2023, GRPCRoute since v1.1, TLSRoute since v1.5, and TCPRoute and UDPRoute since v1.6. For production, use the Standard channel and check which version your controller supports.
What happens to ingress-nginx?
ingress-nginx is retired: since March 2026 there have been no releases and no security updates, and the repository is archived. Existing installations keep running but should be moved to a different controller or to the Gateway API.
What is the difference between Gateway and GatewayClass?
The GatewayClass defines which controller is responsible, comparable to the IngressClass. The Gateway is a concrete entry point of that controller with ports, protocols, and certificates. The applications' routes then attach to a Gateway.
Where to go next
If you are missing the basics, read Kubernetes Ingress and Ingress Controllers and Kubernetes Service Types Explained first, because the Gateway API also routes to Services, never directly to pods. If you want to control traffic not only into the cluster but also inside it, continue with Kubernetes Network Policy Explained.
If you are facing this decision and want a second opinion on your cluster, for example as a cluster review, my page Kubernetes Expert: Consulting and Operations shows what I offer.
I explain Ingress and Services in detail in my Kubernetes Practical Guide (Rheinwerk Computing). The full specification is on the Gateway API project website, and the Kubernetes project's overview is in the Gateway API documentation.
