skip to content

What version gates and prerequisites must be satisfied before attempting a ZK-to-KRaft migration, and what limitations apply?

level: principalimportance: should knowfreq 38%

answer

  1. metadata.version / IBP >= 3.4-IV0
  2. software 3.4 preview, 3.6+ recommended
  3. upgrade THEN migrate (not both at once)
  4. controllers formatted with existing cluster.id, ZK reachable
  5. one-way after finalize; soak + staging dry-run

basics

~20 s

All brokers and controllers must run a Kafka version supporting migration (3.4+, ideally 3.6+), with metadata.version/inter.broker.protocol.version at least 3.4-IV0. The cluster's brokers must be on a recent IBP, and certain features (e.g., older ZK-only behaviors) must be cleared first.

solid answer

~50 s

Before migrating you must satisfy several gates. Version: migration support landed in 3.4 but had bugs; production guidance is to be on a recent 3.x (3.6+ recommended) for both brokers and the KRaft controllers. Metadata/protocol gate: the KRaft metadata.version feature and the brokers' inter.broker.protocol.version must be at least 3.4-IV0, the lowest version with migration records. The brokers must already be upgraded and on a consistent IBP before you start — you cannot migrate a cluster whose IBP is too old. You also need a properly provisioned KRaft controller quorum formatted with the existing cluster.id, ZK reachable from the controllers, and matching security listeners. Operationally, plan around the one-way nature post-finalize, monitor under-replicated partitions during the roll, and verify that no feature you depend on is unsupported in migration/KRaft. Test the full procedure in a staging cluster first.

go deeper

for a junior

Know there is a minimum Kafka version and metadata version required.

for a middle

Name the 3.4-IV0 gate and the dedicated controller quorum prerequisite.

for a senior

Explain upgrade-then-migrate ordering and security/capacity prerequisites.

for a principal

Own the full go/no-go runbook: version matrix, IBP raise, staging dry-run, abort criteria, and feature-compatibility audit.

## Why prerequisites matter The migration mixes ZK-mode and KRaft-mode nodes simultaneously and relies on specific metadata record types. If any node is too old to understand those records — or the metadata version is too low — the controller refuses to migrate or the cluster misbehaves. Treating prerequisites as a checklist prevents a stuck, half-migrated cluster. ## Version gates 1. **Software version on every node.** ZK-to-KRaft migration was introduced as preview in **Kafka 3.4** and stabilized over 3.5/3.6. The practical rule: upgrade the whole cluster to a recent 3.x release (3.6 or later is the common recommendation) *before* migrating, and run the same family on brokers and the new controllers. Do not attempt migration on 3.3 or earlier. 2. **Metadata version / IBP gate.** The lowest metadata version that supports migration records is **3.4-IV0**. On the KRaft side this is the `metadata.version` feature; on the broker (ZK) side it is `inter.broker.protocol.version`. Both must be at least 3.4-IV0. If your brokers run an older IBP, raise it (via a rolling config change) before starting. 3. **Upgrade-then-migrate ordering.** First get all brokers onto the target Kafka version with a high-enough IBP; only then introduce the migration controllers. Migrating and upgrading at the same time multiplies risk. ## Infrastructure prerequisites - A **dedicated KRaft controller quorum** (3 or 5 nodes) formatted with the **existing cluster.id**. - **ZooKeeper reachable** from the controllers (`zookeeper.connect` set) for the dual-write phase. - **Security parity**: the CONTROLLER listener must use auth compatible with the rest of the cluster (mTLS/SASL), or controllers and brokers cannot connect. - **Capacity headroom**: dual-write adds controller load; ensure controllers and ZK have headroom. ## Limitations and risks to plan for - **One-way after finalize**: no supported rollback once dual-write stops. - **Availability during the roll**: rolling brokers one at a time can dip partitions below `min.insync.replicas` if replication is thin — verify RF and ISR health between restarts. - **Feature compatibility**: confirm everything you rely on (ACL providers, quotas, delegation tokens) is carried by the migration; legacy ZK-only integrations may need replacement. - **Monitoring**: track the `ZkMigrationState` gauge, ZK-write metrics, controller commit latency, and under-replicated partitions throughout. ## Recommended practice Run the entire procedure end-to-end in a **staging cluster that mirrors production** (version, IBP, security, topic count), measure timings, and write a runbook with explicit go/no-go and abort criteria before touching production.

  • What is the minimum metadata.version / IBP for migration and why?
    3.4-IV0 — it is the lowest version that includes the metadata records the migration relies on. Both the KRaft metadata.version and the brokers' inter.broker.protocol.version must meet it.
  • Why upgrade the cluster before migrating rather than at the same time?
    Combining a version upgrade with the ZK-to-KRaft migration multiplies failure modes and makes diagnosis hard. Get all brokers onto the target version and IBP first, then introduce migration controllers.

saying these in an interview costs you the question

  • Attempting migration on Kafka 3.3 or earlier where it is unsupported.
  • Migrating with an IBP/metadata.version below 3.4-IV0.
  • Upgrading Kafka versions and migrating to KRaft in a single combined step.
  • Skipping a staging dry-run and assuming rollback is always available.

context

resolving links…