An NGINX Ingress is an API object that provides Layer 7 load balancing to manage external access to Services in a Kubernetes cluster. Container Service for Kubernetes (ACK) allows you to use the advanced features of NGINX Ingresses to configure specific URLs to allow external access, set rewrite rules, configure HTTPS, and implement canary releases. This topic describes how to configure secure data transmission, set mutual TLS authentication, use regular expressions to specify domain names, use wildcard domain names, apply for free TLS certificates, and customize other related features.
Prerequisites
- An ACK cluster is created. For more information, see Create an ACK managed cluster.
- The NGINX Ingress controller in the cluster runs as normal.
- A kubectl client is connected to the ACK Pro cluster. For more information, see Step 2: Select a type of cluster credentials.
- A Deployment and a Service are created. For more information, see Manage Ingresses by using kubectl.
NGINX configuration
The methods that are used to configure the NGINX Ingress controller in ACK are fully compatible with the open source version of the component. For more information about the configuration methods, see NGINX Configuration.
- Annotation: You can modify annotations in the YAML template of each NGINX Ingress. The annotations take effect on individual NGINX Ingresses. For more information, see Annotations.
- ConfigMap: You can modify the kube-system/nginx-configuration ConfigMap to set a global configuration for all NGINX Ingresses. For more information, see ConfigMaps.
- Custom NGINX template: You can customize the NGINX template of an NGINX Ingress controller if the preceding methods cannot meet your requirements. For more information, see Custom NGINX template.
Configure routing rules to redirect traffic from specific URLs
After you configure the NGINX Ingress controller, the NGINX Ingress controller redirects
requests from specific URLs to the backend. For example, the NGINX Ingress controller
redirects requests from /service1/api to /service1/api/ of backend pods. If the URL of your backend service is /api, a 404 status code is returned because the URL of the backend service is different
from the requested URL. In this case, you can configure rewrite-target
to rewrite the requested URL to the URL that you want to use.
Configure rewrite rules
The nginx.ingress.kubernetes.io/rewrite-target
annotation can be used to configure basic rewrite rules. To configure advanced rewrite
rules, use the following annotations:
nginx.ingress.kubernetes.io/server-snippet
: This annotation adds custom configurations to the Server configuration block.nginx.ingress.kubernetes.io/configuration-snippet
: This annotation adds custom configurations to the Location configuration block.
Example:
annotations:
nginx.ingress.kubernetes.io/server-snippet: |
rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
nginx.ingress.kubernetes.io/configuration-snippet: |
rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;
The following example shows the configuration of the nginx.conf file:
## start server foo.bar.com
server {
server_name foo.bar.com ;
listen 80;
listen [::]:80;
set $proxy_upstream_name "-";
### Configuration of server-snippet.
rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
...
### Configuration of configuration-snippet.
rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;
...
}
## end server foo.bar.com
In addition, snippet
also supports some global configurations. For more information, see server-snippet.
For more information about how to use rewrite
rules, see Description of rewrite rules in the NGINX official document.
Configure a TLS certificate for Ingress rules
You can configure NGINX Ingress configurations to specify a TLS certificate for a website.
Configure mutual TLS authentication
The NGINX Ingress controller supports mutual TLS authentication. You may want to configure mutual TLS authentication between servers and clients to ensure the security of connections in specific scenarios.
Forward HTTPS requests from Services to backend containers
By default, the NGINX Ingress controller forwards HTTP requests to backend containers.
If your backend service uses HTTPS, you can configure the NGINX Ingress controller
to forward HTTPS requests to backend containers by adding the nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
annotation.
The following template shows the configuration of the NGINX Ingress:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: backend-https annotations: # Note: You must set the backend protocol to HTTPS. nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" spec: tls: - hosts: - <your-host-name> secretName: <your-secret-cert-name> rules: - host: <your-host-name> http: paths: - path: / backend: serviceName: <your-service-name> servicePort: <your-service-port>
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: backend-https annotations: # Note: You must set the backend protocol to HTTPS. nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" spec: tls: - hosts: - <your-host-name> secretName: <your-secret-cert-name> rules: - host: <your-host-name> http: paths: - path: / backend: service: name: <your-service-name> port: number: <your-service-port> pathType: ImplementationSpecific
Use regular expressions to specify domain names
By default, you cannot use regular expressions to specify domain names when you configure
Ingresses for Kubernetes clusters. However, you can enable Ingresses to support regular
expressions by adding the nginx.ingress.kubernetes.io/server-alias
annotation.
Specify wildcard domain names
In Kubernetes clusters, NGINX Ingresses support wildcard domain names. For example,
you can specify the wildcard domain name *. ingress-regex.com
for an Ingress.
Use annotations to implement canary releases
nginx.ingress.kubernetes.io/canary: "true"
. This section describes how to use different annotations to implement canary releases.
nginx.ingress.kubernetes.io/canary-weight
: This annotation allows you to set the percentage of requests that are sent to the specified Service. You can enter an integer from 0 to 100.nginx.ingress.kubernetes.io/canary-by-header
: This annotation enables traffic splitting based on the request header. If theheader
value isalways
, requests are distributed to new Services. If theheader
value isnever
, requests are not distributed to new Services. If theheader
value is neither always nor never, requests are distributed to new Services based on other matching rules in descending order of priority.nginx.ingress.kubernetes.io/canary-by-header-value
andnginx.ingress.kubernetes.io/canary-by-header-value
: When the values ofheader
andheader-value
in the requests match the specified values in the annotations, requests are distributed to new Services. Otherwise, if theheader
value is set to other values, requests are distributed to new Services based on other matching rules in descending order of priority.nginx.ingress.kubernetes.io/canary-by-cookie
: This annotation enables cookie-based traffic splitting. If thecookie
value isalways
, requests are distributed to new Services. If thecookie
value isnever
, requests are not distributed to new Services.
- Weight-based canary release: Set the weight of Services 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 canary release: When the request header is
ack:always
, requests are forwarded to new Services. When the request header isack:never
, requests are not distributed to new Services. If the header is neither ack:always nor ack:never, requests are distributed to new Services based on weights.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: "ack"
- Header-based canary release with custom header values: If the request header is
ack:alibaba
, requests are distributed to new Services. Otherwise, requests are distributed to new Services based on weights.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: "ack" nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba"
- Cookie-based canary release: If the request header is not matched and the request
cookie is
hangzhou_region=always
, requests are distributed to new Services.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: "ack" nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba" nginx.ingress.kubernetes.io/canary-by-cookie: "hangzhou_region"
- Cookie-based canary release does not support custom settings. The cookie value must
be
always
ornever
. - Canary releases that use different rules take effect in the following order: header-based > cookie-based > weight-based.
Use cert-manager to apply for a free TLS certificate
cert-manager is an open source tool used to manage cloud-native certificates. You can use cert-manager in Kubernetes clusters to apply for TLS certificates and enable auto-renewal for the certificates. This section describes how to apply for a free certificate and enable auto-renewal for the certificate by using cert-manager.