Complete Guide to Kubernetes Ingress
Configure and troubleshoot Kubernetes Ingress. Covers controllers, TLS with cert-manager, path routing, annotations, and the move to Gateway API.
Introduction
You’re running three services behind one domain — an API, a web frontend, and an admin panel — and each needs HTTPS. A dedicated cloud load balancer per service works, but now you’ve got three public IPs, three TLS setups, and no single place to manage routing. Kubernetes Ingress exists for exactly this: one entry point into the cluster that fans requests out to many services based on hostnames and paths.
This guide walks through installing a controller, writing routing rules, terminating TLS with cert-manager, tuning behavior with annotations, and debugging the errors you’ll actually hit in production. It also covers where Ingress stands today: the ingress-nginx controller has been retired and Gateway API is the designated successor, so we’ll look at what that means for new and existing clusters.
Quick Answer
An Ingress is a set of L7 routing rules — host and path mapped to a Service — that does nothing until an Ingress controller is running in the cluster. To get traffic flowing: install a maintained controller (Traefik, HAProxy, or your cloud provider’s), set spec.ingressClassName on every Ingress, and let cert-manager issue the TLS certificates. On a brand-new cluster, evaluate Gateway API first — that’s where upstream investment is going.
The rest of this guide is the long version: install, route, terminate TLS, tune, and debug.
What Is Ingress?
Ingress is a Kubernetes resource that manages external HTTP and HTTPS access to services inside the cluster. Three pieces matter:
- Ingress resource: a set of routing rules (host, path, backend service) stored in the API server.
- Ingress controller: a proxy daemon — NGINX, Traefik, HAProxy, Envoy — that watches Ingress resources and turns them into live proxy configuration.
- IngressClass: a cluster-scoped resource that binds an Ingress to a specific controller, which is what lets several controllers coexist in one cluster.
Without a controller, an Ingress resource is just data sitting in etcd. Nothing reacts to it, which is also why a missing ingressClassName fails silently — no controller claims the object.
When to Use Ingress
Ingress is the right tool when:
- Several HTTP services share one domain or a handful of domains.
- You want TLS termination centralized at the edge instead of per-service.
- You need host-based or path-based routing (
api.example.comvsapp.example.com/api). - You want L7 controls at the edge — rate limiting, URL rewrites, canary splits, basic auth — without baking them into each app.
Skip it when:
- A single
LoadBalancerService covers the need. Adding a proxy layer for one app buys you nothing. - You need raw TCP/UDP routing — Ingress is HTTP/HTTPS only (use
LoadBalanceror the controller’s TCP/UDP passthrough config). - Your service mesh already handles north-south traffic through its own gateway.
- You’re building a new cluster — evaluate Gateway API first, because that’s where upstream Kubernetes is investing.
How Ingress Works
Here’s the path a request takes through a typical setup:
Two things about this flow are worth internalizing. First, the Ingress resource doesn’t forward anything — the controller subscribes to Ingress, Service, and Endpoint changes in the API server, regenerates its proxy config, and reloads. Second, routing targets the Service’s endpoints, not the Ingress. If your pods scale from 2 to 20, the controller picks up the new endpoints on its own; you never touch the Ingress object.
That split between “rules” and “enforcer” is also the source of most confusion: a broken route can live in the Ingress (bad host/path), in the Service (wrong port, wrong selector), or in the controller (class mismatch, missing flag). The troubleshooting section is ordered by that exact chain.
Choosing an Ingress Controller
Context that changes the decision in 2026: the Kubernetes project announced the retirement of ingress-nginx, the community controller this guide — and most of the internet — is built around. Best-effort maintenance ran until March 2026; there are no new releases, bug fixes, or security patches since then, though the repo and existing deployments keep working.
Your current clusters aren’t broken because of it — but you shouldn’t install ingress-nginx on a new cluster without a migration plan.
| Controller | Status | Good fit when |
|---|---|---|
| ingress-nginx | Retired (unmaintained since Mar 2026) | Already deployed; plan a move |
| Traefik | Active | Kubernetes-native, dynamic config, Gateway API support |
| HAProxy Ingress | Active | High-throughput L7, mature and battle-tested |
| Kong Ingress | Active | You want API gateway capabilities (auth, plugins) at the edge |
| NGINX Ingress (F5) | Commercial/active | NGINX Plus paid tier, vendor support |
| Cloud controllers (AWS ALB, GCE, AKS) | Active | Managed load balancers, tight cloud integration |
| Envoy Gateway / other Gateway API impls | Active | New clusters going straight to Gateway API |
The rest of this guide uses ingress-nginx examples because they remain the most widely deployed and the annotation model is what most documentation assumes — the concepts (IngressClass, TLS, rules, troubleshooting) transfer to any controller. Where something is ingress-nginx-specific, it’s called out.
Installing an Ingress Controller
Traefik (recommended for new clusters)
helm repo add traefik https://traefik.github.io/charts
helm repo update
helm install traefik traefik/traefik \
--namespace traefik \
--create-namespace
ingress-nginx (legacy / existing clusters)
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--create-namespace
# Verify installation
kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx
Verify the IngressClass
kubectl get ingressclass
# Output:
# NAME CONTROLLER PARAMETERS AGE
# nginx k8s.io/ingress-nginx <none> 2m
# traefik traefik.io/ingress-controller <none> 1m
Every Ingress you create must reference a class the controller actually serves, via spec.ingressClassName. Older clusters may still use the kubernetes.io/ingress.class annotation — it works on legacy controllers but the spec field is the documented way, so prefer it.
Basic Ingress Resource
Single service routing
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-app-ingress
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: my-app-service
port:
number: 80
ingressClassName belongs in spec, not in metadata.annotations — you’ll see that mistake in older tutorials and it does nothing except confuse the next person reading the file.
Path-based routing (multiple services)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: multi-service-ingress
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api-service
port:
number: 8080
- path: /web
pathType: Prefix
backend:
service:
name: web-service
port:
number: 80
- path: /
pathType: Prefix
backend:
service:
name: default-service
port:
number: 80
pathType: Prefix matches on element boundaries — /api covers /api and /api/v1, but not /apis. Use Exact when you mean exactly that string, and reserve ImplementationSpecific for controller-specific regex patterns like the rewrite example below.
Name-based virtual hosting
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: vhost-ingress
spec:
ingressClassName: nginx
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: api-service
port:
number: 8080
- host: blog.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: blog-service
port:
number: 80
Both hosts share the controller’s external IP — the Host header decides where traffic lands. This is the pattern that makes Ingress pay off versus one load balancer per service.
TLS Termination
Install cert-manager for automatic TLS
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true
The CRD flag is crds.enabled on cert-manager 1.15 and later; older chart versions used installCRDs. If you pin an older chart, check the flag name in the cert-manager docs for that version.
ClusterIssuer for Let’s Encrypt
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: admin@example.com
privateKeySecretRef:
name: letsencrypt-prod
solvers:
- http01:
ingress:
class: nginx
Ingress with TLS
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: tls-ingress
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
ingressClassName: nginx
tls:
- hosts:
- app.example.com
secretName: app-tls-secret
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: my-app-service
port:
number: 80
The annotation tells cert-manager to issue the cert; the tls block tells the controller which secret holds it. The secret gets created in the same namespace as the Ingress — put it anywhere else and TLS silently fails.
TLS passthrough (no termination)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: passthrough-ingress
annotations:
nginx.ingress.kubernetes.io/ssl-passthrough: "true"
spec:
ingressClassName: nginx
rules:
- host: secure.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: secure-service
port:
number: 443
On ingress-nginx this only works if the controller was started with --enable-ssl-passthrough; it’s off by default and the annotation alone does nothing. The trade-off: the backend keeps its cert end-to-end, but you lose L7 routing because the controller can’t inspect encrypted traffic — every request to that host goes to one backend.
Common Annotations
Annotations are controller-specific — these are ingress-nginx annotations. Traefik, HAProxy, and Kong expose the same controls under different annotation names.
Rewrite target
metadata:
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
rules:
- host: app.example.com
http:
paths:
- path: /api(/|$)(.*)
pathType: ImplementationSpecific
backend:
service:
name: api-service
port:
number: 8080
With that rule, /api/users reaches the backend as /users — and since the regex form needs ImplementationSpecific, it’s the classic source of “works in staging, 404s in prod” when two clusters run different controllers.
CORS
metadata:
annotations:
nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-origin: "https://frontend.example.com"
nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization"
Rate limiting
metadata:
annotations:
nginx.ingress.kubernetes.io/limit-rps: "10"
nginx.ingress.kubernetes.io/limit-burst: "20"
Limits apply per controller pod — with three replicas, your effective ceiling is roughly 3× the annotation. Keep that in mind before wondering why bursts pass.
Basic authentication
# Create htpasswd file and secret
htpasswd -c auth admin
kubectl create secret generic basic-auth --from-file=auth -n my-namespace
metadata:
annotations:
nginx.ingress.kubernetes.io/auth-type: basic
nginx.ingress.kubernetes.io/auth-secret: basic-auth
nginx.ingress.kubernetes.io/auth-realm: "Authentication Required"
Custom timeouts
metadata:
annotations:
nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
WebSocket support
metadata:
annotations:
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
WebSockets work out of the box on ingress-nginx; the only thing that kills idle connections is the default 60s read timeout, which is why you raise it.
Request size and IP allowlisting
metadata:
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/8,192.168.1.0/24"
proxy-body-size is the fix for 413s on file uploads; whitelist-source-range is the cheap way to keep an internal admin panel off the public internet.
Session affinity (sticky sessions)
metadata:
annotations:
nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "route"
nginx.ingress.kubernetes.io/session-cookie-hash: "sha1"
Cookie affinity pins a client to the same backend pod. Only reach for it when the app truly keeps state in memory — a shared session store is almost always the better fix.
Advanced Configurations
Default backend (custom 404)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: default-backend-ingress
spec:
ingressClassName: nginx
defaultBackend:
service:
name: custom-404-service
port:
number: 80
Requests that match no rule hit defaultBackend instead of the controller’s built-in 404 page.
Canary deployments
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: canary-ingress
annotations:
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-weight: "10"
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: canary-service
port:
number: 80
The canary Ingress mirrors the production one’s host and path but sends canary-weight percent of traffic to the canary service. It pairs naturally with the deployment strategies guide for progressive rollouts — annotations give you traffic split, but not automated metric analysis or rollback.
Multiple Ingress resources for the same host
Several Ingress resources matching the same host get merged by the controller — useful for splitting rules across teams or namespaces. The catch: conflicts resolve by creation timestamp, so the oldest rule wins. A rule added later that overlaps won’t take effect, and nothing warns you.
Multiple controllers on one cluster
Because IngressClass exists, running two controllers is legitimate: ingress-nginx for legacy workloads plus Traefik or Envoy Gateway for new ones. Each controller only claims Ingresses in its class, so you can migrate service by service instead of doing a flag-day cutover.
Running Ingress in Production
The Ingress object is the easy part — the controller is what actually carries your traffic. A few operational details separate a working setup from a page of 502s at 3 AM.
Size the controller like a load balancer, not a sidecar. It terminates TLS and proxies every request, so give it real CPU and memory requests and at least two replicas spread across nodes. On ingress-nginx, nginx_ingress_controller_requests and the upstream latency percentiles tell you when it’s running hot — tail latency degrades long before the pod looks unhealthy.
Alert on config reloads, not just pod health. A controller pod can show Running while silently ignoring your rules because one bad annotation made the generated config fail validation. Track nginx_ingress_controller_config_last_reload_successful and per-Ingress 4xx/5xx rates — between them they catch most “my route disappeared” incidents.
# Config reload failures and request rates on ingress-nginx
kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- \
curl -s localhost:10254/metrics | grep -E "config_last_reload|controller_requests"
Watch certificate expiry separately. If cert-manager issues your certs, alert on certmanager_certificate_expiration_timestamp_seconds — a cert expiring quietly is a classic Ingress outage — one with zero connection to routing.
Protect the entry point. The controller is a single point of entry by design, so treat it like one: a PodDisruptionBudget on the controller Deployment, no unrelated workloads in its namespace, and a NetworkPolicy that only admits the traffic you expect — 80/443 from the load balancer plus your metrics scraper.
Ingress vs Gateway API
Gateway API is the successor the Kubernetes networking SIG built to replace Ingress. Ingress still works — the API isn’t deprecated and existing resources keep serving traffic — but new capabilities land on Gateway API, not on Ingress.
| Feature | Ingress | Gateway API |
|---|---|---|
| Layer | L7 only | L4 and L7 |
| Routing | Host + path | Host, path, header, weight |
| TLS | Per-Ingress | Per-listener |
| Multi-tenant | Limited | Native (Route namespaces) |
| Role model | Single resource | Split: platform owns Gateway, apps own HTTPRoute |
| Status | Stable, frozen | GA since K8s 1.25, actively developed |
The split role model is the real win: platform teams control the Gateway (listeners, TLS, IPs) while app teams own their HTTPRoutes without touching shared infra config — something Ingress never modeled cleanly. The gateway routing pattern covers the same idea at the design level.
Migration doesn’t require a big-bang rewrite, either: stand up a Gateway API implementation alongside the existing controller, move one hostname at a time from Ingress rules to HTTPRoutes, and keep both running until the Ingress list is empty.
Troubleshooting
Work the chain in order — rule, controller, service, DNS — instead of guessing:
# 1. Did the controller accept the Ingress?
kubectl get ingress -A
kubectl describe ingress my-app-ingress -n my-namespace
# 2. Is the controller healthy?
kubectl get pods -n ingress-nginx
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
# 3. Does the Service have live endpoints?
kubectl get endpoints my-app-service -n my-namespace
kubectl get pods -n my-namespace --show-labels
# 4. Does DNS point at the controller?
kubectl get svc -n ingress-nginx # external IP
dig app.example.com
curl -H "Host: app.example.com" http://<ingress-controller-ip>
If curl -H "Host:" works but the real domain doesn’t, the problem is DNS, not Kubernetes — a ten-second check that saves an hour.
Common issues
404 Not Found:
- The backend Service doesn’t exist or has zero ready pods (check
kubectl get endpoints). - The path doesn’t match any rule — remember
Prefixmatches on element boundaries. - The IngressClass is missing or doesn’t match what the controller serves;
kubectl describe ingressshows whether it was ever synced.
502 Bad Gateway:
- The Service port in the Ingress doesn’t match the Service’s
port— the usual culprit is pointing atcontainerPortortargetPortinstead. - Backend pods are up but the app inside isn’t listening on the expected port.
503 Service Unavailable:
- No healthy endpoints: the Service selector doesn’t match any pod labels.
- A readiness probe is failing, so pods stay out of the endpoints list even though they’re running.
TLS certificate not working:
- cert-manager isn’t installed, or the ClusterIssuer never reached
Ready(kubectl describe clusterissuer). - The TLS secret lives in a different namespace than the Ingress — secrets must colocate.
- The domain doesn’t resolve to the controller’s external IP, so the HTTP-01 challenge can’t complete.
kubectl get events -n my-namespace --field-selector reason=Sync
kubectl get certificate -A
kubectl describe certificate app-tls-secret -n my-namespace
Common Mistakes
ingressClassNameinsidemetadata.annotations: it belongs inspec; the annotation form (and the legacykubernetes.io/ingress.class) is a different thing entirely.- Pointing
backend.service.portat the container port: it must match the Service’sport, which is frequently not the same number. - Assuming annotations are portable: everything under
nginx.ingress.kubernetes.io/*is ingress-nginx dialect. A different controller silently ignores them. - Forgetting annotations need string values:
canary: true(boolean) fails;canary: "true"works. - Overlapping host+path rules across namespaces: merges are resolved by age, so the “wrong” rule can win with no error anywhere.
- Editing the Ingress to fix a 502: the rules were fine — the Service had no endpoints. Debug the endpoints first.
Best Practices
- Always set
spec.ingressClassName— without it, no controller may claim the resource and it fails silently. - Use cert-manager for TLS — manual certificate rotation across dozens of Ingresses doesn’t scale; the Kubernetes networking guide covers how TLS fits the broader traffic model.
- Set resource requests and limits on the controller — it sits on the critical path of every request.
- Monitor the controller — track 4xx/5xx rates, latency percentiles, and config reload failures, not just pod health.
- Prefer
pathType: Prefix—ImplementationSpecificis controller-dependent and breaks on migration. - Keep Ingresses in the same namespace as their Services — cross-namespace references aren’t allowed anyway, but grouping by namespace keeps merges predictable.
- Treat annotations as config debt — they reduce portability; the fewer you rely on, the easier a controller swap is.
- Test routing before pointing DNS —
curl -H "Host: app.example.com" http://<ip>validates rules without waiting for propagation. - Plan the Gateway API move — even if you stay on Ingress for now, new clusters should evaluate maintained controllers or Gateway API directly.
See Also
- Companion manifests — every YAML file from this guide, ready to copy
- Kubernetes Ingress documentation
- Gateway API documentation
- cert-manager installation docs
- ingress-nginx annotations reference
- Complete Guide to Kubernetes Networking
Frequently Asked Questions
Do I need an Ingress controller?
Yes. Ingress resources are only rules — without a controller watching and enforcing them, nothing happens. Pick a maintained one for new clusters: Traefik, HAProxy, Kong, or a cloud provider's controller.
Is ingress-nginx dead? Do I have to migrate now?
The community controller was retired in 2026: no more releases or security patches. Existing installs keep running, so this is a plan-your-migration situation, not an outage — but staying on it long-term means running unpatched edge infrastructure. Gateway API or a maintained controller is the destination.
Can I use Ingress for TCP/UDP?
Not with the standard resource — Ingress is HTTP/HTTPS only. For TCP/UDP, use a LoadBalancer Service, the controller's TCP/UDP passthrough config, or Gateway API's TCPRoute/UDPRoute.
How do I route to a service in another namespace?
You can't — Ingress backends must live in the same namespace as the Ingress. The workarounds are a Service of type ExternalName or re-exporting the service locally, both of which add indirection most teams regret later.
What's the difference between Ingress and LoadBalancer?
A LoadBalancer Service gives you one cloud load balancer pointing at one Service. Ingress gives you one entry point with L7 rules fanning out to many Services — virtual hosting, path routing, and TLS termination in one object.
Related Resources
Kubernetes Basics for Application Developers
Learn the core Kubernetes concepts every developer needs: Pods, Services, Deployments, ConfigMaps, and basic kubectl commands.
GuideKubernetes Advanced — Beyond the Basics
An advanced guide to Kubernetes: operators, custom resources, admission controllers, multi-cluster management, and production hardening for experienced users.
GuideComplete Guide to Kubernetes Networking
Understand how Kubernetes networking really works: flat pod network, Service types, Ingress, NetworkPolicies, CNI plugins, DNS, and service mesh.
GuideDeployment Strategies Compared: Blue-Green, Canary, Rolling
A practical guide to deployment strategies: rolling, blue-green, canary, shadow and feature flags. Minimize risk and rollback time when releasing to production.
PatternGateway Routing Pattern
Route requests to multiple backend services through a single entry point that handles cross-cutting concerns.
GuideComplete Guide to GitOps with ArgoCD
Deploy Kubernetes apps with GitOps and ArgoCD: installation, ApplicationSets, sync strategies, Helm/Kustomize, RBAC, and multi-cluster.