Page History

...

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.

Schema

[
   {
         "__schema_version__": 0,   // int64 -> represents the version of the node schema
         "__data_version__": 0  // int64 -> represents the version of the data
   },
   {
        "exactly_once_semantics": {   // string -> name of the feature
            "version": 3 // int64 -> represents the cluster-wide finalized version of this feature
        },
        "consumer_offsets_topic_schema": { 
            "version": 4
        }
   }
]

...

1. For correctness reasons, the controller shall allow processing of only one inflight ApiKeys.UPDATE_FEATURES API call at any given time.

2. Prior to mutating '/features' in ZK, the implementation verifies that all broker advertisements (as seen by it thus far) contained no incompatibilities with the provided List<FeatureUpdate> (see Validations section below).

3. Once validations in #2 are successful, the List<FeatureUpdate> are applied to contents of '/features' ZK node, and it’s __data_version__ is incremented by 1.

4. If #3 is successful, ApiKeys.UPDATE_METADATA requests are issued to all brokers in the cluster. This can incur a slight latency cost, so we expect this API call to succeed/fail in worst case within few seconds (depending on the size of the cluster).

5. Finally, an UpdateFeatureResponse is returned to the user. The metadata version number is the latest __data_version__ in the ZK node: '/features' after the mutations were applied to it.

...

1. Each FeatureUpdate provided in the request was valid, and all updates were persisted to the '/features' ZK node by the controller (along with a bump to the node’s  __data_version__).

2. An ApiKeys.UPDATE_METADATA call was successfully made by the controller to all live brokers (as seen by the controller) with the latest dictionary of cluster-wide finalized feature versions.

3. Future ApiKeys.UPDATE_METADATA calls from controller to brokers will contain the latest set of cluster-wide feature versions, enabling brokers to shutdown when incompatibilities are detected (see Broker protections section).

4. The returned object in the ApiKeys.UPDATE_FEATURES API call contains the latest set of cluster-wide feature versions (after all updates were applied), which can be useful to the client for debugging/logging purposes.

...

Note that the field FinalizedFeaturesMetadataVersion contains the latest version of the metadata stored in the __data_version__ field in the ZK node. On the client side, the value of this field should be used to ignore older metadata returned in ApiVersionsResponse, after newer metadata was returned once (eventual consistency).

...