Configuring Nginx Ingresses Using Annotations¶
The nginx-ingress add-on in CCE uses the community chart and image. If the default add-on parameters cannot meet your demands, you can add annotations to define what you need, such as the default backend, timeout, and size of a request body.
This section describes common annotations used for creating an ingress of the Nginx type.
Note
The key value of an annotation can only be a string. Other types (such as Boolean values or numeric values) must be enclosed in quotation marks (""), for example, "true", "false", and "100".
Nginx Ingress supports native annotations of the community. For details, see Annotations.
Ingress Type¶
Parameter | Type | Description | Supported Cluster Version |
|---|---|---|---|
kubernetes.io/ingress.class | String |
This parameter is mandatory when an ingress is created by calling the API. For clusters of v1.23 or later, use the parameter ingressClassName. For details, see Using kubectl to Create an Nginx Ingress. | Only clusters of v1.21 or earlier |
For details about how to use the preceding annotations, see Using kubectl to Create an Nginx Ingress.
Interconnecting with HTTPS Backend Services¶
Parameter | Type | Description |
|---|---|---|
nginx.ingress.kubernetes.io/backend-protocol | String | If this parameter is set to HTTPS, HTTPS is used to forward requests to the backend service container. |
For details, see Configuring HTTPS Backend Services for an Nginx Ingress.
Creating a Consistent Hashing Rule for Load Balancing¶
Parameter | Type | Description |
|---|---|---|
nginx.ingress.kubernetes.io/upstream-hash-by | String | Enable consistent hashing for load balancing for backend servers. The parameter value can be an Nginx parameter, a text value, or any combination. For example:
|
For details, see Configuring Consistent Hashing for Load Balancing of an Nginx Ingress.
Customized Timeout Interval¶
Parameter | Type | Description |
|---|---|---|
nginx.ingress.kubernetes.io/proxy-connect-timeout | String | Customized connection timeout interval. You do not need to set the unit when setting the timeout interval. The default unit is second. Example: nginx.ingress.kubernetes.io/proxy-connect-timeout: '120'
|
Customizing a Body Size¶
Parameter | Type | Description |
|---|---|---|
nginx.ingress.kubernetes.io/proxy-body-size | String | When the body size in a request exceeds the upper limit, error 413 will be returned to the client. You can use this parameter to adjust the upper limit of the body size. The basic unit of the parameter value is byte. You can use units such as KB, MB, and GB. The unit conversion is as follows: 1 KB = 1024 bytes, 1 MB = 1024 KB, 1 GB =1024 MB Example: 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.
Use kubectl to access the cluster. For details, see Connecting to a Cluster Using kubectl.
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' -----
Create a server certificate.
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' -----
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
Create a client certificate.
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' -----
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
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
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
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
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.
Run the following command to create an ingress:
kubectl create -f ingress-test.yaml
Expected output:
ingress.networking.k8s.io/ingress-test created
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
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
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.
Use kubectl to access the cluster. For details, see Connecting to a Cluster Using kubectl.
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.
Run the following command to create an ingress:
kubectl create -f ingress-test.yaml
Expected output:
ingress.networking.k8s.io/ingress-test created
Check the Nginx Ingress Controller configuration.
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
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
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
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.
Documentation¶
For details about annotation parameters supported by Nginx Ingress, see Annotations.