...

A new --bootstrap-server option will be added and will:

1. Perform the election by calling AdminClient.electPreferredReplicaLeader() on an AdminClient instance bootstrapped from the via the given broker --bootstrap-server.

Using both options in the same command line will produce an error message and the tool will exit without doing the intended operation.

...

The following methods will be added to AdminClient:

/**
 * Elect the preferred replica of the given {@code partitions} as leader, or
 * elect the preferred replica for all partitions as leader if the argument to {@code partitions} is null.
 *
 * This operation is supported by brokers with version 1.0 or higher.
 */
ElectPreferredReplicaLeaderResult electPreferredReplicaLeader(Collection<TopicPartition> partitions, ElectPreferredReplicaLeaderOptions options)
ElectPreferredReplicaLeaderResult electPreferredReplicaLeader(Collection<TopicPartition> partitions)

Where

class ElectPreferredReplicaLeaderOptions {
    public ElectPreferredReplicaLeaderOptions() { ... }
    /**
     * The request timeout in milliseconds for this operation or {@code null} if the default request timeout for the
     * AdminClient should be used.
     */
    public Integer timeoutMs() { ... }
    /**
     * Set the request timeout in milliseconds for this operation or {@code null} if the default request timeout for the
     * AdminClient should be used.
     */
    public ElectPreferredReplicaLeaderOptions timeoutMs(Integer timeoutMs) { ... }
}
class ElectPreferredReplicaLeaderResult {
    // package access constructor
 Map<TopicPartition   Map<TopicPartition, KafkaFuture<Void>> values();
}() { ... }
    KafkaFuture<Void> all() { ... }
 }

A call to electPreferredReplicaLeader() will send a ElectPreferredReplicaLeaderRequest to the controller broker.

NetworkProtocol: ElectPreferredReplicaLeaderRequest and ElectPreferredReplicaLeaderResponse

...

The request will require ClusterAction operation on the Cluster resource. TODO Or should this be ALTER on the Topic?require Alter on each topic in the request.

Note: It is not an error if there is a duplicate (topic, partition)-pair in the request.

Note that a ElectPreferredReplicaLeaderRequest can must be sent to any node in the cluster; it's not necessary to target a request to a leader ir follower broker for a partitionthe controller of the cluster.

ElectPreferredReplicaLeaderResponse => throttle_time_ms [replica_election_result]
  throttle_time_ms => INT32
  replica_election_result => topic partition_id error_code error_message
    topic => STRING
    partition_id => INT32
    error_code => INT16
    error_message => NULLABLE_STRING

Where

Anticipated errors:

• UNKNOWN_TOPIC_OR_PARTITION (3) If the topic or partition doesn't exist on any broker in the cluster. Note that the use of this code is not precisely the same as it's usual meaning of "This server does not host this topic-partition".

•  NOT_CONTROLLER (41) If the request is sent to a broker that is not the controller for the cluster.

• REPLICA_LEADER_ELECTION_IN_PROGRESS (new) If there is an election if elections are already in progress. The request can be attempted again retried at a later time.
• TOPIC_AUTHORIZATION_FAILED (29) If the user didn't have Alter access to the topic.
• NONE (0) The topic partition count was changed successfullyelection has successfully been started.

Compatibility, Deprecation, and Migration Plan

...