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 is included in the Confluent Platform distribution, 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¶

The tool will help you identify problems with your KRaft controller configuration and ZooKeeper-based cluster before you fully migrate the brokers to KRaft mode. Your brokers should be running in migration mode, and you should have at least one KRaft controller with migration enabled in its properties file before running the tool.

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
/migration ZNode 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 is successful, you will 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 status of the migration¶

You can check the status of the migration using the status option. A status check can be run before, during, or after the migration. It infers the current migration state by looking at the controller configuration file and by the current state of ZooKeeper.

kafka-migration-check --status  --controller-config <controller-config>

Use the status results to resolve any issues that may arise during the migration process.

A status check after migration will look similar to the following:

kafka-migration-check --status --controller-config ../etc/kafka/kraft/controller.properties

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