Tigera Logo

Guides: NGINX Ingress

NGINX Ingress: The Basics and a Quick Tutorial

What Is the NGINX Ingress Controller?

The NGINX Ingress Controller is a Kubernetes-native component that manages external access to services within a Kubernetes cluster. It uses NGINX as a reverse proxy and load balancer to route HTTP and HTTPS traffic to appropriate services based on rules defined in Kubernetes Ingress resources.

The NGINX solution is highly configurable and supports traffic management features, such as SSL termination, session persistence, URL rewriting, and rate limiting. It can be deployed in two main flavors: one based on the open source version of NGINX, and another using NGINX Plus, which offers commercial features like dynamic reconfiguration and active health checks.

The NGINX Ingress Controller translates Kubernetes ingress rules into native NGINX configuration and reloads dynamically to apply changes without downtime.

This is part of a series of articles about Kubernetes security.

In this article:

Key Features of NGINX Ingress Controller

The NGINX Ingress Controller offers a set of features to meet the needs of both simple and complex Kubernetes deployments. Key capabilities include:

  • Load balancing: Supports round-robin, IP hash, least connections, and other balancing algorithms.
  • TLS termination and SNI routing: Handles SSL offloading and can route requests based on the Server Name Indication (SNI) header.
  • Customizable routing rules: Allows host- and path-based routing with regular expressions and rewrites using NGINX annotations or custom templates.
  • Rate limiting and access control: Provides client rate limiting, connection limits, and IP whitelisting/blacklisting for securing endpoints.
  • gRPC and WebSocket support: Supports modern protocols needed for real-time and API-driven applications.
  • Rewrite and redirect capabilities: Supports rewriting URIs and issuing redirects using NGINX configuration.
  • Session persistence: Supports sticky sessions for stateful applications.
  • Observability and metrics: Integrates with Prometheus and supports access logs, error logs, and customizable dashboards via tools like Grafana.
  • Scalability and high availability: Scales with Kubernetes clusters and supports active-active HA deployments.
  • Extensibility: Offers custom configuration options via snippets, Lua scripting, and integration with external auth systems.

NGINX Ingress Controller Architecture

The architecture of the NGINX Ingress Controller is built around a modular design that integrates tightly with Kubernetes. It consists of several key components that work together to translate Kubernetes Ingress resources into a live, running NGINX configuration.

Core Components

The NGINX Ingress Controller runs as a pod in the Kubernetes cluster, typically in the nginx-ingress namespace. This pod contains:

  • The ingress controller process: Monitors Kubernetes API resources like ingresses, services, and secrets, and translates them into NGINX configuration.
  • NGINX master process: Oversees the worker processes, manages their lifecycle, and loads new configurations upon reloads.
  • NGINX worker processes: Handle incoming client traffic and perform reverse proxying, SSL termination, load balancing, and other operations.

Control Loop and Configuration Generation

At the heart of the controller is a control loop implemented in Go. This loop listens for changes to Kubernetes resources using informers. These informers maintain an up-to-date cache and notify the control loop via a workqueue when a relevant change occurs.

Once notified, the controller fetches the affected resources and invokes a configuration generator. This generator produces NGINX configuration files based on the current cluster state. The configuration is then written to the filesystem, and NGINX is reloaded to apply the changes.

Reloads are done gracefully using nginx -s reload, and the controller monitors the reload process by checking a special Unix socket to verify that the new configuration version has been applied. If successful, the resource status is updated, and a Kubernetes event is emitted.

Dynamic Resource Management

The architecture supports both built-in Kubernetes resources (like Ingress) and custom resources (VirtualServer, TransportServer, GlobalConfiguration). These are validated and tracked in a Configuration object that ensures no conflicts in hostnames or ports and determines what updates must be applied to NGINX.

Additionally, secrets like TLS certs and keys are handled by a LocalSecretStore, which keeps them synced on disk for NGINX to consume.

High Availability and Observability

The controller is typically deployed in a highly available configuration with multiple replicas and a shared public endpoint (via LoadBalancer or NodePort). It integrates with Prometheus for metrics, exposing performance and health indicators over an HTTP endpoint. Readiness and liveness probes ensure smooth operation and quick failure detection.

NGINX Plus Enhancements

When using NGINX Plus, the controller can leverage dynamic reconfiguration via the NGINX Plus API instead of full reloads. It also supports advanced metrics and additional secret types like JSON Web Keys (JWKs).

Tutorial: Installing NGINX Ingress Controller with Helm

This section walks through the steps to install the NGINX Ingress Controller using Helm, the Kubernetes package manager. Helm simplifies deployment by managing charts—preconfigured application resources. Instructions are adapted from the NGINX documentation.

Prerequisites

Ensure the following before you begin:

  • A Kubernetes cluster with a supported version.
  • Helm 3.0 or higher installed on your system.
  • For NGINX Plus users, access to a valid license, JWT token, and subscription credentials to download the commercial image.

If you plan to use custom resources, you must also install the necessary Custom Resource Definitions (CRDs). Helm can install these automatically unless you opt out using the –-skip-crds flag.

Installing the Chart

To install the open source version of the NGINX Ingress Controller:

helm install release-name oci://ghcr.io/nginx/charts/nginx-ingress --version 2.1.0

To install the commercial NGINX Plus version:

helm install release-name oci://ghcr.io/nginx/charts/nginx-ingress
  --version 2.1.0
  --set controller.image.repository=registry-name.example.com/nginx-plus-ingress
  --set controller.nginxplus=true

Ensure the image registry is accessible.

Upgrading the Chart

Helm does not manage CRD upgrades during chart upgrades. To upgrade CRDs manually:

kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v5.0.0/deploy/crds.yaml

Then, upgrade the release:

helm upgrade release-name oci://ghcr.io/nginx/charts/nginx-ingress --version 2.1.0

For upgrades from versions prior to 3.1.0, some resources like Deployment and Service may be recreated due to naming changes. To avoid downtime, copy the selector values from the existing resources and configure them under selectorLabels in values.yaml, then set overrides during the upgrade.

Uninstalling the Chart

To uninstall the Helm release:

helm uninstall release-name

This removes all Kubernetes resources associated with the release, but does not delete the CRDs. To remove them:

kubectl delete -f crds/

Caution: This will delete all custom resources across the cluster. Ensure that no other NGINX Ingress Controller instance depends on these CRDs.

Installing the Edge Version

For testing the latest development version, you can install the edge build:

helm install release-name oci://ghcr.io/nginx/charts/nginx-ingress --version 0.0.0-edge

The edge version is not stable and should not be used in production.

Installing from Chart Sources

You can also install the controller by pulling and building the chart locally:

helm pull oci://ghcr.io/nginx/charts/nginx-ingress --untar --version 2.1.0
cd nginx-ingress
helm install release-name .

For NGINX Plus:

helm install release-name -f values-plus.yaml .

This approach gives more control and is useful when customizing the deployment or managing CRDs manually.

Limitations of NGINX Ingress Controller

While the NGINX Ingress Controller is a feature-rich solution for managing ingress traffic in Kubernetes environments, it does come with some limitations and trade-offs that users should consider before adoption. These limitations were reported by users on the G2 platform:

  • Default HTTP port configuration: By default, the controller enables HTTP traffic on port 80 but not HTTPS on port 443. This may lead to less secure configurations if HTTPS is not explicitly enabled.
  • Limited community support: Compared to open source alternatives like Traefik or HAProxy Ingress, the F5 NGINX Ingress Controller has a smaller user base and fewer community-driven resources. This can make troubleshooting and finding documentation for advanced use cases more difficult.
  • Higher cost: The commercial version, NGINX Plus, introduces licensing fees that may be significant for smaller organizations.
  • Complex setup: Installing and configuring the F5 NGINX Ingress Controller can be more complicated than other ingress options. It often requires deeper technical knowledge, especially when working with custom resources or integrating advanced features.
  • Manual WAF integration: Unlike some other ingress controllers that offer built-in or community-supported web application firewall (WAF) features, NGINX requires manual integration or the purchase of separate F5 security solutions to achieve similar protection.
  • Proprietary nature: Being a commercial product, the NGINX Plus version is not fully open source.
  • Shifting ecosystem: Some users have begun transitioning to alternatives like the Gateway API or service mesh solutions, which can offer more native integration with Kubernetes and additional capabilities without relying on traditional ingress controllers.

Kubernetes Ingress with Calico

The Calico Ingress Gateway is a scalable, customizable ingress management solution based on the Envoy Gateway that offers a way to optimize external traffic flow. Calico provides the following ingress capabilities:

  • Enterprise-Hardened Distribution of Envoy Gateway – A 100% upstream Envoy Gateway distribution ensures reliable, scalable, and customizable ingress traffic management that is fully compatible with the Kubernetes Gateway API.
  • Unified Network Security and Observability – Combine ingress, egress, network policy management, cluster mesh, and observability within a single platform for improved efficiency.
  • Scalable and Optimized Traffic Flow Management – Efficiently manage and scale high volumes of ingress traffic across multiple Kubernetes clusters with enhanced reliability and control.
  • Advanced Traffic Control – Enable granular control over ingress traffic through header-based routing, retries, fault injection, rate limiting, traffic splitting, and more. Also includes integrated load balancing to reduce latency and ensure high availability of application data.
  • Role-Oriented Gateway – Delegate specific configurations to application developers while allowing cluster-wide settings to be managed by cluster admins or DevOps teams.

Next steps:

X