Status

Current state: Under Discussion", Accepted

Discussion thread: https://lists.apache.org/thread/mbjlgbv2q4x5ml7mx93ls77bg93wtrfy

Vote thread: https://lists.apache.org/thread/czmbljctdkrl6s834gmrv4kwn8d6oq44Discussion thread: 

JIRA:

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

In KIP-584, it introduced describeFutures Admin API to return supported and finalized features. Finalized features are consistent across the entire cluster, allowing users to receive the same response from any node. In contrast, supported features depend on unstable.api.versions.enable configuration, which can lead to different results from different nodes. This inconsistency can confuse users about the correct supported minimum and maximum versions within the cluster. Even if users are aware of this issue and want to check the supported version on a specific node, they currently cannot specify the node ID in the Admin API or CLI tool. This KIP proposes adding a new optional argument to the describeFeatures Admin API and FeatureCommand CLI tool, enabling users to retrieve supported features from a specified node.

Public Interfaces

DescribeFeaturesOptions

Add nodeId to DescribeFeaturesOptions. Default value is

...

empty.

public class DescribeFeaturesOptions extends AbstractOptions<DescribeFeaturesOptions> {
      private intOptionalInt nodeId = -1OptionalInt.empty();

    /**
     * Set the node id to which the request should be sent. If using bootstrap controller and node id is less than 0,
     * the request will be sent to the controller node. If using bootstrap broker and node id is less than 0, the
     * request will be sent to the first available node.
     */
    public DescribeFeaturesOptions nodeId(int nodeId) {
        this.nodeId = OptionalInt.of(nodeId);
        return this;
    }

    /**
     * The node id to which the request should be sent. If using bootstrap controller and the node id is less than 0,
     * empty, the request will be sent to the controller node. If using bootstrap broker and node id is less than 0, the
     * request will be sent to the first available nodearbitrary controller/broker.
     */
    public intOptionalInt nodeId() {
        return nodeId;
    }
}

Proposed Changes

kafka-features.sh

describe —node-id <node-id>

Add —-node-id to kafka-features.sh describe command. The argument is optional. If the value is negative, throws IllegalArgumentException.

> ./bin/kafka-features.sh --bootstrap-server localhost:9092 describe --node-id 2
Feature: eligible.leader.replicas.version	SupportedMinVersion: 0	SupportedMaxVersion: 1	FinalizedVersionLevel: 0	Epoch: 153
Feature: group.version	SupportedMinVersion: 0	SupportedMaxVersion: 1	FinalizedVersionLevel: 1	Epoch: 153
Feature: kraft.version	SupportedMinVersion: 0	SupportedMaxVersion: 1	FinalizedVersionLevel: 1	Epoch: 153
Feature: metadata.version	SupportedMinVersion: 3.3-IV3	SupportedMaxVersion: 4.0-IV3	FinalizedVersionLevel: 4.0-IV3	Epoch: 153
Feature: transaction.version	SupportedMinVersion: 0	SupportedMaxVersion: 2	FinalizedVersionLevel: 2	Epoch: 153
  
> ./bin/kafka-features.sh --bootstrap-controller localhost:9093 describe --node-id 1
Feature: eligible.leader.replicas.version	SupportedMinVersion: 0	SupportedMaxVersion: 1	FinalizedVersionLevel: 0	Epoch: 7
Feature: group.version	SupportedMinVersion: 0	SupportedMaxVersion: 1	FinalizedVersionLevel: 1	Epoch: 7
Feature: kraft.version	SupportedMinVersion: 0	SupportedMaxVersion: 1	FinalizedVersionLevel: 1	Epoch: 7
Feature: metadata.version	SupportedMinVersion: 3.3-IV3	SupportedMaxVersion: 4.1-IV0	FinalizedVersionLevel: 4.0-IV3	Epoch: 7
Feature: transaction.version	SupportedMinVersion: 0	SupportedMaxVersion: 2	FinalizedVersionLevel: 2	Epoch: 7

Compatibility, Deprecation, and Migration Plan

No breaking change is introduced. The new argument —-node-id is optional.

Test Plan

Admin API

• Default DescribeFeaturesOptions can work as usual.

• If nodeId is

negative

• empty, the Admin client ignores it and falls back to use LeastLoadedBrokerOrActiveKController.

• If nodeId is valid, the Admin client sends ApiVersionRequest to a node with nodeId.

• If nodeId is not registered, the Admin client throws TimeoutException.

kafka-features.sh

• The empty —-node-id can work as usual.

• If nodeId is negative, the FeatureCommand throws IllegalArgumentException.

• If nodeId is valid, the FeatureCommand

get

• gets ApiVersionResponse from a node with nodeId.

Rejected Alternatives

• If nodeId is not registered, the FeatureCommand throws AdminCommandFailedException.

Alternatives

Use metrics to track finalized level and minimum / maximum supported level. The approach has been accepted in KIP-1180: Add generic feature level metrics.N/A