Annotations for Configuring Nginx Ingresses

Ingress Type

For details about how to use the preceding annotations, see Creating an Nginx Ingress Using kubectl.

Configuring a Redirection Rule

For details, see Configuring Redirection Rules for an Nginx Ingress.

Configuring a URL Rewriting Rule

For details, see Configuring URL Rewriting Rules for an Nginx Ingress.

Interconnecting with HTTPS Backend Services

For details, see Configuring HTTPS Backend Services for an Nginx Ingress.

Creating a Consistent Hashing Rule for Load Balancing

For details, see Configuring Consistent Hashing for Load Balancing of an Nginx Ingress.

Customized Timeout Interval

nginx.ingress.kubernetes.io/proxy-connect-timeout: '120'

Customizing a Body Size

nginx.ingress.kubernetes.io/proxy-body-size: 8m

Two-Way HTTPS Authentication

Nginx Ingress supports two-way HTTPS authentication between the server and client to ensure secure connections.

1. Use kubectl to access the cluster. For details, see Connecting to a Cluster Using kubectl.
2. Run the following command to create a self-signed CA certificate:

   openssl req -x509 -sha256 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 356 -nodes -subj '/CN=Ingress Cert Authority'

   Expected output:

   Generating a RSA private key
   .............++++
   ................................................++++
   writing new private key to 'ca.key'
   -----

3. Create a server certificate.
   1. Run the following command to create a request file for generating a server certificate:

      openssl req -new -newkey rsa:4096 -keyout server.key -out server.csr -nodes -subj '/CN=foo.bar.com'

      Expected output:

      Generating a RSA private key
      .....................................................++++
      ..........++++
      writing new private key to 'server.key'
      -----

   2. Run the following command to issue the server request file using the root certificate to generate the server certificate:

      openssl x509 -req -sha256 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt

      Expected output:

      Signature ok
      subject=CN = foo.bar.com
      Getting CA Private Key

4. Create a client certificate.
   1. Run the following command to create a request file for generating a client certificate:

      openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=Ingress'

      Expected output:

      Generating a RSA private key
      .................................++++
      ................................................++++
      writing new private key to 'client.key'
      -----

   2. Run the following command to issue the client request file using the root certificate to generate the client certificate:

      openssl x509 -req -sha256 -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 02 -out client.crt

      Expected output:

      Signature ok
      subject=CN = Ingress
      Getting CA Private Key

5. Run the ls command to check the created certificates.

   Expected output:

   ca.crt  ca.key  client.crt  client.csr  client.key  server.crt  server.csr  server.key

6. Run the following command to create a secret of the CA certificate:

   kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt

   Expected output:

   secret/ca-secret created

7. Run the following command to create a secret of the server certificate:

   kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key

   Expected output:

   secret/tls-secret created

8. Create a YAML file named ingress-test.yaml. The file name can be customized.

   vi ingress-test.yaml

   • For clusters of v1.23 or later:

     apiVersion: networking.k8s.io/v1
     kind: Ingress
     metadata:
       annotations:
         nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
         nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"   # Replace it with your CA certificate secret.
         nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
         nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
       name: ingress-test
       namespace: default
     spec:
       rules:
       - host: foo.bar.com
         http:
           paths:
           - backend:
               service:
                 name: nginx-test  # Replace it with the name of your target Service.
                 port: 
                   number: 80  # Replace it with the port of your target Service.
             path: /
             pathType: ImplementationSpecific
       tls:
       - hosts:
         - foo.bar.com
         secretName: tls-secret   # Replace it with your TLS certificate secret.
       ingressClassName: nginx

   • For clusters of v1.21 or earlier:

     apiVersion: networking.k8s.io/v1beta1
     kind: Ingress 
     metadata: 
       annotations: 
         kubernetes.io/ingress.class: nginx
         nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
         nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"   # Replace it with your CA certificate secret.
         nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
         nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
       name: ingress-test
       namespace: default
     spec:
       rules: 
       - host: foo.bar.com
         http: 
           paths: 
           - path: '/'
             backend: 
               serviceName: nginx-test  # Replace it with the name of your target Service.
               servicePort: 80  # Replace it with the port of your target Service.
       tls: 
       - hosts: 
         - foo.bar.com
         secretName: tls-secret   # Replace it with your TLS key certificate.

9. Run the following command to create an ingress:

   kubectl create -f ingress-test.yaml

   Expected output:

   ingress.networking.k8s.io/ingress-test created

10. Run the following command to obtain the IP address of the ingress:

    kubectl get ingress

    Expected output:

    NAME         CLASS   HOSTS         ADDRESS      PORTS     AGE
    nginx-test   nginx   foo.bar.com   10.3.xx.xx   80, 443   27m

11. Run the following command to update the IP address of the ingress into the hosts file and replace the following IP address with the actual IP address of the ingress:

    echo "10.3.xx.xx  foo.bar.com" | sudo tee -a /etc/hosts

    Expected output:

    10.3.xx.xx  foo.bar.com

12. Verify the configuration.
    • The client does not send the certificate for access.

      curl --cacert ./ca.crt  https://foo.bar.com

      Expected output:

      <html>
      <head><title>400 No required SSL certificate was sent</title></head>
      <body>
      <center><h1>400 Bad Request</h1></center>
      <center>No required SSL certificate was sent</center>
      <hr><center>nginx</center>
      </body>
      </html>

    • The client sends the certificate for access.

      curl --cacert ./ca.crt --cert ./client.crt --key ./client.key https://foo.bar.com

      Expected output:

      <!DOCTYPE html>
      <html>
      <head>
      <title>Welcome to nginx!</title>
      <style>
      body {
          width: 35em;
          margin: 0 auto;
          font-family: Tahoma, Verdana, Arial, sans-serif;
      }
      </style>
      </head>
      <body>
      <h1>Welcome to nginx!</h1>
      <p>If you see this page, the nginx web server is successfully installed and
      working. Further configuration is required.</p>
       
      <p>For online documentation and support please refer to
      <a href="http://nginx.org/">nginx.org</a>.<br/>
      Commercial support is available at
      <a href="http://nginx.com/">nginx.com</a>.</p>
       
      <p><em>Thank you for using nginx.</em></p>
      </body>
      </html>

Domain Name Regularization

Nginx Ingress allows you to configure the nginx.ingress.kubernetes.io/server-alias annotation to configure regular expressions for domain names.

1. Use kubectl to access the cluster. For details, see Connecting to a Cluster Using kubectl.
2. Create a YAML file named ingress-test.yaml. The file name can be customized.

   vi ingress-test.yaml

   For example, the regular expression ~^www\.\d+\.example\.com$,abc.example.com indicates that you can access the ingress using www.{One or more digits}.example.com and abc.example.com.

   • For clusters of v1.23 or later:

     apiVersion: networking.k8s.io/v1
     kind: Ingress
     metadata:
       annotations:
         nginx.ingress.kubernetes.io/server-alias: '~^www\.\d+\.example\.com$,abc.example.com'
       name: ingress-test
       namespace: default
     spec:
       rules:
       - host: foo.bar.com
         http:
           paths:
           - backend:
               service:
                 name: nginx-93244  # Replace it with the name of your target Service.
                 port: 
                   number: 80  # Replace it with the port of your target Service.
             path: /
             pathType: ImplementationSpecific
       ingressClassName: nginx

   • For clusters of v1.21 or earlier:

     apiVersion: networking.k8s.io/v1beta1
     kind: Ingress 
     metadata: 
       annotations: 
         kubernetes.io/ingress.class: nginx
         nginx.ingress.kubernetes.io/ server-alias: '~^www\.\d+\.example\.com$,abc.example.com'
       name: ingress-test
       namespace: default
     spec:
       rules: 
       - host: foo.bar.com
         http: 
           paths: 
           - path: '/'
             backend: 
               serviceName: nginx-test  # Replace it with the name of your target Service.
               servicePort: 80  # Replace it with the port of your target Service.

3. Run the following command to create an ingress:

   kubectl create -f ingress-test.yaml

   Expected output:

   ingress.networking.k8s.io/ingress-test created

4. Check the NGINX Ingress Controller configuration.
   1. Run the following command to check the NGINX Ingress Controller pods:

      kubectl get pods -n kube-system | grep nginx-ingress-controller

      Expected output:

      cceaddon-nginx-ingress-controller-68d7bcc67-dxxxx        1/1     Running   0          18h
      cceaddon-nginx-ingress-controller-68d7bcc67-cxxxx        1/1     Running   0          18h

   2. Run the following command to check the NGINX Ingress Controller configuration:

      kubectl exec -n kube-system cceaddon-nginx-ingress-controller-68d7bcc67-dxxxx cat /etc/nginx/nginx.conf | grep -C3 "foo.bar.com"

      Expected output:

               ## start server foo.bar.com
               server {
                        server_name foo.bar.com abc.example.com ~^www\.\d+\.example\.com$ ;
                        
                        listen 80  ;
                        listen [::]:80  ;
      --
                        }
                        
               }
               ## end server foo.bar.com

5. Run the following command to obtain the IP address of the ingress:

   kubectl get ingress

   Expected output:

   NAME         CLASS   HOSTS         ADDRESS      PORTS   AGE
   nginx-test   nginx   foo.bar.com   10.3.xx.xx   80      14m

6. Use different rules to test service access.
   • Run the following command to access the service through Host: foo.bar.com:

     curl -H "Host: foo.bar.com" 10.3.xx.xx/

     It is expected that the web page can be accessed properly.

   • Run the following command to access the service through Host: www.123.example.com:

     curl -H "Host: www.123.example.com" 10.3.xx.xx/

     It is expected that the web page can be accessed properly.

   • Run the following command to access the service through Host: www.321.example.com:

     curl -H "Host: www.321.example.com" 10.3.xx.xx/

     It is expected that the web page can be accessed properly.

Grayscale Release

Grayscale release can be enabled using annotation nginx.ingress.kubernetes.io/canary: "true" and implemented using different annotation settings.

• The preceding annotation rules are evaluated based on the following priority: canary-by-header -> canary-by-cookie -> canary-weight.
• When an ingress is marked as a canary ingress, all non-canary annotations except nginx.ingress.kubernetes.io/load-balance and nginx.ingress.kubernetes.io/upstream-hash-by will be ignored.

For more information, see Using Nginx Ingress to Implement Grayscale Release and Blue-Green Deployment.

The configuration examples of some annotations are as follows:

• Weight-based grayscale release: Set the weight of the grayscale release service to 20%.

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-weight: "20"
  ...

• Header-based grayscale release: If a request header value is cce:always, the request will be routed to the grayscale service. If a request header value is cce:never, the request will not be routed to the grayscale service. For other request header values, the request will be allocated to the grayscale service based on the grayscale weight.

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-weight: "50"
      nginx.ingress.kubernetes.io/canary-by-header: "cce"
  ...

• Header-based grayscale release (custom header value): If a request header value is cce:test, the request will be routed to the grayscale service. For other request header values, the request will be allocated to the grayscale service based on the grayscale weight.

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-weight: "20"
      nginx.ingress.kubernetes.io/canary-by-header: "cce"
      nginx.ingress.kubernetes.io/canary-by-header-value: "test"
  ...

• Cookie-based grayscale release: When a header is not matched and the requested cookie is region=always, the request will be routed to the grayscale service.

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/canary: "true"
      nginx.ingress.kubernetes.io/canary-weight: "20"
      nginx.ingress.kubernetes.io/canary-by-header: "cce"
      nginx.ingress.kubernetes.io/canary-by-header-value: "test"
      nginx.ingress.kubernetes.io/canary-by-cookie: "region"
  ...

Documentation

For details about annotation parameters supported by Nginx Ingress, see Annotations.