KAFKA-19184; Add documentation for upgrading the kraft version #20071

jsancio · 2025-06-30T16:20:00Z

Update the documentation to describe how to upgrade the kraft feature
version from 0 to 1.

Reviewers: Mickael Maison [email protected], Alyssa Huang
[email protected]

ahuang98

looks good overall, just left a few nits

ahuang98 · 2025-06-30T18:27:42Z

docs/ops.html

@@ -3948,6 +3948,40 @@ <h4 class="anchor-heading"><a id="others_monitoring" class="anchor-link"></a><a

  <h3 class="anchor-heading"><a id="kraft" class="anchor-link"></a><a href="#kraft">6.8 KRaft</a></h3>

+  <h4 class="anchor-heading"><a id="kraft_upgrade" class="anchor-link"></a><a href="#kraft_upgrade">Upgrade</a></h4>
+
+  Apache Kafka 4.1 added support for upgrading cluster from a static controller configuration to a dynamic controller configuration. This feature upgrade is done by upgrading the kraft feature version and updating the nodes configuration.


nits:
upgrading cluster -> upgrading a cluster

updating the nodes -> updating the nodes'

ahuang98 · 2025-06-30T18:30:33Z

docs/ops.html

+
+  <h5 class="anchor-heading"><a id="kraft_upgrade_describe" class="anchor-link"></a><a href="#kraft_upgrade_describe">Describe KRaft Version</a></h5>
+
+  <p>Dynamic controller cluster was added in <code>kraft.version=1</code> or <code>release-version 4.1</code>. To determine which kraft feature version the cluster is using you can execute the following CLI command:</p>


nit: in case it's not self-explanatory, should we got into a bit of detail on what dynamic controller configuration means?

ahuang98 · 2025-06-30T18:34:24Z

docs/ops.html

+
+  <p>KRaft version 1 deprecated the <code>controller.quorum.voters</code> property and added the <code>controller.quorum.bootstrap.servers</code> property. After checking that the kraft version has been successfully upgrade to at least version <code>1</code>. Remove the <code>controller.quorum.voters</code> property and add the <code>controller.quorum.bootstrap.servers</code> to all of the nodes (controllers and brokers) in the cluster.</p>
+
+  <pre><code class="language-bash">process.roles=...


will it be confusing that we mention these configurations before the Configuration section of the docs? have you considered moving this new section below the Configuration section?

Yeah I wonder if putting this in , or near, the existing Controller membership changes section would make more sense.

I am not sure. Let me see what I can do. I wanted to document the steps needed to upgrade the KRaft feature version without the user having to jump/read other sections.

It is interesting that you both suggest different sections.

I think we can solve this issue by moving the configuration section first. Above the upgrade the section. The upgrade section can repeat this information by saying that they need to remove controller.quorum.voters and added controller.quorum.bootstrap.servers.

Let me make that change and you can tell me what you think.

mimaison

Thanks for the PR! I left a few suggestions.

mimaison · 2025-07-01T13:07:50Z

docs/ops.html

@@ -3948,6 +3948,40 @@ <h4 class="anchor-heading"><a id="others_monitoring" class="anchor-link"></a><a

  <h3 class="anchor-heading"><a id="kraft" class="anchor-link"></a><a href="#kraft">6.8 KRaft</a></h3>

+  <h4 class="anchor-heading"><a id="kraft_upgrade" class="anchor-link"></a><a href="#kraft_upgrade">Upgrade</a></h4>
+
+  Apache Kafka 4.1 added support for upgrading cluster from a static controller configuration to a dynamic controller configuration. This feature upgrade is done by upgrading the kraft feature version and updating the nodes configuration.


kraft -> KRaft
Same below

mimaison · 2025-07-01T13:11:23Z

docs/ops.html

+
+  <h5 class="anchor-heading"><a id="kraft_upgrade_config" class="anchor-link"></a><a href="#kraft_upgrade_config">Update KRaft Config</a></h5>
+
+  <p>KRaft version 1 deprecated the <code>controller.quorum.voters</code> property and added the <code>controller.quorum.bootstrap.servers</code> property. After checking that the kraft version has been successfully upgrade to at least version <code>1</code>. Remove the <code>controller.quorum.voters</code> property and add the <code>controller.quorum.bootstrap.servers</code> to all of the nodes (controllers and brokers) in the cluster.</p>


upgrade -> upgraded

mimaison · 2025-07-01T13:14:12Z

docs/ops.html

+
+  <p>KRaft version 1 deprecated the <code>controller.quorum.voters</code> property and added the <code>controller.quorum.bootstrap.servers</code> property. After checking that the kraft version has been successfully upgrade to at least version <code>1</code>. Remove the <code>controller.quorum.voters</code> property and add the <code>controller.quorum.bootstrap.servers</code> to all of the nodes (controllers and brokers) in the cluster.</p>
+
+  <pre><code class="language-bash">process.roles=...


Yeah I wonder if putting this in , or near, the existing Controller membership changes section would make more sense.

mimaison · 2025-07-01T13:15:59Z

docs/toc.html

                        <li><a href="#kraft_config">Configuration</a>
-                        <li><a href="#kraft_storage">Storage Tool</a>
+                        <li><a href="#kraft_nodes">Provisioning Nodes</a>


Should we also add Controller membership changes?

Yes. I missed that. Done.

mimaison · 2025-07-01T13:16:28Z

docs/ops.html

+Feature: kraft.version  SupportedMinVersion: 0  SupportedMaxVersion: 1  FinalizedVersionLevel: 0        Epoch: 7
+Feature: metadata.version       SupportedMinVersion: 3.3-IV3    SupportedMaxVersion: 4.0-IV3    FinalizedVersionLevel: 4.0-IV3  Epoch: 7</code></pre>
+
+  <p>If the <code>FinalizedVersionLevel</code> for <code>Feature: kraft.version</code> is <code>0</code>, the version need to be upgraded to at least <code>1</code> to support a dynamic controller cluster.</p>


need -> needs

mimaison

LGTM

Update the documentation to describe how to upgrade the kraft feature version from 0 to 1. Reviewers: Mickael Maison <[email protected]>, Alyssa Huang <[email protected]>

mimaison · 2025-07-09T09:23:41Z

Applied to 4.1 too: b0ff9ba

KAFKA-19184; Add documentation for upgrading the kraft version

485f0bb

github-actions bot added docs small Small PRs labels Jun 30, 2025

ahuang98 approved these changes Jun 30, 2025

View reviewed changes

mimaison reviewed Jul 1, 2025

View reviewed changes

KAFKA-19184; Fix documentation

3638096

mimaison approved these changes Jul 9, 2025

View reviewed changes

mimaison merged commit e42e01e into apache:trunk Jul 9, 2025
28 checks passed

jsancio deleted the kafka-19184-kraft-upgrade-doc branch July 9, 2025 13:34


		<h5 class="anchor-heading"><a id="kraft_upgrade_describe" class="anchor-link"></a><a href="#kraft_upgrade_describe">Describe KRaft Version</a></h5>

		<p>Dynamic controller cluster was added in <code>kraft.version=1</code> or <code>release-version 4.1</code>. To determine which kraft feature version the cluster is using you can execute the following CLI command:</p>


		<p>KRaft version 1 deprecated the <code>controller.quorum.voters</code> property and added the <code>controller.quorum.bootstrap.servers</code> property. After checking that the kraft version has been successfully upgrade to at least version <code>1</code>. Remove the <code>controller.quorum.voters</code> property and add the <code>controller.quorum.bootstrap.servers</code> to all of the nodes (controllers and brokers) in the cluster.</p>

		<pre><code class="language-bash">process.roles=...

KAFKA-19184; Add documentation for upgrading the kraft version #20071

KAFKA-19184; Add documentation for upgrading the kraft version #20071

Uh oh!

Conversation

jsancio commented Jun 30, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ahuang98 left a comment

Choose a reason for hiding this comment

Uh oh!

ahuang98 Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsancio Jul 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mimaison left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mimaison left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mimaison commented Jul 9, 2025

Uh oh!

Uh oh!

jsancio commented Jun 30, 2025 •

edited by github-actions bot

Loading

ahuang98 Jun 30, 2025 •

edited

Loading

jsancio Jul 8, 2025 •

edited

Loading