<a id="kraft-migration-tool"></a>

# 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](../installation/migrate-zk-kraft.md#migrate-zk-kraft).

<!-- Add this for CP 8
If you have clusters running in |zk| mode, you must migrate them to |kraft| before you can upgrade to |cp| 8.0.
change paths for CP 8 -->

## 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](../installation/overview.md#installation).

## Learn about migration

You should read through the [Migrate from ZooKeeper to KRaft on Confluent Platform](../installation/migrate-zk-kraft.md#migrate-zk-kraft) 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:

```bash
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

Run the preflight check while your cluster is still running in ZooKeeper mode, before you start the migration.

#### IMPORTANT
Run the preflight check only before any migration attempt. It produces
meaningful results only beforehand. Running it during a migration is not
useful. To check the state of an in-progress migration, use the
`kafka-migration-check status` command instead.

The preflight check validates the following items:

- The controller configuration file is present and `zookeeper.metadata.migration.enable` is set to `true`.
- Required ZooKeeper znodes and authentication data are accessible.
- No previous KRaft controller or stale migration state exists, such as a leftover `/migration` znode in ZooKeeper.
- All expected brokers are reachable and the broker population is healthy.
- Brokers and cluster links are migration-ready, and each broker responds to an `ApiVersions` request as a ZooKeeper-based broker with migration enabled.
- No stale or orphaned cluster link metadata entries remain in ZooKeeper.

Usage of the preflight check is as follows:

```bash
kafka-migration-check preflight-check --controller-config <controller-config>
```

An example of calling the preflight check option might look like the following:

```bash
kafka-migration-check preflight-check --controller-config ../etc/kafka/kraft/controller.properties
```

Example output that indicates an issue:

```bash
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:

```bash
======================================================================
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.

```bash
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](../installation/migrate-zk-kraft.md#phase-2), but they are not running or not configured
  with `zookeeper.metadata.migration.enable=true`.

Example output:

```bash
======================================================================
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](../installation/migrate-zk-kraft.md#phase-3) and restarting brokers with migration configuration.
- You restarted all brokers, but some are not reconfigured with the correct migration properties.

Example output:

```bash
======================================================================
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 <controller_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](../installation/migrate-zk-kraft.md#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](../installation/migrate-zk-kraft.md#phase-5) to complete the migration.

Example output:

```bash
======================================================================
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 <controller_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](../installation/migrate-zk-kraft.md#phase-5). You can safely shut down the ZooKeeper cluster.

#### IMPORTANT
You cannot revert to ZooKeeper mode after reaching this state.

Example output:

```bash
======================================================================
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
```

## Related content

- [Migrate from ZooKeeper to KRaft on Confluent Platform](../installation/migrate-zk-kraft.md#migrate-zk-kraft)
- [KRaft Configuration for Confluent Platform](../kafka-metadata/config-kraft.md#configure-kraft)
- [KRaft Overview for Confluent Platform](../kafka-metadata/kraft.md#kraft-overview)