...

This page is meant as a template for writing a KIP. To create a KIP choose Tools->Copy on this page and modify with your content and replace the heading with the next KIP number and a description of your issue. Replace anything in italics with your own description.

Status

Current state: [One of "Under Discussion", "Accepted", "Rejected"]Draft

Discussion thread: here [Change the link from the KIP proposal email archive to your own email thread]

...

This makes it difficult to strengthen configuration constraints over time. For example, if the minimum allowed value for log.segment.bytes is increased (e.g., from 1 byte to 3 MB), brokers with legacy values in server.properties will fail to start after a binary upgrade due to a ConfigException. Because the broker cannot join the cluster, administrators cannot use dynamic APIs such as AlterConfigs to fix the configuration and must instead manually update configuration files across the fleet.

...

1. Broker static reporting: Brokers report their static (non-sensitive) configurations to the controller during registration. This enables the controller to perform pre-flight validation of static configs during metadata version upgrades. On the broker side, BrokerLifecycleManager is responsible for collecting and sending static configs. During registration, it iterates  over all non-internal config entries need to be validated.

2. Metadata-Version-Aware Validators: Configuration definitions are enhanced to support metadata-version-aware validators. The ConfigDef.define() method accepts a mvValidators parameter — Uses NavigableMap.floorEntry() to find the validator registered at the highest feature level ≤ the given featureLevel. This allows  constraints to be introduced incrementally across metadata versions.

   1. During AlterConfigs and IncrementalAlterConfigs operations, the Metadata-Version-Aware validators will be invoked to ensure that any proposed changes are compliant with the cluster's current metadata version. Any configuration that fails this runtime validation will be rejected with an INVALID_CONFIG error.
   2. When an administrator performs a metadata.version upgrade or downgrade, the Controller will execute a comprehensive audit of all existing configurations—both static (via BrokerRegistrationRecord) and dynamic (via ConfigRecord). The transition will only proceed if all current settings satisfy the constraints of the target metadata version, ensuring a safe and atomic version migration.

   3. When an administrator runs kafka-storage format --release-version <version>, the tool now validates the broker's static configs from  server.properties against the MV constraints of the specified release version. If any config violates the constraints, the format command fails with a descriptive error before writing any data to disk.

...

• Add  unit test and integration test to cover this new feature.

Rejected AlternativesIf there are alternative ways of accomplishing the same thing, what were they? The purpose of this section is to motivate why the design is the way it is and not some other way

1. Automatically adjust configuration values to meet new constraints: this approach was rejected because silently modifying configurations without administrator awareness is operationally dangerous and violates the principle of explicit configuration management.
2. Fail immediately with ConfigException on constraint violations: this approach was rejected because it creates operational deadlocks where brokers cannot start and administrators cannot use dynamic APIs to fix the configuration, effectively making the cluster unrecoverable without manual intervention across the entire fleet.