confluentinc / confluentinc/confluent-kafka-javascript
Admin API: support describeCluster()
- Dominant language
- TypeScript
- Stars
- 304
- Forks
- 45
- Avg merge
- 11h 47m
- Merged PRs (30d)
- 5
Description
**Describe the enhancement**
The Admin API currently has no way to describe the cluster (cluster id, controller, broker list). KafkaJS exposes this as `admin.describeCluster()`, and librdkafka has had the `rd_kafka_DescribeCluster()` admin operation since v2.3.0 (the bundled submodule is v2.15.0), but there is no JS binding for it.
**Use case**
We run connectivity/health probes from Node.js services against a large MSK cluster (~355 topics, IAM auth). The cheapest correct probe is DescribeCluster: it sends the admin MetadataRequest with an empty topic list, so a single call verifies broker reachability and authentication without fetching per-topic metadata or triggering per-topic authorization checks. Today the JS surface offers no equivalent:
- `listTopics()` / `fetchTopicMetadata()` fetch full (or per-topic) metadata — on large clusters each health tick costs hundreds of per-topic IAM authorization evaluations on the broker side.
- `rd_kafka_clusterid()` (the approach in #451) is served from the client's local metadata cache after the first fetch, so it cannot prove current broker reachability — with all brokers down it can still return a cached value.
For applications migrating from KafkaJS, `admin.describeCluster()` returning `{ clusterId, controller, brokers }` would also close a gap with the KafkaJS admin API.
**Additional context**
I have a working implementation that wires `rd_kafka_DescribeCluster()` through the AdminClient (callback + promisified APIs, TypeScript types, jest integration tests), following the existing `describeTopics`/`describeGroups` patterns. I'll open a PR referencing this issue.
Contributor guide
Assessment
This issue has not been assessed yet.