The NGINX Ingress Controller serves as the ingress gateway for Alibaba Cloud Container Service for Kubernetes (ACK) managed clusters, routing external traffic to internal services with flexible routing rules. By supporting features such as HTTPS encryption, canary releases, and custom configurations through annotations, it provides secure, high-availability, and scalable Layer 7 (L7) network access.
-
Effective September 11, 2025, due to the discontinuation of specification-based billing for Classic Load Balancer (CLB), Network Load Balancer (NLB) instances will be used by default when you create load balancer-type services or install new NGINX Ingress Controllers in the Container Service for Kubernetes console. Creation of CLB-based services will be restricted to an allowlist, and these services will use the pay-as-you-go billing model by default. For more information, see [Product change] Announcement on changes to the default load balancer type and billing method for new services and the NGINX Ingress Controller.
-
The upstream open-source Ingress-NGINX project will no longer be maintained after March 2026. As a result, Container Service for Kubernetes will discontinue maintenance for the NGINX Ingress Controller component. Please be aware of the associated risks. For more information, see [Product announcement] Announcement on the end of maintenance for the NGINX Ingress Controller component.
Usage notes
-
Do not delete the default service used by the NGINX Ingress Controller. After the add-on is installed, a default service named
nginx-ingress-lbis created in thekube-systemnamespace. Deleting this service makes the add-on unstable and can cause it to crash. -
Use Add-ons or OpenAPI to configure custom parameters for the add-on. Modifying the configuration through other methods can cause the add-on to malfunction and interfere with future upgrades.
-
Use the NGINX Ingress ConfigMap for custom configurations. Technical support does not cover issues caused by additional configurations, such as snippets or Lua code.
-
Upgrade the NGINX Ingress Controller add-on promptly to prevent business disruptions caused by bugs or security vulnerabilities in the upstream community version.
Install the NGINX Ingress Controller add-on
Create a sample application
The sample application deploys two stateless workloads (Deployments) named coffee and tea, and their corresponding Services named coffee-svc and tea-svc.
Console
|
1. Create resources
|
|
2. View the result In the YAML Resource Creation Result dialog box, click View in the Actions column for a resource to confirm that it has been created. |
kubectl
-
Obtain the KubeConfig for your cluster and use kubectl to connect to the cluster.
-
Create a file named test-deployment-service.yaml with the following content.
-
Apply the configuration to create the Deployment and Service.
kubectl apply -f test-deployment-service.yaml -
Verify the status of the
coffeeandteaDeployments.kubectl get deployment coffee teaExpected output:
NAME READY UP-TO-DATE AVAILABLE AGE coffee 2/2 2 2 14m tea 2/2 2 2 14m -
Verify the status of the
coffee-svcandtea-svcServices.kubectl get service coffee-svc tea-svcExpected output:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE coffee-svc ClusterIP 192.168.xxx.xxx <none> 80/TCP 15m tea-svc ClusterIP 192.168.xxx.xxx <none> 80/TCP 15m
Create NGINX Ingress
This example uses test-nginx-ingress.com as the domain name (host). Replace this with your own registered domain name. The path mapping (paths) is taken from the Create a sample application example. Modify these paths to match your application's configuration.
Console
|
1. Create an Ingress
|
|
2. Obtain the endpoint After about one minute, refresh the page. The Nginx Ingress is successfully created when an Elastic IP (EIP) appears in the Endpoint column. This EIP is the public service address of the associated Cloud Load Balancer (CLB) instance. If the endpoint information does not appear after a few minutes, click the Ingress name and check the Events tab for troubleshooting. |
kubectl
-
Create a file named test-ingress.yaml with the following content.
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: test-nginx-ingress namespace: default spec: ingressClassName: nginx rules: - host: test-nginx-ingress.com # Replace with your registered domain name http: paths: - path: /coffee backend: service: name: coffee-svc port: number: 80 pathType: ImplementationSpecific - path: /tea backend: service: name: tea-svc port: number: 80 pathType: ImplementationSpecific - host: www.test-nginx-ingress.com # Replace with your registered domain name http: paths: - path: /coffee backend: service: name: coffee-svc port: number: 80 pathType: ImplementationSpecific - path: /tea backend: service: name: tea-svc port: number: 80 pathType: ImplementationSpecificParameter descriptions:
-
name: The name of the Ingress. In this example, the name istest-nginx-ingress. -
host: The domain name used to access the service. In this example, the domain name istest-nginx-ingress.com. Replace this with your registered domain name. -
path: The URL path for the rule. For a request to be routed to the backend, it must match the specified host and path. In this example, the paths are/coffeeand/tea. -
backend: Consists of a service name and a service port.-
Service name: The name of the backend service to which the Ingress forwards traffic. For example,
coffee-svcandtea-svc. -
Service port: The target port on the backend Service. In this example, the port is
80.
-
-
-
Create the Ingress.
kubectl apply -f test-ingress.yaml -
View the Ingress and obtain its Elastic IP (EIP), such as
8.xxx.xxx.117.kubectl get ingressExpected output:
NAME CLASS HOSTS ADDRESS PORTS AGE test-nginx-ingress nginx test-nginx-ingress.com,www.test-nginx-ingress.com 8.xxx.xxx.117 80 2m39s -
Use the EIP to verify that the Nginx Ingress is working correctly.
curl http://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"Expected output:
... <title>Hello World</title> ... <p><span>Server address:</span> <span>10.xxx.xxx.19:80</span></p> <p><span>Server name:</span> <span>coffee-96d4bc87-l29dh</span></p> <p class="smaller"><span>Date:</span> <span>08/Aug/2025:02:21:02 +0000</span></p> <p class="smaller"><span>URI:</span> <span>/coffee</span></p> ... <div id="footer"> <div id="center" align="center"> Request ID: 42e2d73c85b16b55b6ab52deb7d995d4<br/> © NGINX, Inc. 2018 </div> </div> ...
Configure DNS resolution
Register a domain name. You only need to add a domain name if it is registered with a third-party provider. Alibaba Cloud automatically adds domain names purchased through its platform to the public authoritative zones in Alibaba Cloud DNS, so you can directly add DNS records.
|
1. Add a domain name
|
|
2. Add a DNS record
For more information, see Add a website resolution record. |
|
3. Verify the domain name and path In your browser, visit If the request succeeds, the page returns information from the NGINX backend pod, including the server address, server name, Date, and URI fields. To confirm the result, you can also refer to Methods for testing DNS resolution. If a DNS record does not take effect, see Quickly troubleshoot DNS resolution failures. |
Configure HTTPS security
Purchase a commercial certificate, and apply for the certificate. Ensure the certificate is in the Issued state. Then, follow these steps to download the certificate and add a TLS configuration. This enables encrypted HTTPS access to your domain.
Console
|
1. Download the certificate
For more details, see Download an SSL certificate. |
|
2. Create a Secret
|
|
3. Add a TLS configuration
|
|
4. Verify HTTPS access In your web browser, go to |
Kubectl
-
Log on to the Certificate Management Service console. In the left-side navigation pane, choose .
-
On the Commercial Certificates tab, select the certificate you want to download, and click Download in the bottom-left corner of the certificate list.
-
In the dialog box that appears, select Nginx as the server type, download the certificate package, and decompress it.
-
Use the downloaded certificate file (.pem) and private key file (.key) to create a Secret.
kubectl create secret tls nginx-ingress-tls --cert test-nginx-ingress.com.pem --key test-nginx-ingress.com.key -n default -
Add a TLS configuration to the
test-nginx-ingressIngress. Replacetest-nginx-ingress.comin the command with your actual registered domain name.kubectl patch ingress test-nginx-ingress -p '{"spec":{"tls":[{"hosts":["test-nginx-ingress.com"],"secretName":"nginx-ingress-tls"}]}}' -
Verify encrypted HTTPS access to the service path by running the following command with your actual Elastic IP Address.
curl -v -k https://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"-
Parameters:
-
-v: Displays verbose output, including the TLS handshake. -
-k(or --insecure): Skips certificate verification. Use this option if you are using a self-signed certificate.
-
-
Expected output:
... * Trying 8.xxx.xxx.117:443... * Connected to 8.xxx.xxx.117 (8.xxx.xxx.117) port 443 * ALPN: curl offers h2,http/1.1 * (304) (OUT), TLS handshake, Client hello (1): * (304) (IN), TLS handshake, Server hello (2): * (304) (IN), TLS handshake, Unknown (8): * (304) (IN), TLS handshake, Certificate (11): * (304) (IN), TLS handshake, CERT verify (15): * (304) (IN), TLS handshake, Finished (20): * (304) (OUT), TLS handshake, Finished (20): ... <title>Hello World</title> ... <p><span>Server address:</span> <span>10.xxx.xxx.159:80</span></p> <p><span>Server name:</span> <span>coffee-96d4bc87-6cstv</span></p> <p class="smaller"><span>Date:</span> <span>14/Aug/2025:09:27:42 +0000</span></p> <p class="smaller"><span>URI:</span> <span>/coffee</span></p> ... <div id="footer"> <div id="center" align="center"> Request ID: fee5fe107106748a35d99a2dbbbc6652<br/> © NGINX, Inc. 2018 </div> </div> ...
-
More configurations
Canary release
To upgrade services, you can use various deployment strategies, such as rolling updates, phased releases, blue-green deployments, and canary releases. For detailed instructions, see Implement phased releases and blue-green deployments using NGINX Ingress.
Backend service protocol
To specify the protocol for a backend service, add the nginx.ingress.kubernetes.io/backend-protocol annotation. The supported protocols are HTTP, HTTPS, gRPC, and gRPCS. For a configuration example, see Configure a gRPC service for NGINX Ingress.
URL rewrite
When you use the NGINX Ingress controller, it forwards requests based on the full path. For example, a request to /service1/api is forwarded to the /service1/api path of the backend pod. If your backend service's path is /api, a path mismatch occurs, resulting in a 404 error. To resolve this issue, you can add the nginx.ingress.kubernetes.io/rewrite-target annotation to rewrite the request path to the correct directory.
For detailed instructions, see Configure URL redirection.
Annotations
NGINX Ingress supports an extensive range of features that you can enable with annotations. For more information, see NGINX Ingress configuration dictionary and Advanced NGINX Ingress configurations.
Observability
Enable Simple Log Service (SLS) during cluster creation to access comprehensive NGINX Ingress access log analysis reports and real-time monitoring dashboards. For details, see Analyze and monitor NGINX Ingress access logs.
High-load scenarios
To improve the performance and stability of the NGINX Ingress Controller in high-load scenarios, see Configure an NGINX Ingress Controller for high-payload scenarios and Suggestions for using an NGINX Ingress Controller.
FAQ
Unreachable external IP from within a cluster
Large headers or cookies
CORS configuration
Client IP pass-through
References
-
For versions and release notes, see NGINX Ingress Controller.
-
For common issues and troubleshooting, see NGINX Ingress FAQ and Troubleshoot NGINX Ingress issues.