Apache Kafka 4.x rolling upgrade: when to move and which path is supported
A rolling upgrade is supported from each of the last three releases to the latest version, according to the Kafka time-based release plan. If your KRaft cluster runs an older 4.x release and needs to move forward, the supported path is a broker-by-broker rollout to the newest release, provided your current release is within that window. Check the current release on the Apache Kafka downloads page, which lists 4.3.1, 4.2.2 and 4.1.2 as supported at the time of writing. Confirm the list again on the day you plan, because the project updates it as new releases ship. If your release falls outside the window, plan an intermediate hop first rather than attempting a direct move.
Staying current matters because supported releases are the only ones that receive bugfix releases, and the project aims for three releases a year, one every four months. A cluster that drifts behind the window stops receiving fixes and eventually loses the rolling upgrade path itself, which turns a routine change into a multi-step project. Put the upgrade on the same planning cycle as your other platform work, and record the release you run, the release you target and the date of your last upgrade in your operations runbook. This page covers the upgrade between 4.x releases only. The ZooKeeper to KRaft migration is a separate process with its own prerequisites, and it is covered in the sibling pages for the 3.9 to 4.0 jump and for older clusters.
What changes between 4.x releases and what you must do
This table lists the platform-level changes that affect a 4.x rolling upgrade, with the impact of each and the action to take before or during the rollout. Read it as a pre-upgrade checklist: any row that touches your brokers, Connect workers, tools or client fleet needs an owner and a check before the first broker restarts. Per-release changes beyond the rows shown should be confirmed against the Kafka 4.3 upgrade notes rather than inferred from this list.
| Change | Impact on the cluster | Action to take |
|---|---|---|
| KRaft-only operation since 4.0 | ZooKeeper mode is removed, so any cluster still on ZooKeeper cannot move to 4.x directly and must migrate to KRaft first. | Confirm the cluster runs KRaft before planning the upgrade. Route ZooKeeper-based clusters to the separate migration path. |
| Pre-KRaft version floor | The upgrade notes recommend that KRaft clusters older than 3.3.x first move to 3.9.x before moving to 4.x. | Record the current broker version. If it is older than 3.3.x, plan a stepping upgrade to 3.9.x before any 4.x broker is started. |
| Java 17 for brokers, Connect and tools | Brokers, Kafka Connect workers and command-line tools need Java 17 from 4.0 onward. Older JVMs will not run the new release. | Inventory the JVM on every broker, controller, Connect worker and admin host. Install Java 17 on each host before its rolling restart. |
| Java 11 minimum for clients and Streams | Clients and Kafka Streams applications need at least Java 11, so older Java runtimes in application fleets will block adoption. | List every client application and its runtime. Schedule runtime upgrades for applications that run Java 8 or other unsupported versions. |
| Supported release list | The downloads page lists 4.3.1, 4.2.2 and 4.1.2 as supported. Archived versions receive no fixes, and the time-based release plan supports rolling upgrades from each of the last three releases to the latest. | Choose a target from the supported list. If the current version is outside the rolling upgrade window, plan an intermediate hop before the target. |
| Patch and minor release cadence | The project releases roughly three feature releases a year and issues bugfix releases for supported lines only. Each new target changes the set of supported starting points. | Set a schedule to review the supported list each release cycle. Confirm the upgrade path against the release plan before each planned move. |
| Per-release configuration and feature changes | Defaults, removed settings and metadata feature levels can differ between 4.x releases, and this table does not list every one. | Read the upgrade notes for each release in your path, then check your broker and client configuration files against them before the rollout. |
What to inventory and back up before the first broker restarts
A rolling upgrade is only reversible within limits, so the work before the first restart decides what you can recover. Each card below is a item your team must verify in its own environment and record before any broker is touched.
Current version and listener inventory
Record the exact broker version on every node, the controller roles, and each listener with its protocol and advertised address. Mixed or unexpected versions across nodes change the rollout order, so confirm them from the running cluster rather than from deployment files. Check which listeners are plaintext, SSL or SASL, because listener changes made during the upgrade are easy to lose. Keep the inventory with the change record.
JVM and OS baseline
Confirm that every broker runs Java 17, the minimum for brokers since Kafka 4.0, and that the JVM version, heap settings and garbage collector match what you will run after the upgrade. Record OS versions, file descriptor limits, and disk and network settings on each node. Compare these against the target release notes so a runtime change does not get mistaken for a Kafka regression.
Configuration diff against the target release
Export the effective broker configuration from each node and diff it against the target release's configuration reference. Flag deprecated or removed keys, defaults that changed, and any dynamic settings stored in the cluster metadata that will persist across restarts. Note each difference and its owner, because a config that works on the old version can fail to start on the new one.
Client version inventory
List every producer, consumer, Kafka Streams application and Connect worker with its client library and version, including non-Java clients such as librdkafka-based services. Identify which clients fall outside the supported upgrade window and which will be affected by the Java 11 minimum for clients. Assign an owner to each application so compatibility testing and sign-off happen before brokers move.
ACL and SCRAM credential export
Export the ACLs and SCRAM credentials stored in the cluster metadata, and store the export in a controlled location. In KRaft clusters, ACLs live in the metadata log, and resources without ACLs are limited to super users unless allow.everyone.if.no.acl.found is set, so a missing or partial export can lock clients out after a restart. Compare the export with a live listing after the upgrade to confirm nothing was dropped.
Tested backup and restore path
Back up topic data and cluster metadata using a method you have restored in a test environment. Confirm where metadata snapshots are kept, how long they are retained, and how a full cluster restore would be run. Record the recovery time you observe in testing rather than assuming one. Treat this as the only path that can undo a failed finalization, since a rollback to the old version has limits once the metadata version changes.
Which upgrade paths Kafka supports and when to take a bridge hop
Rolling upgrades are supported from each of the last three Kafka releases to the latest version, so the first decision is whether your current cluster sits inside that window. The Kafka time-based release plan defines the supported set, and the downloads page lists 4.3.1, 4.2.2 and 4.1.2 as the currently supported releases. Check the running version on every broker and controller, not only the version in your deployment manifest, because partially upgraded clusters are common after an interrupted change. Before you schedule anything, confirm the exact path for your target version against the time-based release plan, since the window moves each time a new release ships.
If your KRaft cluster is older than 3.3.x, the upgrade notes recommend moving to 3.9.x first and then to 4.x. Treat 3.9.x as a bridge release: plan a separate rolling upgrade for that hop, with its own rollback point and client checks, rather than combining two version jumps into one change window. Clusters on 3.3.x or later can usually go directly to a supported 4.x release, but confirm the starting version and any release-specific notes in the Kafka 4.3 upgrade notes before you commit to a direct path.
A cluster still running in ZooKeeper mode is outside this page. Since Kafka 4.0 supports only KRaft and ZooKeeper mode has been removed, that cluster must complete the ZooKeeper to KRaft migration before any 4.x upgrade. Treat that migration as a separate project with its own plan, validation and rollback decisions, and do not start a 4.x rolling upgrade on a cluster that has not finished it. Record the outcome of this path check in your change request so approvers can see which path was chosen and why.
The broker-by-broker upgrade sequence with checks and rollback points
This sequence moves a KRaft cluster from one supported 4.x release to a newer one in a controlled order, with a health check at each step. Each step names the last point where you can still return to the previous release, so the team knows when a rollback is simple and when it is limited.
Upgrade a test cluster first
Your team upgrades a non-production cluster that mirrors production topic settings, client mix and Connect setup, using the same rolling order planned for production. Before starting, confirm that your current release is on the rolling upgrade path listed in the Kafka release plan, that brokers and Connect workers run Java 17, and that any cluster older than 3.3.x has moved to 3.9.x. Done means the test cluster has run the target release under representative load with no unexpected errors in broker logs, and the team has written down the exact commands and config changes for production. Rollback point: the test cluster can be rebuilt on its previous version at any time, so this is the cheapest place to find problems.
Roll the KRaft controllers one at a time
Restart each controller on the target release, one node at a time, with the non-active controllers first and the active controller last. After each restart, check that the node rejoins the quorum and catches up on the metadata log before you move to the next node. Leave the metadata version at its current level during this step, because it is raised only in the finalizing step. Done means every controller reports the target binary version, a quorum leader is present, and the logs show no repeated elections or persistent lag. Rollback point: while the metadata version is unchanged, a controller can be returned to the previous release, which is the last safe point to reverse this step.
Roll brokers one at a time
Stop one broker, replace its binaries with the target release, start it, and wait until it rejoins the cluster and its partitions catch up before you touch the next broker. Watch the cluster-wide under-replicated partition count, not only the broker you restarted, and hold the rollout while the count is above the level you recorded before the upgrade began. At each pause, also check producer error rates and consumer lag. Done means every broker runs the target release, under-replicated partitions are back at baseline, and each restart is signed off in the change record. Rollback point: a broker can still return to the previous release while the metadata version is unchanged, so pause the rollout and reverse the last broker if a check fails.
Verify clients and Connect workers
Confirm that producers, consumers, Kafka Streams applications and Kafka Connect workers work against the upgraded brokers, starting with the client versions you inventoried before the upgrade. Clients and Streams applications need Java 11 or later, and Connect workers need Java 17, so check those runtimes first. Test each connector plugin on the new release before its worker is rolled. Done means each critical application completes a test run against the upgraded cluster, all Connect tasks are running without failed states, and error rates and throughput match the baseline. Rollback point: client changes are reversed by redeploying the previous application build, and the cluster stays rollback-capable until you finalize.
Finalize the metadata version with kafka-features
After every broker and controller runs the target release and the verification checks pass, run kafka-features to raise the metadata version to the target release. Start with the describe subcommand to record the current feature levels, and read the upgrade notes for the target release to see which features finalizing enables. Finalizing commits the upgrade, so schedule it when the team can watch the cluster afterward. Done means the describe output shows the target metadata version on every feature, and a test workload uses the newly enabled features without errors. Rollback point: before this command, the previous release remains a valid rollback target. After it, rollback is limited to the features the release documents as downgradable, so treat this command as the point of no return unless the notes say otherwise.
Close the change and record the rollback limits
Keep the previous release binaries and configuration available until the change record shows the rollback window is closed. Monitor under-replicated partitions, consumer lag and client error rates after finalizing, and compare them with the pre-upgrade baseline. Record the versions of each controller, broker and Connect worker, the finalized metadata version, the results of each check and any features that cannot be downgraded. Done means the change record is complete, the monitoring has returned to baseline, and the team has confirmed the downgrade limits in writing so that operations staff know what a later rollback would cost.
Where rollback stops working after finalization
Binary rollback to the previous 4.x release is only possible until the metadata version is finalized. Before you run kafka-features with the upgrade option, a broker can be moved back to the earlier release by replacing the binaries in the same broker-by-broker sequence used for the upgrade. Once the metadata version is finalized, that simple path closes, because the cluster may have started writing metadata and enabling features that the older release does not understand. The rollback window is therefore the period between the last broker running the new binaries and the finalization step, and it should be planned as a deliberate decision rather than an afterthought.
After finalization, only the features that the release marks as downgradable can be reverted, and the set differs by feature and by release. The feature-level details, including how each downgrade is run with kafka-features and what state it leaves behind, are covered on the finalizing and downgrading page. Your rollback plan should not assume that a finalized cluster can return to the earlier release in full. Confirm the downgrade rules for your exact source and target versions in the Apache Kafka 4.3 upgrade notes before you set the window, and record which features in use would block a downgrade. Also confirm the rules for the release line you are leaving, since the notes for that release apply to the starting point of your upgrade.
How to test the upgrade in a staging cluster before production
The platform team owns proof that the cluster itself behaves correctly while brokers and controllers restart one at a time. Run the staging rollout with the same order, batch size and health gates you plan to use in production, because a rehearsal that skips steps proves little. Staging should match production in broker count, controller layout, replication factor and disk pressure as closely as your environment allows. The goal is to show that leadership moves cleanly, under-replicated partitions recover between restarts, and the controller quorum keeps a leader throughout.
- Rolling restarts: Restart one broker at a time and wait for it to rejoin the in-sync replica sets before continuing. Record the time each broker took to return and any restarts that needed intervention.
- Controller quorum health: Confirm with
kafka-metadata-quorumthat a leader exists and that voters are caught up before and after each controller restart. - Replication: Watch under-replicated and offline partition counts during each step. Any partition that stays under-replicated after the rejoin needs investigation before production.
- Metadata version: Before finalizing, confirm the metadata version and feature levels with
kafka-featureson the staging cluster, then run the finalization step as a deliberate, recorded action.
Keep the broker-by-broker log, metric snapshots, and the exact commands run, so the production change record can reference a tested sequence.
Check that every broker and controller reports a healthy state and the same metadata version before you sign off the staging run.
Application owners need to show that their producers, consumers, Streams applications and Connect workers keep working against the upgraded brokers. Cluster health alone does not prove a client is fine, since a client can keep connecting while it silently fails to commit offsets or retries forever. Run representative workloads through staging, including the client versions actually deployed, not just the versions the team intended to deploy. Include failure cases such as a broker restart in the middle of a produce burst.
- Producer behavior: Compare send error rates, retries, and acknowledgment latency before and during the rolling restart. Confirm idempotent or transactional producers recover after a leader change.
- Consumer behavior: Verify consumer groups rebalance, resume from committed offsets, and do not show growing lag once brokers return.
- Kafka Streams: Run each application through at least one restart cycle and confirm state stores restore and processing resumes without duplicate or lost output.
- Kafka Connect: Check that source and sink tasks stay running, that offsets advance, and that connector plugins load on the Java runtime you plan to use.
- Client inventory: Record the client library and framework versions tested against each workload, so gaps are visible.
Save consumer lag graphs, error logs, and a signed list of tested applications with their versions as evidence.
Confirm every tested application reaches a steady state after the last broker restart before production approval.
The security team verifies that the upgrade did not change who can connect, how traffic is protected, or what each principal may do. Restarts reload configuration, so a listener, certificate chain, or SASL setting that was valid before the upgrade can behave differently after it. Test these controls from the outside, using the same clients and identities that production uses, and do not rely only on the broker reporting that it started. Keep the results in a form an auditor can read later.
- Listeners: Confirm each advertised listener accepts connections on the expected port and that no unintended plaintext listener appeared after restart.
- TLS: Check that certificates are presented correctly, are not expired, and chain to the trust store clients use. Confirm that an unsecured connection is refused where TLS is required.
- SASL authentication: Test each enabled mechanism, such as SCRAM-SHA-256 or OAUTHBEARER, with a real client identity after every restart.
- ACLs after restart: Run a set of allowed and denied operations per principal. Remember that the StandardAuthorizer stores ACLs in the metadata log, and that resources without ACLs are restricted to super users unless
allow.everyone.if.no.acl.foundis set to true. Confirm that setting is what you intended. - Audit logs: Check that authentication and authorization decisions are still logged where your monitoring expects them.
Keep the test scripts, their output, and the list of principals and expected results in the change record.
Confirm each denied operation still fails and each allowed operation still succeeds, since a clean startup does not prove access control is intact.
What makes a Kafka 4.x upgrade take longer
This table lists the factors that stretch a rolling upgrade between 4.x releases and what to check for each one. Read it before scoping, so the plan accounts for your cluster's size, client mix and surrounding tooling rather than assuming a single broker-by-broker pass.
| Driver | Why it adds effort | What to check |
|---|---|---|
| Number of brokers and controllers | Each broker restarts in turn, and every restart needs health checks before the next one begins. Controllers form the metadata quorum, so their restart order and quorum health need extra care. | Count brokers and controllers, confirm whether controllers are combined or dedicated, and confirm the quorum has a healthy leader before each step. |
| Size of replicated data | Larger partitions and replica sets take longer to catch up after each restart, which lengthens the wait between steps. | Measure under-replicated partitions and catch-up time on a staging copy, and confirm producers tolerate the chosen acknowledgment settings during restarts. |
| Client and Connect applications on older libraries | Clients and Connect workers on old libraries may need their own upgrades before or during the rollout, and each one has its own test cycle. | Inventory client libraries and versions, check Java 11 or 17 requirements, and confirm which applications must move before the brokers. |
| Custom authorizers or plugins | Custom authorizers, interceptors or Connect plugins may depend on APIs or behavior that changed, and they need tests against the new release. | List every custom component, its source and its owner, and confirm each has a build or test for the target 4.x release. |
| Strimzi or other operators managing the cluster | An operator controls restarts and version changes, so the operator version, the Kafka version in the custom resource and the Kubernetes version must be sequenced together. | Check the operator's supported Kafka versions, plan the operator upgrade before Kafka, and confirm who runs each step. |
| Multi-site replication via MirrorMaker 2 | Replication flows between clusters must keep working through the upgrade, and each cluster in a pair or topology may sit at a different version. | Map every replication flow, confirm the MirrorMaker 2 version supports both ends, and decide the order in which sites are upgraded. |
Questions teams ask before upgrading Kafka 4.x
What does a Kafka 4.x rolling upgrade cost?
The cost is mostly the labor to plan, rehearse and run the upgrade, and it is largely one-time for a given move. Software is not the cost driver because Apache Kafka is licensed under the Apache License 2.0 and the project offers no paid edition. The main cost drivers are the number of clusters, the number of brokers and controllers, how many client applications and Kafka Connect or Kafka Streams deployments must be checked, the state of your monitoring and backups, and whether change windows are restricted. Ask for a written, fixed scope that lists each cluster, each client group, the test environments to build and the evidence you will receive at the end. That scope is what turns these drivers into a quote.
How long does a rolling upgrade between 4.x releases take?
Duration depends on cluster size, the number of environments that must be upgraded in sequence, how many client applications need checks, and how quickly your change approvals move. Brokers are restarted one at a time, so the rollout time grows with broker count and with the time needed to confirm each broker is healthy before moving to the next. Test runs, rollback rehearsal and the finalization decision add further steps. Ask for a timeline in the written scope that shows each stage and the approval gates, rather than a single overall number.
What does the internal team need to provide?
The internal team should provide access, decisions and context. Typical needs include an inventory of clusters, brokers, controllers and their hosting, access to change windows, the Kafka configuration files, the list of client applications with their library versions, monitoring and alert access, and a named owner who can approve finalization. Engineers who run the platform should also be available for review of the rollout plan and for checks during each broker restart. Confirm these needs in the scope so that delays caused by missing access are visible early.
Can our team run the upgrade without outside help?
Yes, a team with Kafka operations experience can run a rolling upgrade on its own, and the official upgrade notes give the steps. The questions to answer honestly are whether someone on the team has done a KRaft rolling restart before, whether you have tested rollback in a non-production environment, and whether you have the client inventory needed to avoid surprises. If the answer is no to any of these, a partner can build the test plan, run the rehearsal and document the evidence while your team keeps ownership of production. Confirm the division of work in writing before the project starts.
Can a 4.1 cluster upgrade directly to 4.3?
Rolling upgrades are supported from each release in the past year, which is the last three releases, to the latest version, according to the Kafka time-based release plan. Upgrading from 4.1 to 4.3 is therefore within the documented path, but confirm it against the release notes for every version you pass through and the upgrade notes for 4.3. Check the 4.1 patch level you run as well, because the supported releases listed by the project are 4.3.1, 4.2.2 and 4.1.2. Start with the current release notes before setting a plan.
Do clients have to upgrade before the brokers?
Clients do not always need to be upgraded first, but they must be compatible with the broker version you run. The most reliable approach is to inventory every producer, consumer, Kafka Streams application and Kafka Connect worker and check each client library version against the 4.3 upgrade notes before the broker rollout begins. Kafka Streams and Connect have their own upgrade requirements, and clients must run on Java 11 or later. Ask the partner for a client compatibility review as a separate line in the scope, because a client problem found during the rollout is the most common reason for a delay.
How does rollback work after the metadata version is finalized?
Before finalization, you can roll brokers back to the previous release, because the cluster has not yet enabled features that the old release cannot read. After finalization with the kafka-features tool, rollback is limited: some features cannot be downgraded, so returning to the earlier release may not be possible without restoring from backup or rebuilding the cluster. The exact limits depend on which features the finalized version enables, so check the upgrade notes and plan the finalization window accordingly. Ask for a written rollback plan that states the point of no return, the backup method and the test that proves restore works.
Official Kafka sources for the upgrade plan
Start with the downloads page, because it sets which releases are supported today. The page lists 4.3.1, 4.2.2 and 4.1.2 as supported, and everything older is archived. Confirm the target version against that page on the day you plan, since bugfix releases are issued as needed. Next, read the Time Based Release Plan, which states that rolling upgrades are supported from each of the last three releases to the latest version. If your current broker is older than that window, the rolling path in this guide does not apply to you, and you will need an intermediate hop first.
Then read the Kafka 4.3 upgrade notes line by line against your target version, not only the summary. The notes cover behavior changes, configuration defaults, removed options and the steps that apply to brokers, controllers and clients. Build a short written list of every note that touches your cluster, your client libraries or your tooling, and assign an owner to each. Your own list is the input to the broker rollout and the client inventory, so keep it with the change record.
Finally, read the security overview and the geo-replication documentation for the 4.3 line. The security overview explains how listeners, SASL mechanisms and authorization interact, so you can check that listener configuration and ACL behavior survive a mixed-version period. The geo-replication guide matters if MirrorMaker 2 runs between sites, because the mirror and the clusters it connects to must be included in the rollout order. Note the version each document describes, and confirm any behavior you depend on against your target release.
How DeployOpen scopes, delivers and supports a Kafka upgrade
DeployOpen plans a Kafka 4.x rolling upgrade as a written, fixed-scope engagement inside your own infrastructure. The work covers version inventory, a broker-by-broker rollout, the metadata version finalization step, client compatibility checks and the documentation your operators need afterwards.
How we scope
- Inventory current Kafka versions, cluster modes, controllers, brokers and clients before agreeing any upgrade path.
- Confirm the start and target releases against the supported upgrade paths in the Kafka time-based release plan.
- Agree in writing which clusters, Connect workers, Streams applications and tools are in the upgrade and which are excluded.
How we build
- Write a rollout runbook with ordered broker restarts, health gates between nodes and named owners for each step.
- Rehearse the upgrade in a non-production cluster that matches your topology, listeners and security configuration.
- Hold the kafka-features finalization step as a separate, approved change with a documented rollback window.
How we hand over
- Deliver the runbook, rollback limits, client compatibility findings and test results as written deliverables.
- Walk your platform and operations team through checks for under-replicated partitions, controller health and client lag.
- Record open risks and the decisions your team owns, so the next upgrade starts from a documented baseline.
How we support
- Ongoing support, upgrades for later 4.x releases and continuous testing are available as retainers.
- Retainers cover planning for the next supported release, after the release notes have been reviewed by your team.
- Ask any provider to confirm which security testing, patch review and on-call hours are included in the retainer.
