LeaderElectionCommand Standalone Application

kafka.admin.LeaderElectionCommand is a standalone application for preferred or unclean leader election for all or some partitions.

LeaderElectionCommand uses AdminClient internally and is simply a command-line front-end to Admin.electLeaders.

LeaderElectionCommand can be executed on command line using kafka-leader-election.sh shell script (that simply uses kafka-run-class shell script to launch the command).

Note	`PreferredReplicaLeaderElectionCommand` and the corresponding `kafka-preferred-replica-election.sh` utility have been deprecated and replaced by the more generic `LeaderElectionCommand` and `kafka-leader-election.sh` utility.

LeaderElectionCommand supports options:

--bootstrap-server and --election-type are required
--topic, --all-topic-partitions and --path-to-json-file are mutually exclusive (only one is required)

Table 1. Options
Option	Description
`admin.config`	File with configuration properties of an admin client `bootstrap.servers` is --bootstrap-server `request.timeout.ms` is the timeout argument (default: `30 seconds`)
`all-topic-partitions`	Perform election on all of the eligible topic partitions based on the type of election Not allowed with --topic or --path-to-json-file
`bootstrap-server`	(required) Brokers to connect to as a comma-separated list of `host:port` URLs
`election-type`	(required) Type of election to attempt: `preferred` for preferred leader election (only performed if the current leader is not the preferred leader for the topic partition) `unclean` for unclean leader election (only performed if there are no leader for the topic partition)
`help`	Prints usage information
`partition`	Partition id to perform an election for Required and only acceptable with --topic
`path-to-json-file`	JSON file with partitions for leader elections Default: `(empty)` (all partitions) The format of the JSON file should be as follows: `{ "partitions": [ { "topic": "foo", "partition": 1 }, { "topic": "foobar", "partition": 2 } ] }` The JSON file should not be empty and has no duplicate partitions (or `AdminOperationException` is thrown)
`topic`	Name of topic for which to perform an election. Not allowed with --path-to-json-file or --all-topic-partitions
`version`	Displays Kafka version

Tip	Read KIP-183 - Change PreferredReplicaLeaderElectionCommand to use AdminClient.

Executing Standalone Application — `main` Utility

main(
  args: Array[String]): Unit

main is the entry point of the LeaderElectionCommand when launched on command line (e.g. using kafka-leader-election.sh shell script).

Internally, main simply run with the timeout of 30 seconds.

`run` Utility

run(
  args: Array[String],
  timeout: Duration): Unit

run reads the options from the command line.

run prints out the following for no command-line options, --help or --version:

This tool helps to causes leadership for each partition to be transferred back to the 'preferred replica', it can be used to balance leadership among the servers.

run creates a AdminClient (with the configuration properties from the admin.config properties file if specified).

In the end, run electLeaders followed by requesting the AdminClient to close.

Note	`run` is used exclusively when `PreferredReplicaLeaderElectionCommand` command-line application is executed.

`electPreferredLeaders` Method

electPreferredLeaders(
  partitionsFromUser: Option[Set[TopicPartition]]): Unit

electPreferredLeaders prints out the following DEBUG message to the logs:

Calling AdminClient.electPreferredLeaders([partitions])

electPreferredLeaders creates a new AdminClient and requests to electPreferredLeaders.

Note	`electPreferredLeaders` is used exclusively when `PreferredReplicaLeaderElectionCommand` is requested to run.

Closing AdminClient — `close` Method

close(): Unit

close prints out the following DEBUG message to the logs and requests the AdminClient to close.

Closing AdminClient

Note	`close` is used exclusively when `PreferredReplicaLeaderElectionCommand` is requested to run.

Validating Options — `validate` Internal Utility

validate(
  commandOptions: LeaderElectionCommandOptions): Unit

validate…FIXME

Note	`validate` is used when `LeaderElectionCommand` is requested to run.

Validating Options — `parseReplicaElectionData` Internal Utility

parseReplicaElectionData(
  jsonString: String): Set[TopicPartition]

parseReplicaElectionData parses the given JSON string that is assumed to have one of more partitions top-level field with topic and partition fields.

{ "partitions":
  [
    { "topic": "foo", "partition": 1 },
    { "topic": "foobar", "partition": 2 }
  ]
}

parseReplicaElectionData throws an AdminOperationException for duplicate partitions:

Replica election data contains duplicate partitions: [duplicatePartitions]

parseReplicaElectionData throws an AdminOperationException when the JSON string has no partitions fields:

Replica election data is missing "partitions" field

parseReplicaElectionData throws an AdminOperationException when the JSON string is invalid:

Replica election data is empty

Note	`parseReplicaElectionData` is used when `LeaderElectionCommand` is requested to run (and handle --path-to-json-file option).

Leader Election — `electLeaders` Internal Utility

electLeaders(
  client: Admin,
  electionType: ElectionType,
  topicPartitions: Option[Set[TopicPartition]]): Unit

electLeaders prints out the following DEBUG message to the logs:

Calling AdminClient.electLeaders([electionType], [partitions])

electLeaders requests the Admin client to electLeaders.

electLeaders splits the election results into three categories: partitions that succeeded, didn’t changed (noops), and failed.

electLeaders prints out the following message to standard output for successful partitions:

Successfully completed leader election ([electionType]) for partitions [partitions]

electLeaders prints out the following message to standard output for partitions that didn’t change the leaders (noops):

Valid replica already elected for partitions [partitions]

electLeaders prints out the following message to standard output for every failed partition and throws an AdminCommandFailedException.

Error completing leader election ([electionType]) for partition: [topicPartition]: [exception]

Note	`electLeaders` is used when `LeaderElectionCommand` is requested to run.

LeaderElectionCommand