Migration mode is Kafka’s transitional configuration state for moving cluster metadata management from ZooKeeper to KRaft. It lets new KRaft controllers replicate metadata while existing brokers continue operating with ZooKeeper, creating a reversible testing stage before the final cutover. section 7.3 section 7.5
A controlled migration typically follows these stages:
- Provision three or five additional KRaft controllers using the same cluster ID as the ZooKeeper cluster. section 7.3
- Enable zookeeper.metadata.migration.enable=true on the controllers and existing brokers, and configure ZooKeeper connectivity plus the new controller connections. section 7.3
- Wait for the controllers to replicate ZooKeeper metadata, then verify that the brokers report successful migration. section 7.3
- Move ordinary brokers to KRaft by removing migration mode and ZooKeeper connectivity and setting process.roles=broker. section 7.3
- Run the mixed state for a week or two to test stability; disabling migration mode on controllers and removing ZooKeeper connectivity completes the irreversible cutover. section 7.3
Staged controller migration
An existing ZooKeeper cluster adds three or five KRaft controllers with an identical cluster ID. Operators enable zookeeper.metadata.migration.enable=true, supply ZooKeeper and controller connection details, verify replication, and leave the cluster in the intermediate state before committing to KRaft. section 7.3 section 7.5
Completed migration of metadata from ZooKeeper to KRaft
Use the completed-migration listing to review the target state after metadata has moved fully from ZooKeeper to KRaft. section 7.3
