...
Code Block | ||
---|---|---|
| ||
// ---- START: Proposed Admin API definitions ---- /** * Describes supported and finalized features. You may anticipate * certain exceptions when calling get() on the future obtained from the returned * DescribeFeaturesResult. * * @param options options for the describeFeatures API, * * @return a result object containing: * 1. List of cluster-wide finalized feature versions. * 2. List of supported feature versions specific to the broker. */ DescribeFeaturesResult describeFeatures(DescribeFeaturesOptions options); /** * Update the feature versions supported cluster-wide. You may * anticipate certain exceptions when calling get() on the futures * obtained from the returned UpdateFeaturesResult. * * @param updates map of feature updates, keyed by the * name of the feature * @param options options for the updateFeatures API * * @return the results of the FeatureUpdate provided in the request */ UpdateFeaturesResult updateFeatures(Map<String, FeatureUpdate> featureUpdates, UpdateFeaturesOptions options); /** * Options for {@link AdminClient#describeFeatures(DescribeFeaturesOptions)}. * * The API of this class is evolving. */ @InterfaceStability.Evolving public class DescribeFeaturesOptions extends AbstractOptions<DescribeFeaturesOptions> { //** Currently empty, * Sets a flag indicating that the describe features request mustbut can be issuedpopulated only toin the controller. future * - True means the {@link Admin#describeFeatures(DescribeFeaturesOptions)} request must be * issued only to the controller. * - False means the {@link Admin#describeFeatures(DescribeFeaturesOptions)} request can be * issued to any random broker. */ public DescribeFeaturesOptions sendRequestToController(boolean sendRequestToController). as needed. } /** * -Options Returns true if the Admin#describeFeatures(DescribeFeaturesOptions) request must be * issued only to the controller. * - Returns false if the Admin#describeFeatures(DescribeFeaturesOptions) request can be * issued to any random broker. */ public boolean sendRequestToController();for {@link AdminClient#describeFeatures(UpdateFeaturesOptions)}. * * The API of this class is evolving. */ @InterfaceStability.Evolving public class UpdateFeaturesOptions extends AbstractOptions<UpdateFeaturesOptions> { // Currently empty, but can be populated in the future as needed. } // ---- END: Proposed Admin API definitions ---- // Represents a range of version levels supported by every broker in a cluster for some feature. class FinalizedVersionRange { // The cluster-wide finalized value of the feature min version level (value >= 1). short minVersionLevel(); // The cluster-wide finalized value of the feature max version level (value >=1 and value >= minVersionLevel). short maxVersionLevel(); } // Represents a range of versions that a particular broker supports for some feature. class SupportedVersionRange { // The minimum version (value >= 1) of the supported feature. short minVersion(); // The maximum version (value >=1 and value >= minVersion) of the supported feature. short maxVersion(); } /** * Represents an update to a Feature, which can be sent to the controller * for processing. */ class FeatureUpdate { /** * The cluster-wide finalized NEW value of the feature max version level. * - When >= 1, it's the new value to-be-updated for the finalized feature. * - When < 1, it indicates the deletion of a finalized feature. */ short maxVersionLevel(); /** * Return true only if downgrade/deletion of a feature should be allowed. * Note that despite this allowDowngrade flag being set, certain downgrades * may be rejected by the controller if it is deemed unsafe to downgrade * the max version level of some specific feature. */ bool allowDowngrade(); } /** * Encapsulates details about finalized as well as supported features. This is particularly useful * to hold the result returned by the `Admin#describeFeatures(DescribeFeaturesOptions)` API. */ class FeatureMetadata { /** * Returns a map of finalized feature versions. Each entry in the map contains a key being a * feature name and the value being a range of version levels supported by every broker in the * cluster. */ Map<String, FinalizedVersionRange> finalizedFeatures(); /** * The monotonically increasing epoch for the finalized features. * If the returned value is empty, it means the finalized features are absent/unavailable. */ Optional<Long> finalizedFeaturesEpoch(); /** * Returns a map of supported feature versions. Each entry in the map contains a key being a * feature name and the value being a range of versions supported by a particular broker in the * cluster. */ Map<String, SupportedVersionRange> supportedFeatures(); } class DescribeFeaturesResult { /** * The data returned in the future contains the latest entire set of * finalized cluster-wide features, as well as the entire set of * features supported by the broker serving this read request. */ KafkaFuture<FeatureMetadata> featureMetadata(); } class UpdateFeaturesResult { /** * Returns a future which succeeds only if all the FeatureUpdate in the request succeed. */ KafkaFuture<Void> all(); /** * Returns a map with key being feature name and value being * the future which can be used to check the status of the FeatureUpdate * in the request. * * Possible error codes: * - NONE: The FeatureUpdate succeeded. * - NOT_CONTROLLER: The FeatureUpdate failed since the request was processed by a broker that's not the controller. * - CLUSTER_AUTHORIZATION_FAILED: The FeatureUpdate failed since there wasn't sufficient permission to perform the update. * - INVALID_REQUEST: The FeatureUpdate failed because it is invalid. * - FEATURE_UPDATE_FAILED: The FeatureUpdate failed because it can not be applied (ex: due to version incompatibilities) */ Map<String, KafkaFuture<Void>> values(); } |
...
Code Block |
---|
=== DESCRIBE FEATURES === # Get cluster-wide finalized features, and features supported by a specific broker. # - Use `--bootstrap-server` to provide a broker host:port to which queries should be issued. # - Optionally, provide `--from-controller` flag to describe the features only from the controller. # This can be useful for debugging purposes. $> kafka-features.sh --describe \ --bootstrap-server kafka-broker0.prn1:9071 \ [--from-controller] Feature: consumer_offsets_topic_schema SupportedMinVersion: 1 SupportedMaxVersion: 1 FinalizedMinVersionLevel: - FinalizedMaxVersionLevel: - Epoch: 1 Feature: group_coordinator SupportedMinVersion: 1 SupportedMaxVersion: 2 FinalizedMinVersionLevel: 1 FinalizedMaxVersionLevel: 1 Epoch: 1 Feature: transaction_coordinator SupportedMinVersion: 1 SupportedMaxVersion: 5 FinalizedMinVersionLevel: 1 FinalizedMaxVersionLevel: 4 Epoch: 1 === UPGRADE TO ALL LATEST FEATURES === # Upgrade to the max version levels of all features, as internally known to the CLI tool. # # - This command removes the burden to individually finalize feature upgrades. # This becomes handy to a cluster operator intending to finalize a cluster with all the latest # available feature version levels. This usually happens after completing the deployment # of a newer Kafka Broker release onto an existing cluster. # - Use `--bootstrap-server` to provide a broker host:port to which queries should be issued. # - Optionally, use the `--dry-run` flag to list the feature updates without applying them. $> kafka-features.sh \ --upgrade-all \ --bootstrap-server kafka-broker0.prn1:9071 \ [--dry-run] [Add] Feature: consumer_offsets_topic_schema ExistingFinalizedMaxVersion: - NewFinalizedMaxVersion: 1 Result: OK [Upgrade] Feature: group_coordinator ExistingFinalizedMaxVersion: 1 NewFinalizedMaxVersion: 2 Result: OK [Upgrade] Feature: transaction_coordinator ExistingFinalizedMaxVersion: 4 NewFinalizedMaxVersion: 5 Result: OK === EMERGENCY DOWNGRADE ALL FEATURES === # Downgrade to the max version levels of all features known to the CLI tool. # # - This command removes the burden to individually finalize feature version # downgrades. This becomes handy to a cluster operator intending to downgrade all # feature version levels, just prior to rolling back a Kafka Broker deployment # on a cluster, to a previous Broker release. # - Optionally, use the `--dry-run` flag to list the feature updates without applying them. $> kafka-features.sh \ --downgrade-all \ --bootstrap-server kafka-broker0.prn1:9071 \ [--dry-run] [Delete] Feature: consumer_offsets_topic_schema ExistingFinalizedMaxVersion: 1 NewFinalizedMaxVersion: - Result: OK [Downgrade] Feature: group_coordinator ExistingFinalizedMaxVersion: 2 NewFinalizedMaxVersion: 1 Result: OK [Downgrade] Feature: transaction_coordinator ExistingFinalizedMaxVersion: 5 NewFinalizedMaxVersion: 4 Result: OK |
...