Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 78 ยท Services and Networking

Ingress and Ingress Controllers

Route HTTP traffic into a cluster with Kubernetes Ingress: host and path rules, pathType, IngressClass, TLS termination, controllers and annotation pitfalls.

A LoadBalancer Service gives one application one public address, which gets expensive and unwieldy when you run a dozen web applications. What you really want is one entry point that looks at each HTTP request and decides where it goes: shop.example.com to the shop, shop.example.com/api to the API, blog.example.com to the blog, with HTTPS handled in one place. That is the job of an Ingress.

An Ingress is a routing rulebook stored in the API. By itself it does nothing. A separate program, the Ingress controller, reads these rules and configures a real reverse proxy to follow them. In this lesson you will write host and path rules, understand pathType and matching order, terminate TLS, choose a controller, and avoid the annotation traps that cause most Ingress incidents. A Python router stand-in lets you test the matching rules yourself.

This site has no cluster, so every manifest and command is read-only. The Python stand-ins implement the matching rules, not a real proxy. Ingress is also in maintenance mode: new features go into the Gateway API, but Ingress is everywhere in existing clusters, so you need to know it well.

Two halves of Ingress

Ingress object Rules for which host and path goes where.
Controller A proxy that implements the rules.

No controller installed means the rules do nothing.

1 / 2

A first Ingress

This Ingress (read-only) sends different hosts and paths to three Services:

YAML
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  ingressClassName: nginx
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: shop-api
                port:
                  number: 8080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: shop-web
                port:
                  number: 80
    - host: blog.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: blog
                port:
                  name: http

Each backend names a Service in the same namespace and one of its ports (by number or by name). The Ingress never talks to Pods directly. The controller uses the Service's endpoints, so readiness probes and scaling work as usual.

flowchart LR
  U["Browser"] --> L["Load balancer<br/>(one address)"]
  L --> C["Ingress controller<br/>(reverse proxy Pods)"]
  C -- "shop.example.com /api" --> A["Service shop-api"]
  C -- "shop.example.com /" --> W["Service shop-web"]
  C -- "blog.example.com" --> B["Service blog"]

One load balancer in front of the controller replaces one load balancer per application.

Path matching

Every path rule has a pathType, and it is required:

pathType Behavior
Exact Matches only that exact path, case-sensitive. /api does not match /api/ or /api/users.
Prefix Matches by path elements split on /. /api matches /api, /api/ and /api/users but not /apiary.
ImplementationSpecific Left to the controller. Avoid it if you want portability.

When several rules match one request, the longest matching path wins, and an Exact match beats a Prefix match. The catch-all / with Prefix matches everything, so it acts as the fallback for its host. If no rule matches at all, the controller serves its default backend, usually a plain 404 page (you can also configure spec.defaultBackend on the Ingress).

Hosts may be exact (shop.example.com) or have a single-label wildcard at the start (*.example.com matches app.example.com but not a.b.example.com and not example.com itself). A rule without a host matches any host name.

IngressClass: which controller reads which Ingress

A cluster can run several controllers (for example one for public traffic and one for internal tools). The ingressClassName field picks the controller. Each controller registers an IngressClass object, and one of them can be marked as the cluster default, so Ingresses without a class name still get picked up:

Terminal
kubectl get ingressclass
TEXT
NAME    CONTROLLER                     PARAMETERS   AGE
nginx   k8s.io/ingress-nginx           <none>       40d

If your Ingress has no class and no default class exists, no controller touches it. That is the first thing to check when a new Ingress "does nothing". Older manifests set the class with an annotation (kubernetes.io/ingress.class), which is deprecated.

TLS termination

To serve HTTPS, list the hosts and a Secret holding the certificate and key:

YAML
spec:
  tls:
    - hosts:
        - shop.example.com
      secretName: shop-example-com-tls

The Secret must be of type kubernetes.io/tls with tls.crt and tls.key in the same namespace. The controller decrypts HTTPS at the edge (TLS termination) and usually forwards plain HTTP to the Service inside the cluster. Choosing the certificate for a connection is based on the server name the browser sends (SNI), which is why you can host many domains behind one address. Instead of creating certificates by hand, most teams install cert-manager, which watches Ingresses, obtains certificates from an authority such as Let's Encrypt and renews them automatically.

Choosing a controller

Kubernetes ships no controller. You install one, and the choice matters because features, performance and annotations differ:

  • NGINX-based controllers. The community ingress-nginx project was the most common choice for years, but its retirement was announced for 2026, so check its current status and plan a migration path. Other NGINX-based controllers exist, including one maintained by NGINX's vendor.
  • Traefik, HAProxy and Envoy-based controllers (Contour, Emissary and others), each with their own strengths such as dynamic configuration, performance or rich traffic features.
  • Cloud controllers that create the provider's native layer-7 load balancer (for example the AWS Load Balancer Controller or the GKE Ingress controller). They integrate with the cloud's certificates and firewalls, but each Ingress may provision its own billed load balancer.

Annotations and their pitfalls

The Ingress API deliberately covers only the common 80 percent: host, path, backend, TLS. Everything else (redirects, rewrites, timeouts, body size limits, rate limits, authentication) is configured with annotations that are specific to one controller:

YAML
metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "20m"
    nginx.ingress.kubernetes.io/rewrite-target: /$2

This leads to well-known traps:

  • Annotations are not portable. Move to another controller and they are silently ignored. A mistyped annotation is ignored too, with no error from the API server.
  • Rewrites interact with pathType. A rewrite such as stripping /api before forwarding needs a matching regular-expression path, and the exact syntax differs per controller. Prefer applications that can live under a prefix, or test the rewrite carefully.
  • Snippet annotations let users inject raw proxy configuration. That is powerful and dangerous in a shared cluster (it can expose secrets or break the controller), so many administrators disable them.
  • One bad Ingress can break a shared controller. Some controllers reload the whole configuration on each change, and an invalid rule can block updates for everyone.
  • Annotations differ between versions of the same controller; read the release notes when upgrading.

Gateway API addresses most of these gaps with typed, portable fields.

Stand-in: a host and path router

The first stand-in is the matching engine: for a host and path it finds the best rule using the Exact and Prefix rules above, or falls back to a default backend. It is the logic only; a real controller also streams the request and response.

Python Longest-prefix routing with Exact and Prefix

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Three results deserve a second look. /api/admin hits the Exact rule, /api/admin/x does not (so the /api prefix serves it), and /apiary is not under /api, because prefixes match whole path elements, so it falls through to /.

Stand-in: wildcard hosts and TLS certificates

The second stand-in selects the certificate for a requested host name, using the single-label wildcard rule. It also reports a host that no certificate covers, which in a browser appears as a certificate warning.

Python Wildcard host matching and certificate choice

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Exact entries win over wildcards, mirroring how servers prefer the most specific certificate.

Common mistakes

  • Creating an Ingress in a cluster with no controller, or with a class name nobody serves.
  • Pointing backend.service at a Service in another namespace; it must be in the same namespace.
  • Using Prefix for /api and expecting it to match /apiary.
  • Relying on controller annotations and not noticing they are ignored on another controller.
  • TLS Secret in the wrong namespace or of the wrong type.
  • Running one cloud-native Ingress per app and paying for many load balancers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You apply an Ingress to a new cluster, but nothing happens. What is the most likely cause?

    An Ingress is only a set of rules. A controller must be running and responsible for its IngressClass to act on them.
  2. 2. With a Prefix rule for /api, which request path does NOT match?

    Prefix rules match whole path elements, so /apiary is a different element from /api.
  3. 3. Two rules match a request: Prefix / and Exact /health. Which one wins for /health?

    When several rules match, the longest path wins and Exact beats Prefix, so /health goes to its own backend.
  4. 4. Where does TLS usually end in an Ingress setup?

    The controller terminates TLS using the certificate from the referenced Secret and typically proxies HTTP to the backend Service.
  5. 5. Why are Ingress annotations a portability risk?

    Each controller defines its own annotations; a different controller ignores them without any error, so behavior changes quietly after a migration.

Summary

  • An Ingress holds HTTP routing rules; an Ingress controller (nginx-based, Traefik, HAProxy, Envoy-based or cloud-native) turns them into a working proxy.
  • Rules match host and path; Exact beats Prefix, the longest path wins, and Prefix matches whole path elements.
  • ingressClassName and IngressClass objects decide which controller owns an Ingress.
  • TLS ends at the controller, using a kubernetes.io/tls Secret, often managed by cert-manager.
  • Controller-specific annotations are not portable and fail silently, which is why the Gateway API exists.

Next: the more expressive successor to Ingress, Gateway API.