Check Clusters for KRaft Migration
This topic describes the kafka-migration-check utility provided by Confluent, which enables you to check your Kafka clusters before migrating from ZooKeeper to KRaft, and check the status of the KRaft migration during the migration process.
Starting with Confluent Platform version 7.6, KRaft (pronounced craft) mode is the preferred method for managing metadata in Apache Kafka®. Kafka Raft (KRaft) is the consensus protocol that simplifies Kafka’s architecture by consolidating responsibility for metadata management directly into the Kafka brokers themselves.
For existing clusters, there is a migration process to move from ZooKeeper to KRaft mode. This migration process is described in Migrate from ZooKeeper to KRaft on Confluent Platform.
Install kafka-migration-check
The kafka-migration-check utility is included in the Confluent Platform distribution for the following versions:
Confluent Platform 7.7.5 or later
Confluent Platform 7.8.5 or later
Confluent Platform 7.9.2 or later
You can find it in the bin directory of your Confluent Platform installation. To install Confluent Platform, see Install Confluent Platform On-Premises.
Learn about migration
You should read through the Migrate from ZooKeeper to KRaft on Confluent Platform topic before running the kafka-migration-check utility to help you understand the migration process, and the steps to migrate from ZooKeeper to KRaft.
Run the tool
This tool identifies problems with your KRaft controller configuration and ZooKeeper-based cluster before you fully migrate the brokers to KRaft mode. Before running the tool, ensure your brokers are running in migration mode and at least one KRaft controller has migration enabled in its properties file.
Following are the options you can use with the kafka-migration-check utility:
kafka-migration-check --help
usage: kafka-migration-check [-h] {preflight-check,status} ...
this tool checks ZK migration status
positional arguments:
{preflight-check,status}
preflight-check Run preflight checks prior to starting zk migration
status Get the status of the current ZK migration.
optional arguments:
-h, --help show this help message and exit
Run the preflight check
The preflight check is intended to be run before migration is started. It checks for some common problems, including:
ZooKeeper not reachable using the controller configuration file
Brokers not reachable using the controller configuration file
Migration not enable by failing to set
zookeeper.metadata.migration.enable/migrationZNode or other migration state not present for ZooKeeper prior before migration starts
Usage of the preflight check is as follows:
kafka-migration-check preflight-check --controller-config <controller-config>
An example of calling the preflight check option might look like the following:
kafka-migration-check preflight-check --controller-config ../etc/kafka/kraft/controller.properties
Example output that indicates an issue:
If using `zookeeper.metadata.migration.enable` in KRaft mode, `zookeeper.connect` must also be set.
Fix all the issues identified by the preflight check before proceeding with the migration.
When the preflight check succeeds, you see output similar to the following:
======================================================================
Running preflight migration check.
controllerConfigPath = ../etc/kafka/kraft/controller.properties
======================================================================
Checking controller config...
Loading zookeeper znodes..
Checking zookeeper znodes...
Testing outbound connections to brokers...
Testing outbound connection to BrokerEndPoint(id=0, host=127.0.0.1:%d)
Testing outbound connection to BrokerEndPoint(id=1, host=127.0.0.1:%d)
All preflight checks passed.
Check the migration status
To check the migration status, use the status option. You can run a status check before, during, or after the migration. The tool infers the current migration state from the controller configuration file and the current state of ZooKeeper.
kafka-migration-check status --controller-config <controller-config>
Use the status results to resolve any issues during the migration process. Run this command after completing each migration phase to verify the cluster is in the expected state before proceeding to the next phase.
Migration status outputs
The status command returns one of four possible migration states. You can use these states to understand where your cluster is in the migration process and what steps to take next.
PREMIGRATION
Migration has not started. Your cluster runs with a ZooKeeper controller managing metadata.
You see this status when:
You have not started migration yet.
You started KRaft controllers in Phase 2, but they are not running or not configured with
zookeeper.metadata.migration.enable=true.
Example output:
======================================================================
Running migration status check.
controllerConfigPath = ../etc/kafka/kraft/controller.properties
======================================================================
Checking controller config..
zookeeper.metadata.migration.enable = true. Loading zookeeper znodes...
/controller znode contains ZK controller <broker_id>
Apparent mode: PREMIGRATION
HYBRID_DUAL_WRITE
The KRaft controller has taken over as the active controller, but some brokers are still running in ZooKeeper mode. The KRaft controller writes metadata to both KRaft and ZooKeeper.
You see this status when:
You are in Phase 3 and restarting brokers with migration configuration.
You restarted all brokers, but some are not reconfigured with the correct migration properties.
Example output:
======================================================================
Running migration status check.
controllerConfigPath = ../etc/kafka/kraft/controller.properties
======================================================================
Checking controller config..
zookeeper.metadata.migration.enable = true. Loading zookeeper znodes...
/controller znode contains KRAFT controller <broker_id>
Some znodes for ZK brokers remain: <broker_ids>. Cluster appears to be in HYBRID_DUAL_WRITE
Apparent mode: HYBRID_DUAL_WRITE
PURE_DUAL_WRITE
You have migrated all brokers to KRaft mode. The KRaft controller still writes metadata to both KRaft and ZooKeeper, which allows you to roll back to ZooKeeper if needed.
You see this status when:
You are in Phase 4. Run in this mode for an extended period, such as 1-2 weeks, to verify stability before finalizing the migration.
You are ready to finalize. Proceed to Phase 5 to complete the migration.
Example output:
======================================================================
Running migration status check.
controllerConfigPath = ../etc/kafka/kraft/controller.properties
======================================================================
Checking controller config..
zookeeper.metadata.migration.enable = true. Loading zookeeper znodes...
/controller znode contains KRAFT controller <broker_id>
No znodes for ZK brokers remain.
Apparent mode: PURE_DUAL_WRITE
FINALIZED
Migration is complete. Your cluster runs entirely in KRaft mode, and metadata is no longer written to ZooKeeper.
You see this status when:
You completed Phase 5. You can safely shut down the ZooKeeper cluster.
Important
You cannot revert to ZooKeeper mode after reaching this state.
Example output:
======================================================================
Running migration status check.
controllerConfigPath = ../etc/kafka/kraft/controller.properties
======================================================================
Checking controller config..
zookeeper.metadata.migration.enable = false and zookeeper.connect = null. Migration appears to be fully FINALIZED.
Apparent mode: FINALIZED