Migrate Kafka data

Complete Kafka migration before upgrading the 25.10 appliance.

Kafka migration before the upgrade on VA 25.10

Kafka must move from ZooKeeper to KRaft before upgrading from 25.10. The bundle performs the migration automatically, retains the existing Kafka data and cluster identity, and saves the identity needed by 26.7.1.

  1. Prepare the 25.10 appliance before service shutdown.

    Run on the source appliance. Keep services running until the bundle completes. Avoid concurrent start or sync operations during preparation.

    The bundle detects the source release automatically, completes ZooKeeper-to-KRaft migration and captures the original identity.

  2. Run Kafka migration.
    Obtain the updated kafka-migrate.tar bundle and copy it to the source node where you will initiate the platform backup.
    CODE 
    tar -xf kafka-migrate.tar
cd kafka-migrate
sudo bash run.sh run

    Wait for this command to succeed. During migration, the bundle:

    • Checks the appliance and Kafka health before making changes.
    • Moves Kafka metadata to KRaft while retaining the existing broker data.
    • Completes the migration and removes the retired ZooKeeper storage after archiving it.
    • Verifies Kafka readiness and the retained storage, then saves the Kafka identity file.

    Allow the command to finish. Repeated waiting messages are normal while services update. The recorded one-node example completed in about eight minutes; your migration may take longer depending on the deployment.

    Successful completion reports "Checkpoint: complete" and "KRaft is healthy". The verification command must also finish successfully before you continue.

  3. Verify the data migration using the following command.
    CODE 
    sudo bash run.sh verify
    Note: If any command run.sh run or run.sh verify fails, resolve the reported error and rerun before shutting down services.
  4. View the migration progress and status.
    CODE 
    sudo bash run.sh status
    CAUTION:

    If migration fails, keep services running, resolve the reported error and rerun this command. The bundle resumes from its saved progress. Do not proceed with service shutdown until run and verify succeed.

    After migration completes, continue with the upgrade procedure. Do not redeploy the old 25.10 ZooKeeper-based Kafka configuration; completed KRaft migration cannot be reversed to ZooKeeper in place.

    Kafka identity file is created at /var/appd/config/kafka-identity.json.

Continue with the upgrade, see Upgrade the Virtual Appliance.