Current state: Under Discussion
Discussion thread: None
JIRA:
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
Since Apache Kafka 4.0, ZooKeeper has been removed and KRaft is the only supported mode (KIP-500). In KRaft mode, a single process can serve as a broker, a controller, or both. KIP-631 therefore introduced node.id to replace broker.id as the canonical node identifier.
However, the legacy broker.id configuration still exists and is treated as a synonym of node.id. If only one is set, the other is automatically populated with the same value. If both are explicitly set, they must be equal; otherwise, a ConfigException is thrown.
Having two configuration properties that must always hold the same value causes unnecessary confusion and contradicts the documentation, which describes node.id as required in KRaft mode.
Related ZooKeeper-era configurations such as broker.id.generation.enable and reserved.broker.max.id were already removed in Kafka 4.0, making broker.id the only remaining legacy identifier config. We should deprecate it to simplify the configuration surface and guide all users toward the single, canonical configuration: node.id.
This KIP proposes to deprecate the broker.id server configuration property in Apache Kafka 4.3 and remove it in Apache Kafka 5.0.
Config | Default | 4.3 | 5.0 |
|---|---|---|---|
| -1 | Deprecated | Removed |
| (required) | No change | No change |
Notes:
-1 for broker.id is effectively unused in KRaft mode. If node.id is set, the synonym mechanism overwrites broker.id with the value of node.id. If neither is set, node.id validation fails with a ConfigException before the default is ever used.node.id as required in KRaft mode, but it can currently be omitted if broker.id is set, because the synonym mechanism automatically populates node.id from broker.id. After the removal in 5.0, node.id must be explicitly set.No changes to public APIs, network protocols, metrics, or command-line tools.
broker.id is explicitly set in the server configuration, log a WARN-level message at startup:The 'broker.id' configuration is deprecated and will be removed in Apache Kafka 5.0. Please use 'node.id' instead. |
broker.id will still have it automatically copied to node.id. The validation requiring both to be equal (if both are explicitly set) also remains unchanged.broker.id configuration: The BROKER_ID_CONFIG will be removed from ServerConfigs. Setting it will result in an unknown configuration warning.broker.id/node.id synonym handling from AbstractKafkaConfig.populateSynonyms().brokerId() accessor: The brokerId() method will continue to exist for internal use, delegating to nodeId().The following table summarizes the expected behavior for each configuration scenario across version ranges:
Configuration | 4.0 ~ 4.2 (Current) | 4.3 ~ 4.x (Deprecated) | 5.0 (Removed) |
|---|---|---|---|
Only | Valid | Valid | Valid |
Only | Valid; | Valid + |
|
Both set, same value | Valid | Valid + | Valid; |
Both set, different values |
|
| Valid; |
Neither set |
|
|
|
Note: In the 5.0 column, "ignored" means broker.id is treated as an unrecognized configuration, which logs a standard unknown config warning.
Users should replace broker.id with node.id in their server configuration. If both are configured, simply remove broker.id.
Unit tests to verify:
broker.id is explicitly set (with or without node.id).broker.id still works (existing tests in KafkaConfigTest already create configs with only broker.id set).Unit tests to verify:
broker.id is no longer recognized and is ignored with an unknown config warning.broker.id without node.id results in a ConfigException.None.