Container Service for Kubernetes:Nginx Ingress configuration dictionary

Edit the ConfigMap

kubectl edit cm -n kube-system nginx-configuration

Default configuration

The following ConfigMap shows ACK defaults. Unlisted fields 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 Kubernetes clusters 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

Limit request rates and concurrent connections per client IP to protect 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

Route traffic to a backup service when the primary backend is unavailable.

Canary releases

Implement canary releases and blue-green deployments. See Use the NGINX Ingress controller to implement canary releases and blue-green deployments.

Timeout

kubectl edit cm -n kube-system nginx-configuration

CORS

Enable cross-origin resource sharing (CORS) for browser requests. 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 globally, set whitelist-source-range in the nginx-configuration ConfigMap.

Traffic mirroring

Duplicate production requests to a shadow environment for testing without affecting live traffic. See Use an Ingress controller to mirror network traffic.

Security protection

Configure TLS encryption between clients and the NGINX Ingress controller, and between the controller and backend services. See NGINX Ingress controller encryption.

Security authentication

Restrict access with Basic Authentication. Only authenticated requests reach backend services.

Set up Basic Authentication

1. Generate a password file with 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