ingress-nginx Knowledge

Contents

• Overview
• Core Idea
• Key Concepts
  • IngressControllers and Ingresses
  • nginx Configuration
  • Reducing Reloads

Overview

ingress-nginx is a fully featured Kubernetes IngressController built on a specially modified version of nginx that aims to reduce the number of configuration file reloads.

Ingress objects with annotation:

metadata:
  annotations:
    kubernetes.io/ingress.class: "nginx"

will be fulfilled by the ingress-nginx IngressController, typically as unique server blocks within the nginx configuration file.

Using ingress-nginx allows you to use the nginx platform—which you may already have experience tuning and administering—to control HTTP/s routes to your cluster Services.

Core Idea

Use a modified version of nginx as your cluster’s IngressController.

Key Concepts

IngressControllers and Ingresses

An Ingress manages external network access—typically HTTP/s—to your cluster. An IngressController fulfills the functionality defined by and Ingress.

ingress-nginx fulfills the IngressController specification via a specially modified nginx instance and a mechanism for rebuilding / applying that instance’s configuration by monitoring cluster objects. Ingress objects annotated appropriately will be converted into server blocks within the nginx configuration.

While there can be multiple IngressController’s running, generally there is a single ingress-nginx pod running the nginx instance that powers all of your Ingress objects.

nginx Configuration

The Ingress object definition will configure the basic properties of the nginx server block. Additional configuration is available through:

• command line arguments to Deployment
• a Kubernetes ConfigMap object
• annotations
• a custom nginx configuration template

More information on configuration is available in the ingress-nginx reference.

Reducing Reloads

ingress-nginx listens for Kubernetes objects affecting Ingresses and builds a “point-in-time model” of the nginx configuration file reflecting the cluster state. This configuration is then compared to the current one to determine if a full config reload is required.

If a reload is deemed required, ingress-nginx will trigger one. Manual reload for most cases should not be required.

The lua-nginx-module is further used to avoid a config reload for endpoint changes.