Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

KIP-339 — IncrementalAlterConfigs

Status: implemented — back to the KIP index.

What the KIP changes in Apache Kafka

Kafka 2.3 added IncrementalAlterConfigs (key 44): per-key SET / DELETE / APPEND / SUBTRACT operations on a resource's configuration, replacing the original AlterConfigs' read-modify-write-the-whole-config semantics that raced concurrent admins.

How kaas implements it

The handler (crates/kaas-broker/src/handlers/incremental_alter_configs.rs, key 44, v0–v1, flexible from v1) follows the same CR-write pattern as KIP-195: after authorizing AlterConfigs on the topic, each op becomes part of a merge PATCH on KafkaTopic.spec.config (crates/kaas-broker/src/topic_cr_writer.rs). The operator materialises the change to /data/<topic>/.config.json (crates/kaas-storage/src/topicconfig.rs), which brokers hot-reload.

The surface is deliberately narrower than the KIP, and the code says so rather than pretending:

  • TOPIC resources only. BROKER and BROKER_LOGGER return UNSUPPORTED_VERSION (35) — kaas has no dynamic broker-config surface.
  • SET and DELETE only. APPEND / SUBTRACT are list-valued ops; every config key kaas supports is scalar, so the writer returns UnsupportedOp and the wire sees 35. SET with a null value is treated as DELETE (patched to JSON null).
  • Six config keys. config_key_to_json_field maps retention.ms, retention.bytes, segment.bytes, cleanup.policy, min.compaction.lag.ms, and delete.retention.ms (dotted or camelCase spellings) onto the CR's fields; anything else is refused with 35.
  • validate_only under-validates. It returns success after the authorization and writer checks but before the writer runs, so unknown keys and APPEND ops pass validation that the real call would reject.
  • Per-resource error codes ride in the response body; a missing CR maps to UNKNOWN_TOPIC_OR_PARTITION (3), RBAC denial and dev mode to CLUSTER_AUTHORIZATION_FAILED (31).

How it's verified

  • crates/kaas-broker/src/topic_cr_writer.rs unit tests: config_key_to_json_field_matches_known_keys, config_value_parses_integer_fields (integers become JSON numbers, unparseable values fall back to strings for operator-side schema rejection), noop_writer_returns_forbidden.
  • crates/kaas-codec/src/api/incremental_alter_configs.rs round-trip tests cover both versions.
  • scripts/kafka-configs.sh scenario 3 drives kafka-configs.sh --alter --add-config retention.ms=... end-to-end. (The script's comments still label it XFAIL from before gh #9 landed — a stale label, not a stale implementation.)

See also the IncrementalAlterConfigs entry in the per-API reference.