# Service Discovery

Service discovery in API7 Gateway replaces static node lists with dynamic endpoint resolution. Instead of manually updating IP addresses for your upstream services, you can configure the data plane to query a service registry and automatically discover backend nodes.

<!-- -->

## How Service Discovery Works[​](#how-service-discovery-works "Direct link to How Service Discovery Works")

When you use service discovery, you specify a **Service Name** and a **Discovery Type** in the upstream configuration instead of a static `nodes` array.

1. **Query Registry**: The data plane (DP) periodically queries the configured service registry (e.g., Kubernetes API, Nacos server, Consul agent).
2. **Retrieve Endpoints**: The registry returns a list of healthy IP addresses and ports for the requested service.
3. **Local Cache**: The DP caches these endpoints in memory for high-performance routing.
4. **Update Nodes**: The DP updates the upstream node list based on the retrieved endpoints.
5. **Load Balance**: The gateway's load balancer distributes incoming requests across the discovered nodes.

## Supported Discovery Types[​](#supported-discovery-types "Direct link to Supported Discovery Types")

API7 Gateway's Control Plane lets you connect services to the following service registries:

* **Kubernetes**: Resolves endpoints for Kubernetes Services by querying the API server directly.
* **Nacos**: Integrates with the Alibaba Nacos registry for dynamic service discovery.
* **Consul**: Integrates with the HashiCorp Consul catalog for dynamic service discovery.

## Comparison: Static Nodes vs. Service Discovery[​](#comparison-static-nodes-vs-service-discovery "Direct link to Comparison: Static Nodes vs. Service Discovery")

| Feature           | Static Nodes                       | Service Discovery         |
| ----------------- | ---------------------------------- | ------------------------- |
| **Configuration** | Manual (IP/Port)                   | Automated (Service Name)  |
| **Maintenance**   | High (must update on node change)  | Low (automatic)           |
| **Scalability**   | Manual updates required on scaling | Instant scaling support   |
| **Environment**   | Bare metal, legacy apps            | Kubernetes, microservices |

## Configuration Fields[​](#configuration-fields "Direct link to Configuration Fields")

When configuring an upstream with service discovery, you will typically provide:

* **Service Name**: The registry-specific service identifier. For Nacos, use `<registry_id>/<namespace>/<group>/<service_name>`, such as `<registry_id>/public/DEFAULT_GROUP/httpbin`. A Kubernetes DNS name is not a universal service-discovery identifier.
* **Discovery Type**: The registry type (`kubernetes`, `nacos`, or `consul`).
* **Namespace Selector**: For Kubernetes, filters which namespaces the gateway should monitor.
* **Default Weight**: The weight assigned to discovered nodes if not provided by the registry.

## Service Registry Status[​](#service-registry-status "Direct link to Service Registry Status")

This service-registry status detail was introduced in API7 Enterprise 3.10.9. Earlier 3.10.x releases report only `healthy`, `lost_connection`, and `connecting` states and omit `lost_connection_instances`.

The **Service Registries** page of a gateway group shows the connection status of each service registry. Gateway instances report whether they can reach each registry. The control plane aggregates these reports over the online gateway instances of the group, which are the instances that sent a heartbeat within the last 60 seconds.

| Status                        | Meaning                                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Healthy**                   | All online gateway instances that reported on the registry are connected to it.                               |
| **Partially Lost Connection** | Some of these gateway instances have lost the connection to the registry.                                     |
| **Lost Connection**           | Every one of these gateway instances has lost the connection to the registry.                                 |
| **Connecting**                | No online gateway instance has reported on the registry yet, or the health check of the registry is disabled. |

Hover over **Partially Lost Connection** or **Lost Connection** to see the **Gateway instances that lost connection to this registry**. The list shows the **Hostname**, **Instance ID**, and **Lost Since** time of each gateway instance.

The `/api/gateway_groups/{gateway_group_id}/service_registries` endpoints return the same information. The `status` field is one of `healthy`, `partially_lost_connection`, `lost_connection`, or `connecting`. The `lost_connection_instances` field lists the `instance_id`, `hostname`, and `lost_since` of each gateway instance that has lost the connection.

To get notified when gateway instances stay disconnected from a registry, create an alert policy with the **Service Registry Lost Connection** event. See [Alert on Service Registry Connection Loss](https://docs.api7.ai/api7-gateway/observability/alerts.md#alert-on-service-registry-connection-loss).

## Next Steps[​](#next-steps "Direct link to Next Steps")

* [Upstreams and Load Balancing](https://docs.api7.ai/api7-gateway/key-concepts/upstreams-and-load-balancing.md) — configure backend targets and load balancing algorithms.
* [Deploy on Kubernetes](https://docs.api7.ai/api7-gateway/install/deploy-on-kubernetes.md) — deploy the gateway with Kubernetes service discovery.