Two names that beginners mix up all the time: Ingress and Ingress controller. They are different things.

An Ingress is a Kubernetes object, a written set of routing rules. It says things like “requests for shop.example.com should go to the shop application, and requests for shop.example.com/blog should go to the blog application”. On its own, an Ingress does nothing at all. It is only a note.

An Ingress controller is a program running inside the cluster that reads those notes and does the actual work of receiving traffic and forwarding it. It is usually a reverse proxy, which is a server that stands in front of other servers, accepts requests on their behalf and passes each one to the correct place.

Kubernetes does not include an Ingress controller by default. You must choose one and install it. The Ingress object is the menu; the controller is the waiter who reads the menu and carries out the orders.

To see why Ingress exists, look at what you would do without it.

Every Pod in a cluster has its own internal address that changes when the Pod is replaced. To give a stable address, Kubernetes offers a Service, a fixed internal front door for a group of Pods. By default, a Service is reachable only from inside the cluster. To let the outside world in, you have two simple options.

Where these options fall short

• Cost. Fifty applications would mean fifty cloud load balancers.
• No host or path routing. A basic Service load balancer works at the connection level and cannot tell “shop.example.com” from “blog.example.com”.
• Repeated encryption setup. Every public door would need its own certificate for secure connections.
• Scattered controls. Rate limits, redirects, authentication and logging would have to be repeated everywhere.

Ingress solves these by putting one smart entrance in front of many Services. One public address, one set of certificates, and a single place to apply web-level rules.

A few basics about the web and about Kubernetes make everything that follows much clearer.

HTTP, HTTPS and the host name

HTTP is the language web browsers and servers use to ask for pages and reply. HTTPS is the same language wrapped in encryption so nobody in between can read or change it. Every request carries a host name, such as shop.example.com, and a path, such as /cart. Together these tell a server what the visitor wants.

DNS

DNS is the internet’s phone book. It turns a name like shop.example.com into a numeric address. For Ingress, you point your names at the public address of the Ingress controller, and then all of them arrive at the same entrance.

Reverse proxy

A reverse proxy is a server that receives requests from visitors and forwards them to servers behind it, returning the answers. Visitors never talk to the back servers directly. Well-known examples include NGINX, HAProxy, Envoy and Traefik.

Layer 4 versus Layer 7

Network traffic can be handled at different levels. Layer 4 deals with raw connections, like a postman who only looks at the street address on the envelope. Layer 7 deals with the actual web request, like a postman who opens the envelope and reads “please deliver to the bakery on the second floor”. Ingress works at Layer 7, so it can make decisions based on host names and paths.

Service, Endpoints and Pods

A Service selects Pods by label and keeps a list of their current addresses, called endpoints. An Ingress points at a Service, and the controller uses the Service’s endpoints to find live Pods.

The words you will meet again and again.

Path types

Each path rule has a type that decides how the text is compared.

• Exact: the path must match exactly. “/cart” matches “/cart” but not “/cart/items”.
• Prefix: the path matches if it starts with the given text, split on slashes. “/shop” matches “/shop” and “/shop/items”.
• ImplementationSpecific: the controller decides how to interpret it. Behavior can differ between controllers.

Here is the full picture of how traffic gets from a visitor to your Pod.

flowchart TB
    V["Visitor's browser"] --> DNS["DNS: name to public address"]
    DNS --> LB["Cloud load balancer or node address"]
    LB --> IC
    subgraph IC["Ingress controller Pods"]
        P1["Reverse proxy Pod 1"]
        P2["Reverse proxy Pod 2"]
    end
    P1 --> S1["Service: shop"]
    P1 --> S2["Service: blog"]
    P2 --> S1
    P2 --> S2
    S1 --> A1["Shop Pods"]
    S2 --> B1["Blog Pods"]
    

The parts

Let us take an Ingress apart, using field names only, and see what each part means.

An Ingress lives in the networking API group at version v1, which has been stable since Kubernetes version 1.19. Its important fields are these.

How matching works

When a request arrives, the controller first chooses the rule whose host matches the request’s host name. Then, among that rule’s paths, it picks the most specific match, typically the longest matching path. If nothing matches, the request goes to the default backend, which usually responds with a “not found” message.

Almost every real Ingress uses one of three shapes, or a mix of them.

Trade-offs between the patterns

Path-based routing keeps everything under one name, which is simple for visitors and needs only one certificate. But applications must be told they live under a sub-path, and links inside pages may break unless the app is built for it.

Host-based routing keeps each application at the root of its own name, so no path tricks are needed. It needs more DNS names, and a wildcard certificate or several certificates.

Most teams prefer host-based routing for separate applications, and path-based routing for pieces of one product, such as a front end and its API.

The controller is always listening. Here is what it does when you create or change an Ingress.

sequenceDiagram
    participant U as You
    participant A as API server
    participant C as Controller watcher
    participant P as Reverse proxy
    U->>A: Create or update an Ingress
    A-->>C: Watch event: Ingress changed
    C->>A: Read Services, endpoints and secrets
    A-->>C: Current data
    C->>C: Build full proxy configuration
    C->>P: Apply new configuration
    P-->>C: Ready with new rules
    Note over C,P: Traffic keeps flowing during the switch
    

The reconcile loop

Kubernetes controllers follow a simple habit called reconciliation: they compare “what is wanted” with “what exists”, and act to make them match. An Ingress controller repeats this loop for every change.

1. It watches for changes to Ingress objects, Services, endpoints and the secrets that hold certificates.
2. It filters the Ingress objects to those whose class belongs to this controller.
3. It builds a picture of all hosts, paths, backends and certificates.
4. It renders that picture into the proxy’s native configuration.
5. It applies the configuration, either by reloading the proxy or by updating it live.

Reload versus live update

Different controllers apply changes differently. Some, built on NGINX, write a new configuration file and ask NGINX to reload, which starts new worker processes and lets old ones finish their current requests. Frequent changes in a large cluster can make reloads costly, so many controllers update only the list of backend Pod addresses live and reload only when routes change. Envoy-based controllers push changes to the proxy over a live control channel, which avoids reloads altogether.

Following Pods as they change

Pods come and go all the time. Many controllers do not send traffic to the Service’s virtual address. Instead, they read the list of Pod addresses (the endpoints) and send requests straight to Pods, which allows features like sticky sessions and smarter load balancing. When a Pod starts or stops, the endpoint list changes and the controller notices almost at once.

Follow one visitor from the browser to your Pod and back.

Headers the backend needs to know

Because the controller sits between the visitor and the application, the application would otherwise only see the controller’s address. Controllers therefore add headers such as the original visitor address and the original protocol, commonly named forwarded-for headers. Your application must be configured to trust these headers only from the controller, or attackers could fake them.

Secure connections are the most common reason people adopt an Ingress controller.

flowchart LR
    B["Browser"] -->|HTTPS encrypted| IC["Ingress controller: holds certificate"]
    IC -->|Option A: plain HTTP inside cluster| POD1["Pod"]
    IC -->|Option B: re-encrypted HTTPS| POD2["Pod with own certificate"]
    CM["cert-manager"] -->|requests and renews| CA["Certificate authority"]
    CM -->|stores certificate| SEC["Kubernetes secret"]
    SEC --> IC
    

What is TLS?

TLS is the encryption technology behind HTTPS. A server proves who it is by showing a certificate, which is a digital identity card signed by a trusted organization called a certificate authority. The visitor’s browser checks the signature. If it is valid and the name matches, the browser shows a padlock and encrypts everything after that.

Termination at the Ingress

In TLS termination, the controller holds the certificate and its private key, ends the encrypted connection, and forwards the request inside the cluster. It removes the need for every application to manage certificates. The certificate and key are kept in a Kubernetes secret that the Ingress refers to.

Choices inside the cluster

• Plain inside: simplest and fastest. Acceptable only if you trust the internal network.
• Re-encrypt: the controller opens a new encrypted connection to the Pod. Safer, with a small cost in speed and effort.
• Passthrough: some controllers can forward the encrypted stream untouched to the Pod, which then holds the certificate. The controller cannot read or route by path in this mode, only by host name.

Automatic certificates

Certificates expire. Renewing them by hand is a famous cause of outages. The cert-manager add-on can request free certificates from Let’s Encrypt or from a private authority, prove that you own the name, store the result in a secret, and renew it before it expires. The Ingress simply names the secret, and the controller picks up new certificates automatically.

There is no single official controller. Kubernetes lists many, each with its own strengths.

Two families

In-cluster proxies such as NGINX, Traefik, HAProxy and Envoy run as Pods, and you own their scaling, upgrades and tuning. They work the same in every cloud and in your own data center. Cloud-managed controllers instead configure a load balancer that lives outside your cluster and is run by the provider. This removes work and can integrate with cloud firewalls and identity, but it ties you to that provider and its limits.

A controller is not useful until traffic can reach it. How you expose it depends on where the cluster runs.

Installation basics

Most controllers are installed with a package manager for Kubernetes called Helm, or with a set of ready-made description files. The installation creates the controller’s Deployment or DaemonSet, its Service, the permissions it needs to read cluster objects, and an IngressClass. After that, you create Ingress objects that name that class.

Running several controllers

A cluster can host more than one controller, for example one for public traffic and one for internal tools. The IngressClass tells them apart. Each Ingress chooses one class, and only that controller handles it. If you install two controllers without classes, both may try to handle the same Ingress and fight, so always set classes explicitly.

The Ingress object itself is small. Most of the useful extras come from controller-specific settings.

The portability problem

The Ingress object has no standard way to express most of these features. Each controller invented its own annotations or custom objects. An annotation that works on one controller means nothing on another. Moving controllers therefore means rewriting all these settings, which is the main source of lock-in with Ingress.

Kubernetes has several ways to expose applications. Here is how they relate, and where the future is heading.

flowchart TD
    Q1{"Is the traffic web traffic, HTTP or HTTPS?"}
    Q1 -->|No, raw TCP or UDP| L4["LoadBalancer Service or Gateway API TCP and UDP routes"]
    Q1 -->|Yes| Q2{"Many apps behind one address?"}
    Q2 -->|No, only one app| L4B["LoadBalancer Service may be enough"]
    Q2 -->|Yes| Q3{"New project and cluster supports Gateway API?"}
    Q3 -->|Yes| GW["Consider Gateway API"]
    Q3 -->|No or existing setup| ING["Ingress with an Ingress controller"]
    

What is the Gateway API?

The Gateway API is a newer family of Kubernetes objects built to overcome the limits of Ingress. It splits responsibilities among three roles. An infrastructure provider defines the kinds of gateways available. A cluster operator creates the actual gateways and decides who may attach to them. Application developers create routes that attach to a gateway. It supports features that Ingress needed annotations for, such as header-based matching and traffic splitting, in a portable way, and it can handle more protocols than HTTP.

The Kubernetes project treats Ingress as stable but frozen, meaning it is not receiving new features, and points new feature work to the Gateway API. The Gateway API reached its first stable release in 2023. Existing Ingress setups continue to work, and migration can be gradual, but new projects should evaluate the Gateway API seriously.

The controller is the single entrance. If it fails, everything behind it becomes unreachable. Treat it as your most critical service.

Performance factors

• Connections: keep-alive between the proxy and Pods reduces the cost of opening new connections.
• Encryption: handshakes are costly. Session reuse and modern protocol versions reduce the load.
• Configuration size: thousands of Ingress objects produce a huge proxy configuration and slow updates. Consider splitting across several controllers.
• Reload frequency: constant churn in routes can cause frequent reloads and dropped long-lived connections.
• Extra hops: traffic that crosses machines twice, once to the controller and once to a Pod, adds delay. Some setups keep traffic on the same machine where possible.

Ingress controllers are the standard way to expose web apps, but they have real costs and limits.

The design trade-offs

One controller versus several. A single shared controller is cheap and simple, but one team’s mistake can affect all. Separate controllers for public traffic, internal tools and different teams reduce the blast radius, at the cost of more moving parts and more public addresses.

In-cluster proxy versus cloud-managed. In-cluster proxies are portable and highly configurable, but you operate them. Cloud-managed entrances are easier to run and integrate with the provider’s security, but they tie you to one vendor and their feature limits.

Terminate early versus end-to-end encryption. Ending encryption at the entrance is simple and lets the controller inspect traffic. Encrypting all the way to the Pod is safer against internal snooping but costs more processing and certificate management.

Ingress today versus Gateway API. Ingress is mature, widely understood and supported by every controller. The Gateway API is richer and more portable but newer, and support varies. The right answer depends on your timeline and your team’s appetite for change.

The Ingress controller faces the open internet. It is one of the most attacked parts of any cluster, so security here is not optional.

The controller sees every request. That makes it the best place to learn how healthy your whole platform is.

The golden signals at the entrance

Ideas that hold up in production, and habits that cause outages.

Patterns that work

Traps to avoid

Habits that keep the front door open, and errors that lock people out.

Habits that pay off

• Treat the controller as tier-zero infrastructure with its own owners, monitoring, alarms and on-call.
• Use readiness checks on backends so the controller only sends traffic to Pods that are ready.
• Set explicit classes on every Ingress.
• Automate certificates and alert on expiry anyway.
• Test changes in a staging cluster before applying to the shared production entrance.
• Upgrade on a schedule with a rollback plan, reading release notes for changed defaults.
• Document your annotations and keep an inventory of which teams use which features.
• Keep a default backend with a helpful, non-revealing error page.
• Plan the exit by learning the Gateway API now, so you are not forced to move in a hurry.

Mistakes beginners make

The same idea shows up at every scale.

When the front door does not open, walk the path of the request from the outside in.

flowchart TD
    T1["Visitor sees an error"] --> T2{"Does the name resolve to the controller address?"}
    T2 -->|No| F1["Fix DNS"]
    T2 -->|Yes| T3{"Does the controller answer at all?"}
    T3 -->|No| F2["Check load balancer, firewall and controller Pods"]
    T3 -->|Yes| T4{"What status code?"}
    T4 -->|404| F3["No rule matched: check host, path, class and path type"]
    T4 -->|502 or 503| F4["Backend problem: check Service, port, endpoints and readiness"]
    T4 -->|504| F5["Backend too slow: check timeouts and Pod health"]
    T4 -->|Certificate warning| F6["Check certificate secret, name and expiry"]
    

Quick answers to the questions people ask most.

You started with a mall that has one main entrance. Now you know how to build, guard and grow that entrance for a cluster.