apache / apache/fluss

[client] Expose all coordinator servers (leader and standbys) via the client API

Open
#4,117 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
2.1k
Forks
625
Avg merge
3d 14h
Merged PRs (30d)
97

Description

### Search before asking

- [x] I searched in the [issues](https://github.com/apache/fluss/issues) and found nothing similar.

### Motivation

Since coordinator HA (1.0), a cluster may run several coordinator servers, but the client API still surfaces exactly one: `MetadataResponse` carries a single `coordinator_server` (the current leader), and `Admin#getServerNodes()` returns that node plus the alive tablet servers. Standby coordinators are invisible to clients — they reject every request except `apiVersions` with `NotCoordinatorLeaderException`.

Operational tooling (consoles, operators, CLIs) needs to display and verify the HA topology: how many coordinators exist, which one is the leader, and whether the standbys are alive. Today the only sources are out-of-band — ZooKeeper or the deployment platform (for example, Kubernetes pods) — which not every client can or should reach.

### Solution

1. Expose all registered coordinator servers with a role marker (leader/standby) through the client API — either by extending `getServerNodes`/`MetadataResponse`, or as part of the cluster-info API proposed in #1389, or as a dedicated `Admin#describeCoordinators()`.
2. Include a liveness signal per coordinator (for example, presence in the election group), so a dead standby is distinguishable from a live one.

Related: #4105 needs a readiness signal that is valid for standby coordinators; a client-visible role/liveness API could serve that consumer too. The request handler's blanket rejection of all non-leader requests is already marked as provisional in a code comment (`FlussRequestHandler`) — serving this (read-only) call from a standby would be consistent with narrowing that check.

### Anything else?

Affected areas: `fluss-rpc` (`FlussApi.proto`: metadata or a new describe message), `fluss-server` (`CoordinatorService`, election-group state), `fluss-client` (`Admin`).

### Willingness to contribute

- [ ] I'm willing to submit a PR!

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the coordinator metadata and request handling paths in fluss-rpc/FlussApi.proto, fluss-server/CoordinatorService and FlussRequestHandler, and fluss-client/Admin. Compare the existing leader-only MetadataResponse and getServerNodes APIs with the election-group state. Done means clients can discover every coordinator, its leader or standby role, and a liveness signal, including for standby coordinators.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend-api-design, distributed-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.