StackPractices
intermediate By Mathias Paulenko

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.com vs app.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 LoadBalancer Service 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 LoadBalancer or 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:

flowchart diagram: Client

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.

ControllerStatusGood fit when
ingress-nginxRetired (unmaintained since Mar 2026)Already deployed; plan a move
TraefikActiveKubernetes-native, dynamic config, Gateway API support
HAProxy IngressActiveHigh-throughput L7, mature and battle-tested
Kong IngressActiveYou want API gateway capabilities (auth, plugins) at the edge
NGINX Ingress (F5)Commercial/activeNGINX Plus paid tier, vendor support
Cloud controllers (AWS ALB, GCE, AKS)ActiveManaged load balancers, tight cloud integration
Envoy Gateway / other Gateway API implsActiveNew 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

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.

FeatureIngressGateway API
LayerL7 onlyL4 and L7
RoutingHost + pathHost, path, header, weight
TLSPer-IngressPer-listener
Multi-tenantLimitedNative (Route namespaces)
Role modelSingle resourceSplit: platform owns Gateway, apps own HTTPRoute
StatusStable, frozenGA 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 Prefix matches on element boundaries.
  • The IngressClass is missing or doesn’t match what the controller serves; kubectl describe ingress shows 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 at containerPort or targetPort instead.
  • 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

  • ingressClassName inside metadata.annotations: it belongs in spec; the annotation form (and the legacy kubernetes.io/ingress.class) is a different thing entirely.
  • Pointing backend.service.port at the container port: it must match the Service’s port, 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 — ImplementationSpecific is 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

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.