THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
Following are problems surrounding downgrades/deprecation, that we don’t intend to solve with this KIP:
Sometimes there can be a need to downgrade the cluster-wide availability of one or more broker features from some finalized version X to a version Y, where Y < X. Firstly, we leave it to the cluster operator (i.e. human) to decide whether the downgrade is backwards compatible in the first place i.e. externally ensure the changes introduced/exercised in version Y are no longer relevant in the system ahead of the downgrade. As for the support we provide:
The rules are the same as with upgrades → such a downgrade request is rejected by the system, unless all brokers support the downgraded version Y of the feature.
- We assume downgrades of finalized feature max versions are rare. For safety reasons, we request for the human to specify an explicit "force downgrade" flag (in the API/tool) to avoid accidental downgrades to finalized max versions.
A need can arise to deprecate the usage of a certain version of one or more broker feature. We do not provide any special support for this. Instead, the cluster operator (i.e. human) should use external means to establish that it is safe to stop supporting a particular version of broker feature. For example, verify (if needed) that no clients are actively using the version, before deciding to stop supporting it.
Proposed Changes
Below is a TL;DR of the changes:
...
The proposal is that cluster-wide finalized feature max versions will be persisted in a specific common ZK node. The path to the ZK node is proposed as: '/features' . The node content type is JSON (string), and the size is expected to be typically small (in several KBs). Couple high level details:
- During regular operations, the data in the ZK node can be mutated only via a specific admin API served only by the controller.
The node data shall be readable via existing ZK tooling. An eventually consistent copy of the node data shall also be made readable via existing
ApiKeys.API_VERSIONSAPI served by any broker in the cluster . (see this section)During regular operations, the data in the ZK node can be mutated only via a specific admin API served only by . The latest copy of the node data will be cached in the controller, and if needed this can be obtained by directing theApiKeys.API_VERSIONSAPI to the controller.
The above proposed read/write paths are described later in this doc. Below is an example of the contents of the '/features' ZK node, with it’s schema explained below.
...
| 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 `--controller` flag directing the tool to issue the query to the
# controller (while discovering the controller via the bootstrap server).
# This can be useful for debugging purposes.
$> kafka-features.sh describe --bootstrap-server kafka-broker0.prn1:9071 [--controller]
{
"status": "OK",
"supported_features": {
"group_coordinator": {
"minVersion": 1,
"maxVersion": 2
},
"transaction_coordinator": {
"minVersion": 0,
"maxVersion": 5
},
"consumer_offsets_topic_schema": {
"minVersion": 0,
"maxVersion": 0
}
},
"finalized_features": {
"epoch": 0,
"group_coordinator": {
"version": 1
},
"transaction_coordinator": {
"version": 4
}
},
"host": "kafka-broker0.prn1",
"port": 9071
}
=== ADD_OR_UPDATE FEATURES ===
# Add or update a list of cluster-wide finalized features.
# - Use `--bootstrap-server` to provide a broker host:port to which MetadataRequest query should be issued.
# The MetadataResponse will be used to discover the Controller, to which the actual ADD_OR_UPDATE request is issued.
# - Use `--feature-upgrade` to provide a feature comma-separated list of features and new finalized max version to ADD_OR_UPDATE. Note that the flag can be used multiple times to specify multiple features.
# - Use `--feature-force_downgrade` to force downgrade of aprovide a comma-separated list of features and new finalized featuremax version., Thiswith shoulda bedowngrade usedallowed onlyfor whenfeature requiredversions. Note that the flag canThis should be used multipleonly times to specify multiple featureswhen required.
$> kafka-features.sh update \
--bootstrap-server kafka-broker0.prn1:9071 \
--feature-upgrade group_coordinator:2,my_new_feature:0 \
--feature-force-downgrade transaction_coordinator:3 \
--feature-upgrade my_new_feature:0
Please confirm before finalizing the upgrade of the following features:
1. group_coordinator from v1 (existing) to v2 (new)
2. consumer_offsets_topic_schema from none (existing) to v0 (new)
[Y/n]? Y
Please confirm before downgrading the following features:
1.transaction_coordinator from v4 (existing) to v3 (new)
[Y/n]? Y
{
"status": "OK",
"supported_features": {
"group_coordinator": {
"minVersion": 1,
"maxVersion": 2
},
"transaction_coordinator": {
"minVersion": 0,
"maxVersion": 5
},
"consumer_offsets_topic_schema": {
"minVersion": 0,
"maxVersion": 0
}
},
"finalized_features": {
"epoch": 1,
"group_coordinator": {
"version": 2
},
"transaction_coordinator": {
"version": 3
},
"consumer_offsets_topic_schema": {
"version": 0
}
},
"host": "kafka-broker0.prn1",
"port": 9071
}
=== DISABLE FEATURES ===
# Disable/delete a list of cluster-wide finalized features.
# - Use `--bootstrap-server` to provide a broker host:port to which MetadataRequest query should be issued.
# The MetadataResponse will be used to discover the Controller, to which the actual delete request is issued.
# - Use `--features` to provide a comma-separated list of features to be deleteddisabled.
$> kafka-features.sh disable --bootstrap-server kafka-broker0.prn1:9071 --features group_coordinator,transaction_coordinator
Please confirm deletiondisabling of the following features. Note that the latest finalized feature version value for the disabled feature, will be lost forever:
1. group_coordinator
2. transaction_coordinator
[Y/n] Y
{
"status": "OK",
"supported_features": {
"group_coordinator": {
"minVersion": 1,
"maxVersion": 2
},
"transaction_coordinator": {
"minVersion": 0,
"maxVersion": 5
},
"consumer_offsets_topic_schema": {
"minVersion": 0,
"maxVersion": 0
}
},
"finalized_features": {
"epoch": 2,
"consumer_offsets_topic_schema": {
"version": 0
}
},
"host": "kafka-broker0.prn1",
"port": 9071
} |
...