This document defines Naming health state, health checking, enabled state, weight, and protection-threshold behavior.
healthy describes whether an instance is currently considered available by
Naming health logic. It can be updated by:
- heartbeat checks for instances of ephemeral services;
- active health checks for instances of persistent services;
- manual health update for instances of persistent services whose cluster
health checker is
NONE; - synchronization of health state across responsible servers.
enabled describes whether the instance is allowed to accept discovery traffic.
Disabled instances should not be returned to runtime Open API consumers and are
filtered by Java SDK selection.
Instances of ephemeral services are non-persistent runtime state. Their health is driven by the runtime publisher liveness, not by server-side active health checks.
HTTP clients, 1.x clients, and other clients that do not use gRPC keep ephemeral instances alive by reporting heartbeats. Beat check tasks inspect the last heartbeat time. If an instance is unhealthy for longer than its heartbeat timeout, it may be marked unhealthy. If it exceeds the delete timeout and expiration is enabled, it may be removed. Beat check task scheduling must follow the Task Execution Spec.
Heartbeat timing can be customized by reserved metadata keys:
| Key | Meaning |
|---|---|
preserved.heart.beat.interval |
Expected heartbeat interval. |
preserved.heart.beat.timeout |
Timeout before the instance is considered unhealthy. |
preserved.ip.delete.timeout |
Timeout before the instance may be deleted. |
gRPC clients keep ephemeral instances alive through the remote connection lifecycle. Naming observes connection close and release events to remove or redo runtime publisher/subscriber state. Local event delivery follows the Event Dispatch And NotifyCenter Spec.
The gRPC transport has its own heartbeat and liveness detection to avoid half-open connections. That heartbeat is hidden behind the gRPC connection layer from the Naming module perspective. Naming should depend on connection lifecycle events defined by the Remote Connection Lifecycle Spec, not duplicate transport-level heartbeat logic.
Instances of persistent services are checked by server-side health check processors. Cluster metadata selects the checker type and port behavior.
Built-in checker types include TCP, HTTP, MySQL, and NONE, and additional checker types may be registered through the health checker registry.
Active health checks should only change health state when the responsible server performs the check and the service health check switch allows it.
Persistent instance recovery may schedule health-check tasks before local persistent-client and service-metadata CP snapshots have both completed successfully. Those tasks must be deferred until both snapshots are loaded. If no local snapshot exists, application startup completion may release the gate as a fail-open fallback. Once released, the gate must remain open for the process lifetime. Temporarily unavailable cluster metadata must not be interpreted as the default TCP checker or change instance health state.
The instance address used by an active health check must be a plain host. The instance IP field must not carry user information, a port, a path, query parameters, or a fragment. A processor must validate the address at runtime before making a network request. If address parsing fails or extra URL components are present, the current check must be skipped without making a network request, changing instance health state, or blocking checks for other services. IPv6 syntax separators are not extra URL components.
The built-in HTTP checker's path is a relative URI reference resolved against
the instance host and effective check port. It may contain a path and query, but
must not define a scheme, authority, user information, host, port, or fragment.
Custom header names must use valid HTTP token characters, and emitted values
must not contain control characters other than horizontal tab. Request-framing
headers Content-Length and Transfer-Encoding are not valid health-check
custom headers. Other valid headers, including Host and Authorization,
remain supported and do not change the connection target.
Cluster metadata update APIs must reject an invalid built-in HTTP checker before
persisting it. The HTTP processor must apply the same validation at runtime so
historical invalid metadata is skipped without starting a check or changing
instance health state. Validation of fields owned by extension checkers remains
the responsibility of the extension provider.
Manual instance health update is allowed for instances of persistent services
only when the cluster health checker is NONE. If active health check is
configured, manual health update must be rejected because health is owned by the
checker.
weight is an instance-level value used by client-side weighted selection.
Runtime selection should ignore instances whose weight is less than or equal to
zero. Server-side query stores and returns the weight; it does not guarantee
that every consumer uses weighted balancing.
Service protectThreshold prevents discovery results from collapsing to too
few healthy instances. After cluster, enabled, internal server-side filtering,
and health filtering, if the healthy ratio is lower than or equal to the
threshold, the server marks the result as reaching protection threshold and
returns the broader filtered instance set with unhealthy instances presented as
healthy in that protected view.
Protection threshold is a discovery availability protection mechanism. It is not an assertion that the underlying instances are actually healthy.
gRPC connection heartbeat, half-open detection, and client-side connection liveness behavior are defined by the Client Connection And Failover Spec. The foundation-level server connection lifecycle boundary is defined by the Remote Connection Lifecycle Spec.