Container Service for Kubernetes:Nginx Ingress O&M basics

Configuration file structure

NGINX reads its configuration from /etc/nginx/nginx.conf. The file is organized into five nested blocks:

A typical nginx.conf looks like this:

# Number of worker processes
worker_processes 4;

# Include additional config files
include /etc/nginx/conf.d/*.conf;

http {
  server {
    listen 80;
    server_name www.example.com;

    location / {
      root /var/www/html;
      index index.html;
    }
  }
}

For the full directive reference, see the NGINX core module documentation.

HTTP block

The HTTP block sets global parameters for all virtual hosts:

http {
    worker_processes 4;
    worker_rlimit_nofile 8192;
    client_max_body_size 128m;

    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    server {
        ...
    }
}

Server block

A Server block defines traffic-handling rules for a specific domain or group of domains. Multiple Server blocks can be nested under the HTTP block, letting you host multiple websites on the same server with independent configurations.

server {
    listen 80;
    server_name www.example.com;

    location / {
        root /var/www/html/example;
        index index.html index.htm;
    }

    location /app {
        proxy_pass http://localhost:3000;
    }

    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /usr/share/nginx/html;
    }
}

Location block

A Location block routes requests to different handlers based on URL path. When multiple Location blocks match a request, NGINX applies them according to a fixed priority order.

Matching rules (in priority order):

Priority: = > ^~ > ~ / ~* > (no modifier) > /

location = / { }          # Exact match for root only

location ^~ /xx/ { }      # Any path starting with /xx/; stops regex evaluation

location /uri { }          # Prefix match (lower priority than regex)

location / { }             # General match: catches everything else

location ~* \.(gif|jpg|jpeg)$ { }  # Any request ending with an image extension

An NGINX Ingress sorts multiple Ingress paths for a host in descending order of length. For more information, see Ingress path matching and Understanding NGINX server and location block selection algorithms.

Directive inheritance

Directives cascade from outer contexts to inner ones: http{} settings are inherited by all server{} and location{} blocks. If a directive appears in both a parent and child context, the child's value overrides (does not merge with) the parent's value.

http {
    add_header X-HTTP-LEVEL-HEADER 1;
    add_header X-ANOTHER-HTTP-LEVEL-HEADER 1;

    server {
        listen 8080;
        location / {
            return 200 "OK";
            # Inherits both X-HTTP-LEVEL-HEADER and X-ANOTHER-HTTP-LEVEL-HEADER
        }
    }

    server {
        listen 8081;
        add_header X-SERVER-LEVEL-HEADER 1;
        # This overrides http-level add_header directives in this server block

        location /correct {
            # Must explicitly repeat all desired headers at this level
            add_header X-HTTP-LEVEL-HEADER 1;
            add_header X-ANOTHER-HTTP-LEVEL-HEADER 1;
            add_header X-SERVER-LEVEL-HEADER 1;
            add_header X-LOCATION-LEVEL-HEADER 1;
            return 200 "OK";
        }
    }
}

Reverse proxy directives

To configure NGINX as a reverse proxy, use proxy_pass inside a Location block:

server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://localhost:3000;
    }
}

proxy_set_header adds or overrides headers sent to the backend server — here, it preserves the original hostname and client IP.

Common proxy directives:

Common NGINX commands

Architecture

The NGINX Ingress controller integrates the control plane and data plane in each pod — one controller process plus the NGINX processes.

Configuration sync and when reloads happen

The controller watches Kubernetes resources — Ingresses, Services, pods, and endpoints — and syncs changes to either the nginx.conf file or a Lua table. The Lua table mainly includes configurations of upstream server endpoints, canary releases, and certificates. Changes to these configurations also trigger updates to the nginx.conf file, thereby triggering a reload.

For the full list of reload triggers, see When a reload is required in the NGINX Ingress community documentation.

Startup arguments

The controller reads startup arguments from the Deployment or Pod spec:

containers:
  - args:
    - /nginx-ingress-controller
    - --election-id=ingress-controller-leader-nginx
    - --ingress-class=nginx
    - --watch-ingress-without-class
    - --controller-class=k8s.io/ingress-nginx
    - --configmap=$(POD_NAMESPACE)/nginx-configuration
    - --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
    - --udp-services-configmap=$(POD_NAMESPACE)/udp-services
    - --annotations-prefix=nginx.ingress.kubernetes.io
    - --publish-service=$(POD_NAMESPACE)/nginx-ingress-lb
    - --enable-annotation-validation
    - --validating-webhook=:8443
    - --validating-webhook-certificate=/usr/local/certificates/cert
    - --validating-webhook-key=/usr/local/certificates/key
    - --v=2

For the full argument reference, see Command line arguments.

Load balancing

NGINX Ingress supports two global load balancing algorithms. Set the global default via the ConfigMap; override per-Ingress with annotations.

For session cookie-based affinity, use the nginx.ingress.kubernetes.io/affinity annotation. For IP or header-based consistent hashing, use nginx.ingress.kubernetes.io/upstream-hash-by.

Implementation references:

• EWMA

• Consistent hash

• Round robin

• Sticky

Timeout configuration

Custom snippet configuration

Inject raw NGINX directives into specific configuration blocks using snippet annotations:

Core data plane modules

Built-in NGINX modules used by the data plane:

• ngx_http_core_module

• ngx_http_proxy_module

• ngx_http_upstream_module

• ngx_http_ssl_module

• ngx_http_sub_module

• ngx_stream_core_module

Third-party modules:

• ngx_http_opentracing_module — Integrated in Container Service for Kubernetes (ACK). Enables tracing with Application Real-Time Monitoring Service (ARMS). See Enable tracing for NGINX Ingress Controller.

• OpenTelemetry for NGINX — Enable via ConfigMap:

  data:
    enable-opentelemetry: "true"
    otlp-collector-host: "otel-coll-collector.otel.svc"

For the full NGINX module reference, see NGINX official documentation.

Lua initialization blocks

The data plane uses several Lua initialization blocks in the HTTP context:

init_by_lua_block {
    collectgarbage("collect")
    local ok, res
    ok, res = pcall(require, "lua_ingress")
    -- ... loads: configuration, balancer, monitor, certificate, plugins
}

init_worker_by_lua_block {
    lua_ingress.init_worker()
    balancer.init_worker()
    monitor.init_worker(10000)
    plugins.run()
}

upstream upstream_balancer {
    server 0.0.0.1; # placeholder
    balancer_by_lua_block {
        balancer.balance()
    }
    keepalive 8000;
    keepalive_time 1h;
    keepalive_timeout 60s;
    keepalive_requests 10000;
}

Logs

access_log off;
error_log  /var/log/nginx/error.log notice;

The default configuration disables access logging and sets the error log level to notice. This is the NGINX process log level, configured separately from the controller log verbosity (--v flag described above).

Supported log levels (least to most verbose): emerg, alert, crit, error, warn, notice, info, debug.

To filter warning and error entries from pod logs:

kubectl logs -f <nginx-ingress-pod-name> -n kube-system | grep -E '^[WE]'