Status

Current state: "Under Discussion"

Discussion thread: here

JIRA: https://issues.apache.org/jira/browse/KAFKA-18775

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

Motivation

Currently, when using MetadataQuorumCommand to add a controller, users must provide a controller.properties configuration file. This file is required for the command to retrieve the metadata local path and endpoints needed to add voters. However, this approach has several limitations:

1. Limited Accessibility: The node executing the tool must have direct access to the metadata path of the node being added or removed. This restricts the ability to use node A to manage node B, as node A may not have access to the metadata folder on node B.

2. Dependency on Node Configuration: The tool requires access to the configuration of the node being managed.

However, the essential information for these operations – the "directory UUID" and the "endpoints" – can be obtained through the Admin API.

1. The Admin#describeMetadataQuorum method can provide the directory UUID.

2. The Admin#describeConfigs method, utilizing the bootstrap.controller address, can be used to retrieve the necessary endpoints.

By leveraging these APIs, we can simplify the process of adding/removing voters, allowing the command to be executed without direct access to the target node's metadata directory.

Public Interfaces

CLI

The kafka-metadata-quorum.sh tool introduces a new option —-controller-id for the add-controller subcommand.

Adding a controller

This can only be done with bootstrap controller option since we can‘t use bootstrap.server in Admin#describeConfigs to get controller configs.

bin/kafka-metadata-quorum.sh --bootstrap-controller localhost:9093 add-controller --controller-id <id>

Removing a controller

For removing a controller, the —-controller_directory_id option is no longer required.

bin/kafka-metadata-quorum.sh --bootstrap-server localhost:9092 remove-controller --controller-id <id>

bin/kafka-metadata-quorum.sh --bootstrap-controller localhost:9093 remove-controller --controller-id <id>

Proposed Changes

add-controller changes

Add a new option —-controller-id to add-controller subcommand.

        addControllerParser
            .addArgument("--controller-id", "-i")
            .help("The id of the controller to add. This option should be used with bootstrap controller.")
            .type(Integer.class)
            .action(Arguments.store());

• When using --controller-id with --bootstrap-controller, the MetadataQuorumCommand will:

  1. Retrieve the directory UUID via Admin#describeMetadataQuorum.

  2. Fetch the required endpoints via Admin#describeConfigs method (using bootstrap.controller)

• If —-command-config is provided, fallback to the existing behavior, and —-controller-id option will be ignored.

• If neither command-config nor controller-id with bootstrap-controller is provided, an exception will be thrown:

  • throw new TerseException("You must supply the configuration file of the controller you are adding when using add-controller, or either using controller id with bootstrap controller option to add a controller.");

remove-controller changes

diff --git a/tools/src/main/java/org/apache/kafka/tools/MetadataQuorumCommand.java b/tools/src/main/java/org/apache/kafka/tools/MetadataQuorumCommand.java
index dba7951aa4..f3bdbbeffa 100644
--- a/tools/src/main/java/org/apache/kafka/tools/MetadataQuorumCommand.java
+++ b/tools/src/main/java/org/apache/kafka/tools/MetadataQuorumCommand.java
@@ -471,7 +471,6 @@ public class MetadataQuorumCommand {
         removeControllerParser
             .addArgument("--controller-directory-id", "-d")
             .help("The directory ID of the controller to remove.")
-            .required(true)
             .action(Arguments.store());

• The —-controller_directory-id is no longer required. We can use Admin#describeMetadataQuorum method to get the controller directory UUID.

• If —-controller_directory-id is explicitly provided, it will be used directly, and Admin#describeMetadataQuorum will not be called.

Compatibility, Deprecation, and Migration Plan

This change should be backward compatible:

• The —-command-config option remains available in add-controller.

• The --controller-directory-id option in remove-controller is now optional but still supported.

Test Plan

New test cases will be added to MetadataQuorumCommandTest.java to validate:

• Adding a controller with --controller-id.

• Removing a controller without explicitly providing --controller-directory-id.

Rejected Alternatives

• Deprecate —-command-config option in add-controller and --controller-directory-id option in remove-controller.

  The main reason not to deprecate these two parameters is that they were only just introduced in 4.0, so deprecating them in a 4.x release feels a bit too soon.