Module krabka_version

Expand description

The krabka-owned krabka.version feature (KIP-584).

From krabka-broker 1.0.0 on, krabka.version gates every krabka-only on-disk and inter-node format change, as metadata.version does for Kafka’s. metadata.version mirrors Kafka’s MetadataVersion table level for level, so krabka cannot add a level there. A broker keeps writing and sending the old format until the operator finalizes the krabka.version level that introduces the new one.

§Levels

Level 0 means exactly the krabka-broker 1.0.0 formats. An image that has no finalized krabka.version reads as level 0, as Kafka treats an absent feature (see KrabkaVersion::finalized).
Level 1 also means exactly the 1.0.0 formats. It carries no format change, and it never will: a 1.0.0 node advertises support for it, so a later release cannot give it a meaning that 1.0.0 nodes do not know. The first krabka-only format change takes level 2.
Level 2 turns on diskless WAL object reservations (DISKLESS_OBJECT_RESERVATION_LEVEL). A broker records a reservation for a WAL object in __diskless_wal_index before it uploads the object, and clears it once the object’s index records are applied, so no broker reclaims an object whose index publication is still in flight. The reservation reuses the 1.x delete-floor record encoding, so every 1.x reader can still replay it. Below level 2 a broker writes no reservations. Level 2 changes no private RPC version.
Level 3 turns on two formats. Level 2 shipped in krabka-broker 1.1.3, so a later format cannot join it.
- The OCSF 1.3.0 activity ids of __krabka_audit records (OCSF_ACTIVITY_IDS_LEVEL). Application Lifecycle reports a start as activity 3 (Start) and a stop as 4 (Stop), Authorize Session reports an ACL denial as 99 (Other), API Activity reports an admin operation as Create, Read, Update or Delete where one applies, and a record carries metadata.log_version "2". Below level 3 a broker writes the 1.0.0 shape. krabka-audit verify hashes each record’s bytes, so a chain that mixes both shapes still verifies.
- The normalized tiered-storage key prefix (TIERED_KEY_PREFIX_NORMALIZED_LEVEL). A broker trims spaces and slashes from the configured prefix before it builds a segment key, as it already does for diskless WAL objects. Below level 3 it writes the key with the prefix exactly as configured. A reader looks a segment up under both forms at every level.
Level 3 changes no private RPC version.

§Why the maximum is 1, not 0

Kafka does not advertise a feature whose highest supported level is 0. BrokerFeatures.defaultSupportedFeatures and QuorumFeatures.defaultSupportedFeatureMap both add a feature to the supported map only when maxVersion > 0, and the controller treats a feature that a node does not advertise as supported at [0, 0]. A feature with a maximum of 0 therefore cannot be finalized above 0, and kafka-features describe, which lists supportedFeatures, would show it only because krabka breaks that rule. With a maximum of 1, krabka.version appears in kafka-features describe, and kafka-features upgrade --feature krabka.version=1 finalizes it. kafka-features upgrade --release-version iterates Kafka’s own Feature.PRODUCTION_FEATURES only, so it never touches krabka.version.

§Why a fresh cluster bootstraps at 0

A fresh cluster bootstraps krabka.version at KRABKA_VERSION_MIN, whatever the bootstrap metadata.version is, so krabka format writes no FeatureLevelRecord for it, as Kafka writes none for a feature at level 0. An Apache Kafka node in the same cluster does not know krabka.version, so it treats the feature as supported at [0, 0] (QuorumFeatures.DISABLED). A Kafka controller that replays a finalized level above 0 halts: it throws “this controller only supports versions 0”, and its ProcessTerminatingFaultHandler exits. A Kafka broker cannot register with a controller that has finalized a level above 0.

This departs from Kafka’s rule for its own production features, which bootstrap at their latest level. That rule holds because every Kafka node of the release knows those features. krabka.version is not one of Kafka’s features, so no Kafka node ever knows it. Nothing is lost: levels 0 and 1 mean the same formats.

An operator finalizes krabka.version with kafka-features upgrade --feature krabka.version=1 once every node supports it. The controller refuses a level that some registered node does not support, and a Kafka node, which advertises nothing for the feature, supports only 0.

§Dependencies

krabka.version declares no KIP-1022 dependency on metadata.version. A future level that needs a Kafka record shape adds one for that level only.

§Private-RPC version negotiation

private_rpc_version is the negotiation mechanism for the krabka-private controller RPCs, the same one Kafka uses for inter-broker protocol versions through metadata.version. The controller finalizes a level only once every registered node advertises support for it. The finalized level therefore tells a sender which request versions every peer serves, and a sender never sends a version above the one the table gives for that level.

Structs§

KrabkaVersion: The finalized krabka.version level of a metadata image.

Enums§

PrivateRpc: A krabka-private controller RPC. Its api key sits at 1000 or above, so a later Kafka assignment cannot collide with it.

Constants§

DISKLESS_OBJECT_RESERVATION_LEVEL: The first level at which a broker writes diskless WAL object reservations before it uploads an object. See the module docs.
KRABKA_VERSION_FEATURE: KIP-584 feature name.
KRABKA_VERSION_MAX: Maximum supported level, and the latest production level. Level 1 means the same formats as level 0. See the module docs for the meaning of each level.
KRABKA_VERSION_MIN: Minimum supported level: the krabka-broker 1.0.0 formats.
OCSF_ACTIVITY_IDS_LEVEL: The first level at which a broker writes __krabka_audit records with the OCSF 1.3.0 activity ids. See the module docs.
TIERED_KEY_PREFIX_NORMALIZED_LEVEL: The first level at which a broker normalizes the configured tiered-storage prefix before it builds a segment key. See the module docs.

Functions§

private_rpc_version: The highest request version of the private controller RPC api_key that a node may send when the finalized krabka.version is krabka_version.