Table of Contents

Status

Current state: Under Discussion Accepted

Discussion thread: None https://lists.apache.org/thread/6zsr70lpzqp96g4jf6kngyms4kkz1tp1

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

JIRA:

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

...

Having two configuration properties that must always hold the same value causes unnecessary confusion . The documentation and contradicts the documentation, which describes node.id as required in KRaft mode, yet the synonym mechanism allows users to omit node.id entirely if broker.id is set, contradicting the documented requirement.

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 4 and remove it in Apache Kafka 5.0.

...

Notes:

• The default value of -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.
• The documentation describes node.id as required in KRaft mode, but it can

...

• actually be omitted

...

• currently 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.

The behavior is the same for all process.roles (broker, controller, or combined). No changes to public APIs, network protocols, metrics, or command-line tools.

Proposed Changes

Phase 1: Deprecation (Apache Kafka 4.

...

4)

1. Log deprecation warning: When broker.id is explicitly set in the server configuration, log a WARN-level message at startup:

   Code Block
   The 'broker.id' configuration is deprecated and will be removed in Apache Kafka 5.0. Please use 'node.id' instead.

2. Preserve backward compatibility: The existing synonym mechanism will continue to function. Users who only set 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.

...

1. Remove broker.id configuration: The BROKER_ID_CONFIG will be removed from ServerConfigs. Setting it will result in an unknown configuration warningbe silently ignored.
2. Remove synonym logic: Remove the broker.id/node.id synonym handling from AbstractKafkaConfig.populateSynonyms().
3. Retain internal 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:

Note: In the 5.0 column, "ignored" means broker.id is treated as an unrecognized configuration and silently ignored. The Kafka server does not log warnings for unrecognized configurations.

Compatibility, Deprecation, and Migration Plan

...

Users should replace broker.id with node.id in their server configuration. If both are configured, simply remove broker.id.

Downgrade Considerations

Downgrading from 5.0 to 4.x is safe as long as the same configuration file is used — any config that was valid on 4.x before the upgrade remains valid after the rollback. The only edge case is if broker.id and node.id are set to different values on a 5.0 binary (where broker.id is ignored) and then downgraded to 4.x, which would result in a ConfigException. In practice, this cannot happen if the config was originally used on 4.x.

Test Plan

Phase 1: Deprecation (Apache Kafka 4.

...

4)

Unit tests to verify:

• A deprecation warning is logged when broker.id is explicitly set (with or without node.id).
• Backward compatibility: setting only broker.id still works (existing tests in KafkaConfigTest already create configs with only broker.id set).

...

• broker.id is no longer recognized and is silently ignored with an unknown config warning.
• Setting only broker.id without node.id results in a ConfigException.

Rejected Alternatives

Throw ConfigException when broker.id is set in 5.0

Instead of silently ignoring broker.id in 5.0, we could explicitly throw a ConfigException. However, this would force users to update their configuration files before upgrading, making the upgrade process more disruptive. Silently ignoring unrecognized configurations is consistent with how other removed configurations are handled in Kafka.

Log a customized warning when broker.id is set in 5.0

We could add special-case logic to detect and warn users that broker.id has been removed. However, the Kafka server does not log warnings for unrecognized configurations, and adding a one-off check just for broker.id would be inconsistent with how other removed configurations are handled. The deprecation warning in Phase 1 already provides sufficient notice for users to migrateNone.

References

• KIP-500: Replace ZooKeeper with a Self-Managed Metadata Quorum
• KIP-631: The Quorum-based Kafka Controller