You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kafka.apache.org by ab...@apache.org on 2022/12/31 03:57:13 UTC
[kafka] branch trunk updated: [MINOR] Update upgrade documentation for 3.4 (#13061)
This is an automated email from the ASF dual-hosted git repository.
ableegoldman pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 07085f3f1bc [MINOR] Update upgrade documentation for 3.4 (#13061)
07085f3f1bc is described below
commit 07085f3f1bc77a1ffc351ed9d1295672a8f4ebed
Author: A. Sophie Blee-Goldman <so...@confluent.io>
AuthorDate: Fri Dec 30 19:57:05 2022 -0800
[MINOR] Update upgrade documentation for 3.4 (#13061)
Reviewers: Anna Sophie Blee-Goldman <ab...@apache.org>
---
docs/documentation.html | 3 ++-
docs/upgrade.html | 42 ++++++++++++++++++++++++++++++++++++++++++
2 files changed, 44 insertions(+), 1 deletion(-)
diff --git a/docs/documentation.html b/docs/documentation.html
index 0abbae87181..3589c4461fc 100644
--- a/docs/documentation.html
+++ b/docs/documentation.html
@@ -33,7 +33,7 @@
<!--//#include virtual="../includes/_docs_banner.htm" -->
<h1>Documentation</h1>
- <h3>Kafka 3.3 Documentation</h3>
+ <h3>Kafka 3.4 Documentation</h3>
Prior releases: <a href="/07/documentation.html">0.7.x</a>,
<a href="/08/documentation.html">0.8.0</a>,
<a href="/081/documentation.html">0.8.1.X</a>,
@@ -57,6 +57,7 @@
<a href="/30/documentation.html">3.0.X</a>.
<a href="/31/documentation.html">3.1.X</a>.
<a href="/32/documentation.html">3.2.X</a>.
+ <a href="/33/documentation.html">3.3.X</a>.
<h2 class="anchor-heading"><a id="gettingStarted" class="anchor-link"></a><a href="#gettingStarted">1. Getting Started</a></h2>
<h3 class="anchor-heading"><a id="introduction" class="anchor-link"></a><a href="#introduction">1.1 Introduction</a></h3>
diff --git a/docs/upgrade.html b/docs/upgrade.html
index 1ea6be319e3..61d181a01d4 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -19,6 +19,48 @@
<script id="upgrade-template" type="text/x-handlebars-template">
+ <h4><a id="upgrade_3_4_0" href="#upgrade_3_4_0">Upgrading to 3.4.0 from any version 0.8.x through 3.3.x</a></h4>
+
+ <p><b>If you are upgrading from a version prior to 2.1.x, please see the note below about the change to the schema used to store consumer offsets.
+ Once you have changed the inter.broker.protocol.version to the latest version, it will not be possible to downgrade to a version prior to 2.1.</b></p>
+
+ <p><b>For a rolling upgrade:</b></p>
+
+ <ol>
+ <li>Update server.properties on all brokers and add the following properties. CURRENT_KAFKA_VERSION refers to the version you
+ are upgrading from. CURRENT_MESSAGE_FORMAT_VERSION refers to the message format version currently in use. If you have previously
+ overridden the message format version, you should keep its current value. Alternatively, if you are upgrading from a version prior
+ to 0.11.0.x, then CURRENT_MESSAGE_FORMAT_VERSION should be set to match CURRENT_KAFKA_VERSION.
+ <ul>
+ <li>inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g. <code>3.3</code>, <code>3.2</code>, etc.)</li>
+ <li>log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION (See <a href="#upgrade_10_performance_impact">potential performance impact
+ following the upgrade</a> for the details on what this configuration does.)</li>
+ </ul>
+ If you are upgrading from version 0.11.0.x or above, and you have not overridden the message format, then you only need to override
+ the inter-broker protocol version.
+ <ul>
+ <li>inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g. <code>3.3</code>, <code>3.2</code>, etc.)</li>
+ </ul>
+ </li>
+ <li>Upgrade the brokers one at a time: shut down the broker, update the code, and restart it. Once you have done so, the
+ brokers will be running the latest version and you can verify that the cluster's behavior and performance meets expectations.
+ It is still possible to downgrade at this point if there are any problems.
+ </li>
+ <li>Once the cluster's behavior and performance has been verified, bump the protocol version by editing
+ <code>inter.broker.protocol.version</code> and setting it to <code>3.4</code>.
+ </li>
+ <li>Restart the brokers one by one for the new protocol version to take effect. Once the brokers begin using the latest
+ protocol version, it will no longer be possible to downgrade the cluster to an older version.
+ </li>
+ <li>If you have overridden the message format version as instructed above, then you need to do one more rolling restart to
+ upgrade it to its latest version. Once all (or most) consumers have been upgraded to 0.11.0 or later,
+ change log.message.format.version to 3.4 on each broker and restart them one by one. Note that the older Scala clients,
+ which are no longer maintained, do not support the message format introduced in 0.11, so to avoid conversion costs
+ (or to take advantage of <a href="#upgrade_11_exactly_once_semantics">exactly once semantics</a>),
+ the newer Java clients must be used.
+ </li>
+ </ol>
+
<h4><a id="upgrade_3_3_1" href="#upgrade_3_3_1">Upgrading to 3.3.1 from any version 0.8.x through 3.2.x</a></h4>
<p><b>If you are upgrading from a version prior to 2.1.x, please see the note below about the change to the schema used to store consumer offsets.