Page History

...

• The API requires AclOperation.ALTER on ResourceType.CLUSTER.

• The API request contains a list of FeatureUpdate that need to be applied, as explained below:

  • Each item specifies the finalized feature to be added or updated or deleted, along with the new max feature version level value.

  • To add a new finalized feature version level, or update an existing one, the user must specify the version level starting from 1 (and increasing).
  • Downgrade or deletion of feature version level, is not a regular operation/intent. As an override, each item optionally can specify an allowDowngrade flag, to convey user intent to attempt max version level downgrade/deletion. Note that despite this allowDowngrade flag being set, certain downgrades may be rejected by the system controller if it is deemed impossible.

  • If a finalized feature needs to be permanently deleted, the user must specify a max version level value < 1, and should also set the allowDowngrade flag.

• The API response contains an error code and an error message.
• Changes to cluster-wide finalized minimum feature version level, can not be carried out using this API. This can be only done as explained later under Feature version deprecation section.

...

For any <feature_name>, the above API implementation guards against a change for the related entry in '/features' from {"max_version_level": X} to {"max_version_level": X’}, unless, it notices that each live broker in the deployment advertises {"maxVersion": Y >= X’} and {"minVersion": Z <= X’} in it’s BrokerIdZnode (for the same <feature_name>). A similar check is also applied to changes in the "min_version_level" for a feature.

Related with the above guarding checks:

Note the following rules:

1. The usual regular usage is a feature upgrade. This is done by specifying a higher new max feature version level value (i.e. X' > X). 

2. By default, the API disallows

...

1.  max feature version level downgrades

...

1. (X' < X) and deletions (X' < 1). Such changes are allowed to be attempted only if the allowDowngrade flag is specified. Note that despite this allowDowngrade flag being set, certain downgrades may be rejected by the controller if it is deemed impossible.

2. If any broker does not contain a required feature, this is considered an incompatibility → such a case will fail the API request.

3. If any broker contains an additional feature that’s not required → this is not considered an incompatibility.

4. 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).

5. 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).

6. 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:

...