All Products
Search

This Product

    Microservices Engine:Configure active health check for services

    Document Center

    Microservices Engine:Configure active health check for services

    Last Updated:Aug 10, 2026

    Active health checks automatically deactivate unhealthy service nodes and reactivate them when they recover. This improves the availability of routes to service interfaces in multi-replica deployments.

    Procedure

    Note

    If the gateway version is 1.2.1 or later, the TCP health check feature is automatically enabled when you create a service.

    1. Log on to the MSE console. In the top navigation bar, select a region.

    2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. On the Gateways page, click the ID of the gateway.

    3. In the left-side navigation pane, click Routes. Then, click the Services tab.

    4. On the Services tab, find the desired service and click Health Check Settings in the Actions column. In the Configure Health Check panel, turn on Enable Health Check, configure the parameters, and then click OK.

    Troubleshoot health check failures

    Troubleshoot a health check failure that occurs in common scenarios

    Determine whether a TCP health check or an HTTP health check fails:

    • If a TCP health check fails, the connection to the gateway node cannot be established. Check the following:

      • Check whether the node exists.

      • Check whether too many concurrent connections are established.

    • If an HTTP health check fails, first verify that the TCP health check passes. If it does, check whether the configured health check path is valid by using tools such as cURL or Postman.

    • If Docker is installed on the backend ECS instance, check whether the Docker bridge network conflicts with the VPC network. The default Docker bridge network (for example, 172.17.0.0/16) may overlap with the VPC network to which the ECS instance belongs (for example, 172.16.0.0/12). This overlap causes gateway health check requests to be routed incorrectly. Run the route -n command on the ECS instance to check the route table and confirm whether the Docker bridge network overlaps with the VPC network. To resolve the conflict, modify the bip parameter in the /etc/docker/daemon.json file to change the Docker bridge network (for example, to 192.168.0.1/24). Then, restart the Docker service and confirm that the conflict is resolved.

    Troubleshoot a health check failure that occurs when you add a service for the first time

    Perform the following operations in sequence:

    1. Check whether the service VPC is the same as the gateway VPC, or whether the service environment is connected to the gateway VPC through Cloud Enterprise Network (CEN) or physical connections. If the VPCs are different and not connected, the gateway IP address is inaccessible.

      Note

      The gateway does not support on-premises services that are registered with Nacos and ZooKeeper instances.

    2. Check whether the service VPC is the same as the gateway VPC. If the VPCs are different and not connected, the gateway IP address is inaccessible.

    3. Check whether security group authorization is configured. If the service source is a Container Service for Kubernetes (ACK) cluster, verify that the gateway is added to the security group of the ACK cluster. For more information, see Perform security group authorization.

    4. If the unhealthy gateway uses a public IP address, check whether an Internet NAT Gateway is enabled for the gateway VPC.

    Health check status displays Checking, or the initial probe fails but subsequent probes succeed

    For a service on the cloud-native gateway, this is usually a normal transitional state rather than a fault. Common causes include:

    • The response from the backend service is delayed, and the first probe takes close to the timeout threshold (for example, 2 seconds), so the status is not updated in time.

    • The Pod or the gateway is under high load, so the health check does not get the expected result in time.

    • The health check was just enabled, or the service was just registered, and the probe cycle has not completed. A service is marked healthy only after several consecutive successful probes.

    Observe the status for a while. If the health check remains abnormal, continue troubleshooting by using the other methods described in this topic.

    Troubleshoot a health check failure caused by an incorrect protocol configuration, where the health check passes but access fails

    If the upstream health check for an MSE Ingress on the cloud-native gateway passes but you still cannot access the service, check whether the protocol type of the corresponding application in Container Service for Kubernetes (ACK) is configured correctly. For example, an HTTP request must use the TCP protocol. If the protocol is mistakenly set to UDP, access fails even though the health check passes.

    Perform the following checks:

    • Re-save and republish the route configuration.

    • Check whether automatic listening is enabled for the service source.

    • Run the kubectl describe endpoints command to check the details of the service endpoint.

    FAQ about IPv6 addresses causing health check failures

    Q: Why does the MSE gateway health check still fail even though the Pod is already listening on an IPv6 port?

    A: The MSE gateway does not support proxying IPv6 resources. To resolve this issue, modify the backend Service configuration and set ipFamilies to IPv4 so that traffic is transmitted over IPv4.