Nginx Ingress Annotations

Specifying an Ingress Class

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

Client IP Address Restrictions (Blacklist/Whitelist)

For details about applications and use cases, see Restricting Client IP Addresses for Nginx Ingresses.

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 Accessing 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=example.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 = example.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. You can change the file name if you want to.

   vi ingress-test.yaml

   • For clusters 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: example.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:
         - example.com
         secretName: tls-secret   # Replace it with your TLS certificate secret.
       ingressClassName: nginx

   • For clusters 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: example.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: 
         - example.com
         secretName: tls-secret   # Replace it with your TLS certificate secret.

9. Run the following command to create the 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   example.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  example.com" | sudo tee -a /etc/hosts

    Expected output:

    10.3.xx.xx  example.com

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

      curl --cacert ./ca.crt  https://example.com -k

      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://example.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>

Interconnecting with HTTPS/gRPC Backend Services

For details about application scenarios and use cases, see Configuring HTTPS Backend Services for an Nginx Ingress or Configuring gRPC Backend Services for an Nginx Ingress.

Configuring a Redirection Rule

For details about application scenarios and use cases, see Configuring Redirection Rules for an Nginx Ingress.

Configuring a URL Rewriting Rule

For details about application scenarios and use cases, see Configuring URL Rewriting Rules for an Nginx Ingress.

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 Accessing a Cluster Using kubectl.
2. Create a YAML file named ingress-test.yaml. You can change the file name if you want to.

   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 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: example.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 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: example.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 the 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 -- bash -c 'cat /etc/nginx/nginx.conf | grep -C3 "example.com"'

      Expected output:

               ## start server example.com
               server {
                        server_name example.com abc.example.com ~^www\.\d+\.example\.com$ ;
                        
                        listen 80  ;
                        listen [::]:80  ;
      --
                        }
                        
               }
               ## end server example.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   example.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: example.com:

     curl -H "Host: 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.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.

Customized Timeout Interval

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

Customizing a Body Size

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

Creating a Consistent Hashing Rule for Load Balancing

For details about application scenarios and use cases, see Configuring Consistent Hashing for Load Balancing of an Nginx Ingress.

Traffic Mirroring

For details about applications and use cases, see Configuring Application Traffic Mirroring for an Nginx Ingress.

Cross-Origin Access

nginx.ingress.kubernetes.io/enable-cors: "true"

nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"

nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH, OPTIONS"

nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range"

nginx.ingress.kubernetes.io/cors-allow-credentials: "true"

nginx.ingress.kubernetes.io/cors-expose-headers: "Content-Length,Content-Range"

nginx.ingress.kubernetes.io/cors-max-age: "3600"

For details about applications and use cases, see Configuring Cross-Origin Access for Nginx Ingresses.