Ingress and Gateway API¶
Status: AI draft, 2026-11-16. Not yet verified by me. The Ingress commands were run on a local kind cluster (Kubernetes 1.37) with no ingress controller installed, and pod addresses are rewritten to example ranges; the Gateway API parts are from the documentation and were not run.
In one line¶
Ingress and Gateway API describe HTTP routing into the cluster (hostnames, paths, TLS) as Kubernetes objects; a separate controller reads them and configures a real proxy or cloud load balancer. Ingress is frozen and the community ingress-nginx controller was retired in March 2026; Gateway API is the recommended replacement, with separate objects for the platform team and app teams.
The plain idea¶
A Service gives a stable address for a set of pods, but it works at layer 4: it forwards connections, it does not read HTTP (Services and DNS, Layers and encapsulation). To send example.com/api to one app and example.com/ to another, and to terminate TLS once at the edge, you need a layer-7 reverse proxy in front of the Services (Load balancers and proxies).
Kubernetes splits this into two parts:
- The rules, written as API objects: an
Ingress, or Gateway API'sGatewayandHTTPRoute. - A controller that watches those objects and configures a proxy (an NGINX, Envoy or HAProxy deployment in the cluster) or a cloud load balancer to match.
Without a controller, the rules are just stored text: nothing listens and nothing routes.
How it works¶
The request path¶
flowchart TD
C["Client: https://www.example.com/api"] --> LB["Cloud load balancer<br/>or node port"]
LB --> P["Proxy pods run by the controller:<br/>TLS ends here, host and path matched"]
P --> S1["Service api"]
P --> S2["Service web"]
S1 --> E["Pod endpoints"]
W["Controller watches Ingress or<br/>HTTPRoute, Services, EndpointSlices"] -.->|"writes proxy config"| P
Many controllers send traffic straight to pod IPs from the EndpointSlices, skipping the Service's virtual IP. On AWS, the Load Balancer Controller does the same with an ALB and no in-cluster proxy at all (AWS Load Balancer Controller).
The Ingress object¶
| Field | Meaning |
|---|---|
ingressClassName |
Which controller should handle it. An IngressClass object names the controller. |
rules[].host |
Hostname to match (the HTTP Host header or TLS SNI). |
rules[].http.paths[] |
A path, a pathType (Exact, Prefix or ImplementationSpecific), and a backend Service and port. |
tls[] |
Hostnames and a secretName holding the certificate and key, in the same namespace (TLS and certificates). |
defaultBackend |
Where requests that match no rule go. |
Anything beyond host, path and TLS (redirects, rewrites, timeouts, header changes, canary weights) is done with controller-specific annotations, so an Ingress written for one controller rarely works unchanged on another.
Gateway API¶
Gateway API is a set of CRDs installed on top of Kubernetes. It splits the Ingress into objects owned by different people:
flowchart TD
GC["GatewayClass: which controller<br/>(infrastructure provider)"] --> G["Gateway: listeners, ports, hostnames,<br/>TLS certificates (platform team)"]
G --> R1["HTTPRoute in namespace team-a<br/>(app team)"]
G --> R2["HTTPRoute in namespace team-b<br/>(app team)"]
R1 --> S1["Service web, weight 90"]
R1 --> S2["Service web-canary, weight 10"]
R2 --> S3["Service api"]
- GatewayClass: the kind of load balancer, and which controller implements it.
- Gateway: one actual entry point. Its listeners say which ports, protocols and hostnames it accepts, where its certificates are, and which namespaces' routes may attach (
allowedRoutes). - HTTPRoute: matches on path, headers, query parameters and method, can redirect, rewrite and change headers, and splits traffic by weight between backends. These are in the standard API, not annotations.
- GRPCRoute, TLSRoute, TCPRoute and UDPRoute cover other protocols.
- ReferenceGrant: lets a route or Gateway refer to a Service or Secret in another namespace only when that namespace allows it.
- Routes report back in
status.parents[].conditions:AcceptedandResolvedRefssay whether the Gateway took the route and whether its backends exist.
Where things stand¶
- The Ingress API is frozen. It stays generally available and the project has no plans to remove it, but it gets no new features, and the Kubernetes documentation recommends Gateway instead.
- The community ingress-nginx controller has been retired. Kubernetes SIG Network announced in November 2025 that best-effort maintenance would end in March 2026, with no further releases, bug fixes or security updates after that. Existing installations keep working, unpatched. This is the controller most people mean by "nginx ingress"; it is a different project from NGINX's own controller.
- Most proxy and cloud vendors implement Gateway API, and some also read Ingress, which eases a gradual move.
| Ingress | Gateway API | |
|---|---|---|
| Status | Frozen, still supported | Actively developed |
| Objects | One object per app | GatewayClass, Gateway, routes, per role |
| Ownership | App team writes everything, including TLS | Platform team owns Gateways; app teams own routes |
| Advanced routing | Controller-specific annotations | Standard fields: header matches, weights, rewrites |
| Protocols | HTTP and HTTPS | HTTP, gRPC, TLS, TCP, UDP |
| Cross-namespace | Not supported | Explicit, with allowedRoutes and ReferenceGrant |
| Portability | Low once annotations are used | Higher, with a conformance test suite |
A concrete example¶
sample-app has a website and an API on www.example.com, with a canary of the new version.
- Platform team: one Gateway named
publicin namespaceinfra, listening on 443 with thewww.example.comcertificate, allowing routes from namespaces labelledexposed: "true". - App team, in their own namespace:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: sample-app
namespace: team-a
spec:
parentRefs:
- name: public
namespace: infra
hostnames: ["www.example.com"]
rules:
- matches:
- path: { type: PathPrefix, value: /api }
backendRefs:
- { name: sample-app-api, port: 8080 }
- backendRefs:
- { name: sample-app-web, port: 80, weight: 90 }
- { name: sample-app-web-canary, port: 80, weight: 10 }
Moving the canary to 50% is a one-line change the app team can make, without touching the Gateway or its certificate (Deployment strategies).
Why not just...?¶
- ...give every app a
type: LoadBalancerService? One cloud load balancer per app costs money each, gives you no path or host routing, and spreads TLS certificates across every app. One shared entry point with rules is cheaper and easier to audit. - ...keep running ingress-nginx, since it still works? It works, but any vulnerability found from now on stays unfixed, and it sits on the internet edge. Plan the move to a maintained controller, preferably through Gateway API.
- ...switch from Ingress to Gateway API by converting the YAML? The basic rules translate directly, but every annotation has to be mapped by hand to a Gateway API field or the new controller's own policy objects. Run both side by side and move hostnames one at a time.
Commands to know¶
An Ingress created on a cluster with no ingress controller:
$ kubectl create ingress web -n demo --rule="web.example.com/*=web:80" --rule="web.example.com/api*=web:80"
ingress.networking.k8s.io/web created
$ kubectl get ingress web -n demo
NAME CLASS HOSTS ADDRESS PORTS AGE
web <none> web.example.com 80 1s
$ kubectl get ingressclass
No resources found
$ kubectl describe ingress web -n demo
...
Ingress Class: <none>
Rules:
Host Path Backends
---- ---- --------
web.example.com
/ web:80 (10.244.0.5:80,10.244.0.6:80)
/api web:80 (10.244.0.5:80,10.244.0.6:80)
Events: <none>
The object is valid and describe even resolves the backends, but ADDRESS stays empty and there are no events, because nothing is watching it. That is the signature of a missing controller or a wrong class. A /* in --rule becomes pathType: Prefix; without it, Exact.
Gateway API objects only exist once their CRDs are installed:
$ kubectl api-resources | grep -i gateway || echo "(no gateway resources)"
(no gateway resources)
| Command | What it does |
|---|---|
kubectl get ingress -A |
Every Ingress, its class and its address. |
kubectl get ingressclass |
Installed controllers; one may be marked default. |
kubectl get gatewayclass,gateway -A |
Gateway API entry points and whether they are programmed. |
kubectl get httproute -A |
Routes and the Gateways they attach to. |
kubectl describe httproute <name> |
Accepted and ResolvedRefs conditions with reasons. |
kubectl logs -n <controller-ns> deploy/<controller> |
Why the controller rejected or ignored something. |
curl -v --resolve www.example.com:443:<lb-ip> https://www.example.com/api |
Test routing and TLS before DNS points at the load balancer (curl -v line by line). |
How it breaks¶
| Symptom | Layer | Check | Likely cause |
|---|---|---|---|
ADDRESS empty, no events |
Controller | kubectl get ingressclass; controller pods |
No controller, or ingressClassName names one that is not installed |
| 404 from the proxy | Routing rules | Host and path in the rule vs the request | Host header does not match, or Exact where Prefix was meant |
| 503 from the proxy | Backends | kubectl get endpointslices -l kubernetes.io/service-name=<svc> |
Service has no ready pods (Probes and graceful shutdown) |
| Browser shows the controller's default certificate | TLS | tls.secretName, Secret namespace |
Secret missing, in another namespace, or host not listed under tls.hosts |
| HTTPRoute ignored | Attachment | status.parents conditions |
Wrong parentRefs, namespace not allowed by the listener's allowedRoutes, or hostname mismatch |
ResolvedRefs: False |
Cross-namespace reference | ReferenceGrant in the target namespace | Backend in another namespace without a ReferenceGrant |
| Behaviour changed after a controller migration | Annotations | Old annotations | The new controller ignores the old controller's annotations |
Interview questions¶
1. What is the difference between an Ingress and an ingress controller?
Answer
- The Ingress is an API object: host, path and TLS rules.
- The controller is software that watches Ingresses and configures a proxy or cloud load balancer.
- Without a controller the object does nothing;
ingressClassNamepicks which controller handles it.
2. Why is Gateway API replacing Ingress?
Answer
- Ingress only standardises host, path and TLS; everything else is non-portable annotations.
- Gateway API standardises header matching, weights, rewrites, and protocols beyond HTTP.
- It separates roles: platform teams own Gateways and certificates, app teams own routes, with explicit cross-namespace permission.
3. Name the main Gateway API objects and who typically owns each.
Answer
- GatewayClass: infrastructure provider; which controller.
- Gateway: platform or cluster operators; listeners, ports, TLS, which namespaces may attach.
- HTTPRoute (and other routes): application teams; matches and backends.
- ReferenceGrant: owners of the target namespace, allowing cross-namespace references.
4. What happened to ingress-nginx, and what would you do about a cluster still using it?
Answer
- Kubernetes SIG Network retired it: best-effort maintenance ended in March 2026, with no releases or security fixes after.
- Existing installs keep working but stay unpatched at the internet edge.
- Inventory Ingresses and annotations, choose a maintained controller (ideally via Gateway API), run both side by side, move hosts one at a time.
5. An Ingress returns 503 for every request. How do you debug it?
Answer
- The proxy is reached and the rule matched, so look at the backend.
- Check the Service's EndpointSlices: no ready endpoints means failing readiness probes or a wrong selector.
- Check the Service port in the rule matches the Service's port, then the controller's logs.
6. How would you route 10% of traffic to a new version?
Answer
- Gateway API: two
backendRefsin an HTTPRoute with weights 90 and 10. - Ingress: only through controller-specific annotations, or a service mesh (Traffic management).
- Watch error rate and latency per version before raising the weight.
7. Why put TLS termination at the ingress layer, and what are the trade-offs?
Answer
- One place to manage certificates and TLS settings; apps speak plain HTTP inside.
- Traffic between proxy and pod is then unencrypted unless re-encrypted or covered by mesh mTLS (mTLS and authorization).
- Certificates live in Secrets, so access to that namespace must be tight.
Try it¶
Step 1. On a kind cluster with any Service (here web in namespace demo), create an Ingress.
kubectl create ingress try-web -n demo --rule="try.example.com/*=web:80"
Step 2. Predict the ADDRESS and the events, then check. Explain why.
kubectl get ingress try-web -n demo
kubectl describe ingress try-web -n demo | tail -3
kubectl get ingressclass
Step 3. Look up what pathType values mean, then clean up.
kubectl explain ingress.spec.rules.http.paths.pathType
kubectl delete ingress try-web -n demo
Zoom out¶
Ingress and Gateway API are the cluster's version of the reverse proxy (Nginx as a reverse proxy), with the configuration written as API objects that a controller reconciles. On AWS the same objects can drive an ALB directly (ALB and NLB), and a service mesh extends the same routing ideas to traffic between services (Why a mesh).
Sources¶
- Kubernetes documentation: Ingress
- Kubernetes documentation: Ingress controllers
- Kubernetes documentation: Gateway API
- Gateway API: API overview
- Gateway API: HTTPRoute
- Gateway API: ReferenceGrant
- Gateway API: troubleshooting and status conditions
- Kubernetes blog: Ingress NGINX retirement, what you need to know (2025-11-11)