Container Intelligent Service (CIS) provides Ingress diagnostics to help you identify and fix common Ingress issues. The feature runs checks across three categories: Ingress resources, the Addon (controller startup parameters, associated Services, and pods), and the Server Load Balancer (SLB) instance.
Important
When you run Ingress diagnostics, CIS executes a data collection program on each cluster node. The program collects system-level information: system version, load status, Docker status, kubelet status, and key error entries from system logs. No business data or sensitive information is collected.
Note
The diagnostic items available depend on your cluster configuration. The items shown on the diagnostic page are authoritative.
Diagnostic categories
| Category | What it checks |
|---|---|
| Ingress | Availability of Ingress resources |
| Addon | Startup parameters of the Ingress controller, the Service associated with the Ingress, and Ingress pods |
| SLB | Status of the SLB instance used by the Ingress controller, including maximum connections, QPS, and health status |
Ingress
| Diagnostic item | Description | Resolution |
|---|---|---|
| Ingress check | Checks whether the specified Ingress exists. | Verify that an Ingress rule exists for the URL. If the URL is correct, inspect the Ingress rules — for example, check whether a regular expression is specified as the path or whether the use-regex annotation is set. |
| base-url-scheme check | Detects use of the nginx.ingress.kubernetes.io/base-url-scheme annotation, which was deprecated in Ingress controller 0.22.0. | Check the Ingress controller version, then remove this annotation or replace it with a supported one. |
| grpc-backend check | Detects use of the nginx.ingress.kubernetes.io/grpc-backend annotation, which was deprecated in Ingress controller 0.21.0. | Check the Ingress controller version, then remove this annotation or replace it with a supported one. |
| mirror-uri check | Detects use of the nginx.ingress.kubernetes.io/mirror-uri annotation, which was deprecated in Ingress controller 0.24.0. | Check the Ingress controller version, then remove this annotation or replace it with a supported one. |
| secure-backends check | Detects use of the nginx.ingress.kubernetes.io/secure-backends annotation, which was deprecated in Ingress controller 0.21.0. | Check the Ingress controller version, then remove this annotation or replace it with a supported one. |
| session-cookie-hash check | Detects use of the nginx.ingress.kubernetes.io/session-cookie-hash annotation, which was deprecated in Ingress controller 0.24.0. | Check the Ingress controller version, then remove this annotation or replace it with a supported one. |
| nginx.com/nginx.org check | Detects annotations prefixed with nginx.com/nginx.org. These annotations are specific to the commercial NGINX Ingress controller and are not recognized by the open-source version. | Replace these with annotations supported by the open-source NGINX Ingress controller. For details, see NGINX Ingress management or the official documentation. |
| Status of Canary | Checks whether nginx.ingress.kubernetes.io/canary: "true" is set. Without this annotation, the Canary feature does not take effect. | Add the nginx.ingress.kubernetes.io/canary: "true" annotation to the Ingress rules to enable canary routing. |
Addon
| Diagnostic item | Description | Resolution |
|---|---|---|
| Percentage of Ingress pods in the Ready state | Checks what percentage of Ingress pods are in the Ready state. A value below 100% may indicate an issue. | Check the error logs to identify and fix the faulty pods. See NGINX Ingress controller troubleshooting. |
| Ingress IP address check | Checks whether the Ingress controller has assigned an IP address to the Ingress. | If no IP address is assigned, verify that the Ingress controller is referenced in the IngressClass of the Ingress and that the controller is running correctly. Fix any issues based on the diagnostic result. |
| Leader pod check | Checks whether a leader pod has been elected. No leader pod may indicate that the pod startup time is too short or that the Ingress controller permissions are misconfigured. | Check the Ingress pod error logs and fix any errors reported. See NGINX Ingress controller troubleshooting. |
| Incorrect NGINX Ingress annotations | Checks for annotations prefixed with nginx.com/nginx.org. The open-source NGINX Ingress controller only recognizes annotations prefixed with nginx.ingress.kubernetes.io. If you use annotations that start with nginx.com/nginx.org, your configurations may become invalid or do not meet your requirements. | Replace these with the annotations supported by the open-source controller. See Annotations. |
| Use of capture groups together with rewrite-target in NGINX Ingresses | Checks whether the rewrite-target annotation is used with capture groups. In Ingress controller 0.22.0 and later, capture groups must be explicitly specified when using rewrite-target. Without them, traffic forwarding errors occur. | Configure the Ingress correctly. See Advanced NGINX Ingress configurations. |
| NGINX Ingress canary rules | Checks whether more than two Services are specified in service-match or service-weight. Each field supports traffic distribution between exactly two Services. Any Services beyond the second are ignored, which can cause traffic routing to behave unexpectedly. | Adjust the configuration so that service-match or service-weight references no more than two Services. |
| Ingress name | Displays the names of matching Ingress rules. | None. |
| Pod error logs | Checks whether the Ingress controller pods are generating error logs. Error logs indicate the controller may not be running as expected. | Review the error logs to identify the cause and fix the issue. See NGINX Ingress controller troubleshooting. |
| Use of capture groups in the paths of rewrite-target | Checks whether capture groups are specified in the nginx.ingress.kubernetes.io/rewrite-target annotation. In Ingress controller 0.22.0 and later, capture groups are required. Without them, path errors may occur. | Configure the Ingress correctly. See Configure routing rules to redirect traffic from specific URLs. |
| Multiple targets in service-* | Checks whether more than two Services are specified in service-match or service-weight. Traffic can only be distributed between two Services at a time. | Configure service-weight or service-match to reference no more than two Services. See Use the NGINX Ingress controller to implement canary releases and blue-green deployments. |
| Ingress Service check | Checks whether the Service referenced in the Ingress controller startup parameters exists. A deleted Service causes the Ingress controller to fail to start. | Locate the deleted Service name in the Deployment startup parameters and restore it. See High-risk operations related to networks and SLB instances. |
| Ingress Service endpoint check | Checks whether the Service associated with the Ingress has endpoints. Without endpoints, the SLB instance cannot route traffic to the Ingress controller. | Verify that the label selector on the Service matches the correct pods. |
| Ingress Service events | Checks whether the Service associated with the Ingress has generated Warning or Error events. These events often indicate SLB configuration errors. | Review the Service events to identify and fix the cause. See Service errors and solutions. |
| Ingress Service external traffic policy | Checks the external traffic policy of the Service. The default policy is Local; it can also be set to Cluster. In Cluster mode, client IP addresses may not be preserved, which can cause health checks to report incorrect results. | Use Local mode unless your workload requires Cluster mode or you need to access the Ingress controller via the SLB IP address from within the cluster. |
| Ingress Service external IP address | Checks whether the cloud controller manager has assigned an external IP address to the Service. Without one, the Ingress cannot receive traffic from the Internet. | Verify the Service status, the cloud controller manager status, and your SLB quota. Most issues surface as Service events. |
| Ingress Service type (LoadBalancer) | Checks whether the Service referenced in the Ingress controller startup parameters is of type LoadBalancer. A non-LoadBalancer Service type makes the Ingress controller inaccessible over the Internet. | Change the Service type to LoadBalancer unless your workload does not require Internet access. |
| --force-namespace-isolation check | Detects use of the --force-namespace-isolation startup parameter, which was deprecated in Ingress controller 0.24.0. | Check the Ingress controller version, then remove this startup parameter. |
| --sort-backends check | Detects use of the --sort-backends startup parameter, which was deprecated in Ingress controller 0.22.0. | Check the Ingress controller version, then remove this startup parameter. |
SLB
| Diagnostic item | Description | Resolution |
|---|---|---|
| SLB instance | Checks whether the SLB instance used by the Ingress controller exists. | If the SLB instance is missing, verify the associated Service and its events, then check the SLB console. If the instance was accidentally deleted, recreate the Service to provision a new one. See What do I do if I accidentally delete an SLB instance? |
| Ingress controller SLB instance backend server health | Checks the health status of the SLB backend servers. | If backend servers are unhealthy, review the events of the Service referenced by the Ingress controller and check whether the controller pods are overloaded. See NGINX Ingress controller troubleshooting. |
| SLB ID | Displays the ID of the SLB instance. | None. |
| Ingress controller SLB instance connections | Checks whether the number of connections on the SLB instance over the previous three days exceeded 80% of the upper limit. Reaching the limit prevents clients from establishing new connections. | If connections have reached the upper limit, upgrade the SLB instance to avoid service interruptions. See Use an existing SLB instance. |
| Ingress controller SLB instance new connection rate | Checks whether the new connection rate on the SLB instance over the previous three days exceeded 80% of the upper limit. Reaching the limit temporarily prevents new client connections. | If the new connection rate has reached the upper limit, upgrade the SLB instance to avoid service interruptions. See Use an existing SLB instance. |
| Ingress controller SLB instance QPS | Checks whether the QPS of the SLB instance over the previous three days exceeded 80% of the upper limit. Reaching the limit prevents clients from connecting. | If QPS has reached the upper limit, upgrade the SLB instance to avoid service interruptions. See Use an existing SLB instance. |
| Host and SecretName for TLS | Checks whether both the Host and SecretName parameters are specified in the Ingress TLS configuration. Both are required. | Specify both Host and SecretName, and make sure the host value matches the hostname in the certificate. |
| Ingress controller SLB health check | Checks whether the SLB instance failed health checks during the previous three days. Failures indicate the controller pods may be overloaded or the SLB configuration contains errors. | If health check failures occurred, review the events of the Service referenced by the Ingress controller and verify that the controller is not overloaded. See NGINX Ingress controller troubleshooting. |