Container Service for Kubernetes:Nginx Ingress configuration dictionary

Edit the ConfigMap

kubectl edit cm -n kube-system nginx-configuration

Default configuration

The following ConfigMap reflects the ACK defaults. Fields not listed here inherit upstream ingress-nginx defaults.

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
  namespace: <namespace>    # Default: kube-system
  labels:
    app: ingress-nginx
data:
  log-format-upstream: '$remote_addr - [$remote_addr] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id $host [$proxy_alternative_upstream_name]'
  proxy-body-size: 20m
  proxy-connect-timeout: "10"
  max-worker-connections: "65536"
  enable-underscores-in-headers: "true"
  reuse-port: "true"
  worker-cpu-affinity: "auto"
  server-tokens: "false"
  ssl-redirect: "false"
  allow-backend-server-header: "true"
  ignore-invalid-headers: "true"
  generate-request-id: "true"
  upstream-keepalive-timeout: "900"

Field descriptions

Load balancing

Example: consistent hashing by request URI

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: <your-service-name>
                port:
                  number: <your-service-port>

For clusters running Kubernetes versions earlier than 1.22, use apiVersion: networking.k8s.io/v1beta1 and the serviceName/servicePort fields under backend.

Cookie affinity

Example: cookie-based session affinity

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "route"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
spec:
  ingressClassName: nginx
  rules:
    - host: stickyingress.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: http-svc
                port:
                  number: 80

Redirects

Example: permanent redirect from `foo.com` to `bar.com`

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/permanent-redirect: "https://bar.com"
spec:
  ingressClassName: nginx
  rules:
    - host: foo.com
      http:
        paths:
          - path: "/"
            pathType: ImplementationSpecific
            backend:
              service:
                name: httpbin
                port:
                  number: 8000

Rewrites

Example: rewrite the `Host` header to `test.com` for requests to `example.com/test`

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  annotations:
    nginx.ingress.kubernetes.io/upstream-vhost: "test.com"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            pathType: ImplementationSpecific
            backend:
              service:
                name: demo-service
                port:
                  number: 80

Throttling

Use throttling annotations to limit request rates and concurrent connections per client IP address, protecting backend services from traffic spikes.

Example: rate limiting with an IP whitelist

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/limit-rate: "100K"
    nginx.ingress.kubernetes.io/limit-rps: "1"
    nginx.ingress.kubernetes.io/limit-rpm: "30"
    nginx.ingress.kubernetes.io/limit-whitelist: "10.1.10.100"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: backend-svc
                port:
                  number: 80

Fallback

Use fallback annotations to route traffic to a backup service when the primary backend is unavailable.

Canary releases

Use canary annotations to implement canary releases and blue-green deployments. For a full walkthrough, see Use the NGINX Ingress controller to implement canary releases and blue-green deployments.

Timeout

kubectl edit cm -n kube-system nginx-configuration

CORS

Configure cross-origin resource sharing (CORS) to allow browser clients to access resources from different origins. For more details, see Configure CORS on NGINX Ingresses.

Retry policies

IP address-based access control

Example: allow only a specific IP address

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/whitelist-source-range: "10.1.10.2"
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: backend-svc
                port:
                  number: 80

To apply an IP allowlist globally, edit the nginx-configuration ConfigMap and set whitelist-source-range.

Traffic mirroring

Traffic mirroring duplicates production requests to a shadow environment, letting you test new versions or configurations without affecting live traffic. For a full walkthrough, see Use an Ingress controller to mirror network traffic.

Security protection

Configure TLS to encrypt communications between clients and the NGINX Ingress controller, and between the controller and backend services. For more details, see NGINX Ingress controller encryption.

Security authentication

Use Basic Authentication to restrict access to your applications. Only requests with valid credentials are forwarded to backend services.

Set up Basic Authentication

1. Generate a password file using htpasswd:

   htpasswd -c auth joker

   Verify the file:

   cat auth
   # Expected output: joker:$apr1$R.G4krs/$hh0mX8xe4A3lYKMjvlVs1/

2. Create a Secret from the password file:

   kubectl create secret generic basic-auth --from-file=auth

3. Add the annotations to your Ingress:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-nginx
     annotations:
       kubernetes.io/ingress.class: "nginx"
       nginx.ingress.kubernetes.io/auth-type: basic
       nginx.ingress.kubernetes.io/auth-secret: basic-auth
   spec:
     ingressClassName: nginx
     rules:
       - host: example.com
         http:
           paths:
             - path: /
               pathType: Prefix
               backend:
                 service:
                   name: backend-svc
                   port:
                     number: 80