...
The usual regular usage of the API is a feature upgrade. This is by specifying a higher new max feature version level value (i.e. Y
> X)
.By default, the API disallows max feature version level downgrades (Y
< X) a
nd finalized feature deletions (Y< 1)
. Such changes are allowed to be attempted only if theallowDowngrade
flag is additionally set in the request. Note that despite theallowDowngrade
flag being set, certain downgrades may be rejected by the controller, if the action is deemed impossible.If any broker does not contain a required feature, this is considered an incompatibility → such a case will fail the API request.
If any broker contains an additional feature that’s not required → this is not considered an incompatibility.
Some/all of the above logic will also be used by the broker (not just the controller) for it’s protections (see this section of this KIP).
Activating the effects of a feature version cluster-wide is left to the discretion of the logic implementing the feature (ex: can be done via dynamic broker config).
Deprecating/eliminating the presence/effects of a specific feature version cluster-wide is left to the discretion of the logic backing the feature (ex: can be done via dynamic broker config). However, it may need further external verification to ensure no entity (ex: a consumer, or a broker) is actively using the feature (see Non-goals section).
Guarantees
When a call to the ApiKeys.UPDATE_FEATURES
API returns a success return code to the client, the following is guaranteed:
...