In Alibaba Cloud Container Service for Kubernetes (ACK) managed clusters, the NGINX Ingress Controller acts as the primary L7 entry point, precisely routing external traffic to internal services based on flexible rules. It supports HTTPS encryption, canary releases, and custom configurations via annotations to meet high-availability and security requirements.
Due to the discontinuation of specification-based billing for Classic Load Balancers (CLB), starting August 28, 2025, new installations of the NGINX Ingress Controller via the ACK console will default to Network Load Balancer (NLB) instances.
CLB instances are restricted to whitelist only.
If a CLB is still required, it will default to a pay-as-you-go (usage-based) billing model. See the Product change announcement.
Usage notes
Do not delete default services: Upon installation, a service named
nginx-ingress-lbis created in thekube-systemnamespace. Deleting this service will destabilize the controller and may cause system crashes.Use standard configuration methods: Always use the Add-ons page in the console or OpenAPI to configure custom parameters. Manual modifications via other channels may cause upgrade failures or functional errors.
Prioritize ConfigMaps: Use the NGINX Ingress ConfigMap for custom requirements. Technical support is not provided for issues arising from custom snippets or Lua code.
Keep the add-on updated: Regularly upgrade NGINX Ingress Controller to patch upstream community bugs and security vulnerabilities.
Prerequisites
NGINX Ingress Controller is installed.
NoteAfter installation, the controller is associated with a CLB instance that serves as the traffic entry point for the NGINX Ingress.
You have obtained the kubeconfig file of the cluster and used kubectl to connect to the cluster.
You have registered a domain name.
You have purchased a commercial certificate and submit an application to a CA. The certificate is in the Issued state.
Create a sample application
This example deploys two stateless workloads (deployments) named coffee and tea, and their corresponding ClusterIP services.
Console
1. Create resources
|
|
2. View the creation result In the YAML Resource Creation Result dialog box, click View in the Actions column for a resource to confirm the creation result. |
|
kubectl
Create a file named test-deployment-service.yaml with the following content:
Apply the configuration.
kubectl apply -f test-deployment-service.yamlVerify 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 14mView 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 an NGINX Ingress
In the following example, the domain name (host field) in the rules uses test-nginx-ingress.com as a placeholder. Replace it with your actual registered domain name. Similarly, the path mappings (paths field) in the rules use the sample application created earlier. Update it to match your specific application configuration.
Console
1. Create resources
|
|
2. Obtain the endpoint Wait for about a minute after creation, then click the refresh button in the upper-right corner. If the Endpoint column shows an Elastic IP (EIP) as the service address for the associated public CLB instance, the NGINX Ingress was created successfully. If the endpoint information is not updated after a long time, click the Ingress name and check the Events tab for errors. |
|
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 actual 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 actual 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: ImplementationSpecificKey parameter 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 actual registered domain.path: The URL path for the rule. All inbound requests must match thehostandpathbefore the CLB forwards traffic to thebackend. In this example, the paths are/coffeeand/tea.backend: Defines the destination where traffic should be sent, consisting of a service name and port.Service name: The name of the backend service to which the Ingress forwards traffic. In this example, the service names are
coffee-svcandtea-svc.Service port: The port exposed by the service. In this example, the port is
80.
Create the Ingress.
kubectl apply -f test-ingress.yamlView the Ingress details and obtain its public IP address, 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 2m39sReplace the placeholder IP with your actual public IP address and run the following command to verify that the NGINX Ingress is functioning correctly:
curl http://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"Expected output:
... <title>Hello World</title> ... <p>Server address:10.xxx.xxx.19:80Server name:coffee-96d4bc87-l29dhDate:08/Aug/2025:02:21:02 +0000URI:/coffee
Configure DNS resolution
Adding a domain name is only required for domains registered with third-party providers (non-Alibaba Cloud domains). Domains purchased through Alibaba Cloud are automatically synchronized to the DNS console, allowing you to add resolution records directly.
1. Add a domain name
|
|
2. Add a DNS record
For more information, see Add a website resolution record. |
|
3. Verify DNS and path resolution In your browser, access You can also refer to Methods for testing DNS resolution to confirm the result. If the resolution fails, see Quickly troubleshoot DNS resolution failures. |
|
Configure HTTPS/TLS encryption
Before proceeding, ensure you have purchased and applied for a certificate as described in the Prerequisites section. Follow these steps to download the certificate and add the TLS configuration to enable encrypted HTTPS communication.
Console
1. Download the certificate
For more information, see Download an SSL certificate. |
|
2. Create a secret
|
|
3. Add a TLS configuration
|
|
4. Verify HTTPS access In your browser, access |
|
kubectl
Log on to the Certificate Management Service console. In the left navigation pane, choose .
On the Commercial Certificates tab, select the certificate that you want to download, and click Download in the lower-left corner of the certificate list.
In the dialog box that appears, select Nginx as the server type, then download and decompress the certificate package.
Run the following command to create a Secret using the downloaded certificate file (
.pem) and private key file (.key).kubectl create secret tls nginx-ingress-tls --cert test-nginx-ingress.com.pem --key test-nginx-ingress.com.key -n defaultRun the following command to add a TLS configuration to the
test-nginx-ingressIngress. Replacetest-nginx-ingress.comwith your actual registered domain name.kubectl patch ingress test-nginx-ingress -p '{"spec":{"tls":[{"hosts":["test-nginx-ingress.com"],"secretName":"nginx-ingress-tls"}]}}'Run the following command using your actual public IP address to verify that the domain name and service path are accessible over HTTPS.
curl -v -k https://8.xxx.xxx.117/coffee -H "Host: test-nginx-ingress.com"Parameter description:
-v: Displays detailed communication process, including TLS handshake information.-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>Server address:10.xxx.xxx.159:80Server name:coffee-96d4bc87-6cstvDate:14/Aug/2025:09:27:42 +0000URI:/coffee
Advanced configurations
Canary release
When upgrading services, you can use various deployment strategies such as rolling updates, phased releases (batch pause), blue-green deployments, and canary releases. For detailed instructions, see Implement phased releases and blue-green deployments using NGINX Ingress.
Backend service protocols
Specify the protocol used by your backend services by adding the nginx.ingress.kubernetes.io/backend-protocol annotation. Supported protocols include HTTP, HTTPS, gRPC, and gRPCS. For configuration examples, see Configure a gRPC service for NGINX Ingress.
URL path rewriting
By default, the NGINX Ingress Controller forwards the full request path to the backend. For example, a request to /service1/api is sent directly to the backend pod as /service1/api. If your backend service listens on a different path, such as /api, a path mismatch occurs, which results in a 404 error. In this case, use the nginx.ingress.kubernetes.io/rewrite-target annotation to rewrite the request path to the required directory.
For more information, see Configure a routing service for URL redirection.
Add annotations
NGINX Ingress supports an extensive range of features via Kubernetes annotations. To explore more capabilities, 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 dashboards. For setup details, see Analyze and monitor NGINX Ingress access logs.
High-load scenario optimization
To enhance the performance and stability of the NGINX Ingress Controller under heavy traffic, see Configure an NGINX Ingress Controller for high-payload scenarios and Suggestions for using an NGINX Ingress Controller.
FAQ
Why is the LoadBalancer IP unreachable from within the cluster?
How do I handle requests with large headers or cookies?
How do I configure CORS in NGINX Ingress?
How do I configure client IP address pass-through?
References
For information about the versions and release notes, see NGINX Ingress Controller.
For common issues and troubleshooting methods, see NGINX Ingress FAQ and Troubleshoot NGINX Ingress issues.













