Mastering Kubernetes Ingress: Controllers, Architecture, and Lua Extensions

1. Overview of Ingress

Ingress is a collection of routing rules that expose services inside a cluster to users via layer‑7 protocols. It is a default Kubernetes resource that defines HTTP/HTTPS rules for external traffic, allowing administrators to control inbound traffic to the cluster.

2. Ingress Definitions

Ingress resource : an API object usually configured with YAML, defining how requests are forwarded to services.

Ingress‑controller : the component that manages L4/L7 traffic entering or leaving the cluster, parses Ingress rules and performs request forwarding.

3. Popular Ingress Controllers

Kubernetes Ingress Nginx : official recommendation, based on Nginx with Lua plugins; easy to start but reload can be slow with many configs.

Nginx Ingress : developed by NGINX, built on NGINX Plus; high stability, supports TCP/UDP, but lacks some auth and traffic‑scheduling features.

Kong Ingress : extends Nginx with Lua modules, adds advanced routing, upstream probing, and authentication; provides CRDs to sync with Kong.

Traefik Ingress : full‑featured edge router with live config reload, multiple load‑balancing algorithms, Web UI, metrics, REST API, canary releases, and built‑in Let's Encrypt support.

HAProxy Ingress : leverages HAProxy’s load‑balancing strengths, offers soft config updates, DNS‑based service discovery, and customizable ConfigMap templates.

APISIX Ingress : emerging controller comparable to Kong, strong routing and plugin extensibility, excellent performance, but limited real‑world cases and documentation.

4. Ingress‑Nginx Architecture

The runtime consists of three main components: NginxController , Store , and SyncQueue .

Store watches the Kubernetes API server, captures changes to resources such as Ingress and Service, and writes events into a circular buffer.

NginxController listens to the update channel; when a configuration change arrives it pushes a request into SyncQueue .

SyncQueue processes tasks by:

Periodically scanning the queue and executing update operations.

Using Store to fetch the latest runtime data.

After processing, a new Nginx configuration is generated; if a reload is required, the new file is written locally and Nginx is reloaded.

5. Lua Extensions in Ingress‑Nginx

Lua scripts are embedded to provide flexible extensions. The main phases are:

init_by_lua* : runs when Nginx starts or reloads, initializing Lua environment.

init_worker_by_lua* : executed for each worker process, often used for periodic tasks such as health checks.

ssl_certificate_by_lua* : handles HTTPS requests, allowing per‑request certificate selection.

set_by_lua* : sets Nginx variables.

rewrite_by_lua* : rewrites URLs or performs redirects.

access_by_lua* : processes requests during the access phase.

content_by_lua* : runs business logic and generates responses, similar to a servlet.

balancer_by_lua* : performs load‑balancing decisions.

header_filter_by_lua* : modifies response headers.

body_filter_by_lua* : modifies response bodies.

log_by_lua* : writes access logs.