Container Service for Kubernetes:NGINX Ingress configuration dictionary

Table of contents

Default ConfigMap configurations

To modify the configurations of the ConfigMap used by an NGINX Ingress, run the kubectl edit cm -n kube-system nginx-configuration command. The following sample code block provides the default configurations of the ConfigMap. For more information, see Official documentation.

apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-configuration
 namespace: <Namespace>  # Default value: 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"

The following table describes the fields in the preceding code block.

Ingress annotations

When you use the NGINX Ingress controller, you can modify the controller configurations to meet your business requirements. To control the behavior of NGINX, you can add annotations to NGINX Ingresses. The following tables describe the common NGINX Ingress annotations. For more information, see NGINX Ingress annotations.

Load balancing algorithms

NGINX Ingresses provide various load balancing algorithms to optimize traffic distribution among backend services. You can select load balancing algorithms based on the features and requirements of your applications.

The following sample YAML file provides an example on how to configure consistent hashing for load balancing.

apiVersion: networking.k8s.io/v1
kind: Ingress 
metadata: 
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # Use the Uniform Resource Identifier (URI) of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # Use the URI and domain name of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # Use the URI of the request and a custom text value for hashing. 
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              service:
                name: <YOUR_SERVICE_NAME>  # Replace the value with the actual Service name.
                port:
                  number: <YOUR_SERVICE_PORT>  # Replace the value with the actual Service port.
            property:
              ingress.beta.kubernetes.io/url-match-mode: STARTS_WITH
            pathType: ImplementationSpecific
  ingressClassName: nginx

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # Use the URI of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # Use the URI and domain name of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # Use the URI of the request and a custom text value for hashing. 
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              serviceName: <YOUR_SERVICE_NAME>  # Replace the value with the actual Service name.
              servicePort: <YOUR_SERVICE_PORT>  # Replace the value with the actual Service port.

Cookie affinity

The following table describes the annotations that you can use to configure cookie-based session affinity.

The following sample YAML file provides an example on how to configure cookie-based 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

The following table describes the annotations that you can use to configure redirects for NGINX Ingresses.

The following sample Ingress configurations show how to specify the destination URL for permanent redirects. After you implement the Ingress rules, requests to foo.com are redirected 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

The following table describes the annotations that you can use to configure rewrites for NGINX Ingresses.

The following sample Ingress configurations show how to configure host rewrites. After you implement the Ingress rules, the system rewrites the hostnames of requests to example.com/test as test.com/test.

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

Throttling

To ensure service stability, you can configure throttling policies to control the frequency and concurrency of requests that are sent from each client IP address. The following table describes the annotations that you can use to configure throttling.

The following sample Ingress configurations show how to configure throttling:

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-whitelist: 10.1.10.100
    nginx.ingress.kubernetes.io/limit-rps: 1
    nginx.ingress.kubernetes.io/limit-rpm: 30
spec:
  rules:
  - host: iphone.example.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-backend-svc
          servicePort: 80

Fallback

To ensure high availability and stability of your service, NGINX Ingresses provide disaster recovery (fallback) configurations to allow you to resolve issues such as node unavailability and specific errors. The following table describes the annotations that you can use to configure disaster recovery.

Canary releases

Canary releases and blue-green deployments are widely used to ensure seamless application upgrades and high availability. The following table describes the annotations that you can use to configure flexible traffic control to meet various requirements for service releases. For more information, see Use the NGINX Ingress controller to implement canary releases and blue-green releases.

Timeout

The following table describes the annotations that you can use to configure timeout for NGINX Ingresses, including global configurations and custom timeout settings for specific resources. Proper timeout settings can optimize connection performance and reliability.

• Global timeout settings

  You can run the kubectl edit cm -n kube-system nginx-configuration command to configure the following fields for global timeout settings.

  Configuration option	Description	Default value
  proxy-connect-timeout	Sets the timeout period for establishing a connection with the proxy server. In general, the value cannot exceed 75s.	5s
  proxy-read-timeout	Sets the timeout period for reading a response from the proxy server. This timeout period applies between two consecutive read operations, rather than to the transmission of the entire response.	60s
  proxy-send-timeout	Sets the timeout period for sending a request to the proxy server. This timeout period applies between two consecutive write operations, rather than to the transmission of the entire request.	60s
  proxy-stream-next-upstream-timeout	Limits the amount of time allowed to pass a connection to the next server. If you set the value to 0, no limit is imposed.	600s
  proxy-stream-timeout	Sets the timeout period between two consecutive read or write operations on a client or proxy server connection. If no data is transmitted within the period, the connection is closed.	600s
  upstream-keepalive-timeout	Sets a timeout period for keeping an idle connection open with upstream servers.	Open source edition: 60s ACK edition: 900s
  worker-shutdown-timeout	Sets the timeout period for a graceful shutdown.	240s
  proxy-protocol-header-timeout	Sets the timeout period for receiving the proxy protocol header. The default value prevents the Transport Layer Security (TLS) passthrough handler from waiting indefinitely for a broken connection.	5s
  ssl-session-timeout	Sets the validity period for SSL session parameters in the session cache. The expiration time is subject to the creation time. Each session cache occupies about 0.25 MB of space.	10m
  client-body-timeout	Sets the timeout period for reading the client request body.	60s
  client-header-timeout	Sets the timeout period for reading the client request headers.	60s

• Custom timeout settings on specific resources

  The following table describes the annotations that you can use to configure timeout settings for specific resources.

  Annotation	Description
  nginx.ingress.kubernetes.io/proxy-connect-timeout	Sets the timeout period for establishing a connection with the proxy server.
  nginx.ingress.kubernetes.io/proxy-send-timeout	Sets the timeout period for sending data to the proxy server.
  nginx.ingress.kubernetes.io/proxy-read-timeout	Sets the timeout period for reading data from the proxy server.
  nginx.ingress.kubernetes.io/proxy-request-buffering	Specifies whether to enable the request buffering feature. Valid values: on: enables request buffering. After request buffering is enabled, the request data is forwarded to the backend workload only after it is completely received. HTTP/1.1 chunked-encoded requests are not subject to this setting and are always buffered. off: disables request buffering. After request buffering is disabled, if an error occurs during the data transmission, no workload is selected for a retry.

CORS

After you configure cross-origin resource sharing (CORS) for the NGINX Ingress controller, you can allow the specified resources to be accessed across origins. For more information, see Configure CORS on NGINX Ingresses.

Retry policies

The following table describes the annotations that you can use to configure retry policies. Retries can improve the availability and fault tolerance of your applications.

IP address-based access control

The following table describes the annotations that you can use to configure IP whitelists and blacklists for NGINX Ingresses.

The following sample Ingress configurations show how to configure an IP whitelist:

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:
  rules:
  - host: iphone.exmaple.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-example-svc
          servicePort: 80

To configure global configurations, run the kubectl edit cm -n kube-system nginx-configuration command and modify the whitelist-source-range field.

Traffic mirroring

The following table describes the annotations that you can use to configure traffic mirroring. Traffic mirroring helps you detect potential risks without interrupting your services in the production environment and improve application stability. For more information, see Use an Ingress controller to mirror network traffic.

Security protection

You can configure security protection to secure communications between clients and gateways. The following tables describe the annotations that you can use to encrypt communications. For more information, see NGINX Ingress controller encryption.

• Encrypted communications between clients and gateways

  The following table describes the annotations that you can use to encrypt communications between clients and gateways.

  Annotation	Scope	Description
  nginx.ingress.kubernetes.io/ssl-cipher	Domain name	Specifies the TLS cipher suites. You can specify multiple TLS cipher suites, which are separated by commas (,). This parameter takes effect only if a TLS version from 1.0 to 1.2 is used during a TLS handshake. Default cipher suites: ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES128-SHA AES128-GCM-SHA256 AES128-SHA ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-SHA ECDHE-RSA-AES256-SHA AES256-GCM-SHA384 AES256-SHA
  nginx.ingress.kubernetes.io/auth-tls-secret	Domain name	Specifies the certificate authority (CA) certificate that a gateway uses to verify the certificate provided by a client during a mutual TLS (mTLS) handshake. This annotation is suitable for scenarios in which a gateway needs to verify the identity of a client. The corresponding Secret must include a file named ca.crt. The ca.crt file contains a complete CA chain.

• Encrypted communications between gateways and backend services

  The following table describes the annotations that you can use to encrypt communications between backend services and gateways.

  Annotation	Scope	Description
  nginx.ingress.kubernetes.io/proxy-ssl-secret	Service	Specifies the client certificate that is used by the gateway. The client certificate is used by the backend service to authenticate the gateway. The specified certificate must be in the Privacy Enhanced Mail (PEM) format. The Secret must include the following files: tls.crt: the client certificate. tls.key: the private key of the client certificate. ca.crt: the trusted CA certificate used to authenticate proxy HTTPS servers. The value must be in the "namespace/secretName" format.
  nginx.ingress.kubernetes.io/proxy-ssl-name	Service	Specifies the Server Name Indication (SNI) that is used during a TLS handshake.
  nginx.ingress.kubernetes.io/proxy-ssl-server-name	Service	Specifies whether to enable or disable the SNI that is used during a TLS handshake.

Security authentication

The following table describes the annotations that you can use to configure Basic Authentication to allow only authorized users to access your applications.

Procedure:

1. Use the htpasswd command-line tool to generate a password file.

   htpasswd -c auth joker

   View the password file.

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

2. Create a Secret based on the password file:

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

3. Enable Basic Authentication in the Ingress configurations. Example:

   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:
     rules:
     - host: iphone.example.com 
       http:
         paths:
         - path: 
           backend:
             serviceName: iphone-backend-svc
             servicePort: 80