This document outlines the steps to perform an in-place upgrade of the Kafka cluster from Kafka 2.x to Kafka 3.x using the same data directories and ZooKeeper quorum.
Pre-requisites
The existing Kafka 2.x cluster is running and stable.
The current data log directory (used by Kafka 2) is available and will be reused by Kafka 3.
Ensure Ambari is up and running.
Upgrade will be performed in ZooKeeper mode (not KRaft).
1. Validate the Existing Kafka 2 Setup
Before starting the upgrade, verify that the Kafka 2 cluster is fully functional.
List Topics
Create a Sample Topic
Produce Sample Data
Consume the Data
Verification: Messages are successfully produced and consumed. Kafka 2 setup is healthy.
2. Prepare for the Upgrade
Update Broker Protocol Compatibility
Before installing Kafka 3, update the following property under Ambari → Kafka → Configs → Custom kafka-broker:
Restart all Kafka brokers from Ambari to apply the configuration. This ensures smooth compatibility during the upgrade.
3. Install Kafka 3 Management Pack (MPack)
Run the following commands on all the nodes on which Kafka 2 is installed:
Then restart the Ambari Server:
4. Upgrade to Kafka 3
Stop Kafka 2 Brokers
Stop all Kafka 2 brokers via Ambari.
Install Kafka 3
From Ambari, add the Kafka 3 service and perform the following configurations before starting brokers:
Mandatory Notes:
The upgrade must be performed in ZooKeeper mode.
Ensure Kafka 3 uses the same log directory as Kafka 2.
Ensure ZooKeeper quorum configuration matches Kafka 2.
Update Configuration in Ambari
Under Advanced kafka3-broker, configure the following:
Configuration | Value / Action |
|---|---|
log.dirs | Same as Kafka 2’s data log directory |
zookeeper.connect | Same quorum as Kafka 2 (Kafka 3 defaults to |
All the required configs under | This will be similar to Kafka 2. |
5. Validate Post-Upgrade Functionality
After starting all Kafka 3 brokers:
Verify Topics and Data
Try consuming the earlier created topic:
Expected: You should be able to consume messages produced before the upgrade.
6. Finalize the Upgrade
Once the Kafka 3 cluster is verified to be stable:
Update
inter.broker.protocol.versionunder Custom kafka3-broker:
Restart brokers one by one to apply the new protocol version.
After this step, downgrading to an older Kafka version is not supported.
7. Clean Up
Delete the old Kafka 2 service from Ambari.
Do not reinstall Kafka with default configurations — this may overwrite or corrupt existing data.
8 Rollback (If Required)
If the Kafka 3 upgrade encounters issues, limited rollback options are available. However, rollback feasibility depends on the upgrade stage and whether broker protocol changes were applied.
Rollback Feasibility Matrix
Upgrade Stage | Upgrade Stage | Description |
|---|---|---|
Before updating | ✅ Yes | Rollback requires Kafka 2 binaries and configs identical to the previous setup. |
After updating | ❌ Not Recommended / Unsafe | At this point, data and metadata formats are upgraded. Downgrading to Kafka 2.x may result in topic corruption or broker startup failure. |
Safe Rollback Procedure (Before Protocol Bump)
If rollback is still feasible (i.e., protocol version not yet updated):
Stop all Kafka 3 brokers via Ambari.
Remove Kafka 3 service from Ambari (do not delete data directories).
Reinstall Kafka 2 MPack and service using Ambari.
Ensure
log.dirsandzookeeper.connectpoint to the same values as before.Start Kafka 2 brokers and validate cluster health by listing and consuming topics.
Verification: You should be able to consume previously stored messages.
When Rollback is Not Possible
Rollback is not supported once
The Kafka3 cluster has run with a newer
inter.broker.protocol.version.Any log compaction or retention cleanup occurred after the upgrade.
At this stage, the data format has changed, and Kafka 2.x brokers cannot interpret Kafka 3 logs safely.
Upgrade Complete
You now have a fully functional Kafka 3 cluster using the existing Kafka 2 data directories and ZooKeeper quorum.