This is an automated email from the ASF dual-hosted git repository.
dajac pushed a commit to branch 3.1
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/3.1 by this push:
new 271ac42 MINOR: Update doc for 3.1 (#11539)
271ac42 is described below
commit 271ac425fa704a6d4f41b214303145f4b26e217c
Author: David Jacot <[email protected]>
AuthorDate: Fri Dec 3 09:55:33 2021 +0100
MINOR: Update doc for 3.1 (#11539)
* Update main version of main documentation and add link to previous
version;
* Update quick start guide (links do not work yet obviously);
* Add upgrade section.
Reviewers: Luke Chen <[email protected]>, Manikumar Reddy
<[email protected]>
---
docs/documentation.html | 5 +--
docs/quickstart.html | 6 ++--
docs/upgrade.html | 86 +++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 92 insertions(+), 5 deletions(-)
diff --git a/docs/documentation.html b/docs/documentation.html
index 9ca7f41..d13f691 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.0 Documentation</h3>
+ <h3>Kafka 3.1 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>,
@@ -53,7 +53,8 @@
<a href="/25/documentation.html">2.5.X</a>,
<a href="/26/documentation.html">2.6.X</a>,
<a href="/27/documentation.html">2.7.X</a>,
- <a href="/28/documentation.html">2.8.X</a>.
+ <a href="/28/documentation.html">2.8.X</a>,
+ <a href="/30/documentation.html">3.0.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/quickstart.html b/docs/quickstart.html
index eda3ede..7f003c0 100644
--- a/docs/quickstart.html
+++ b/docs/quickstart.html
@@ -28,12 +28,12 @@
</h4>
<p>
- <a
href="https://www.apache.org/dyn/closer.cgi?path=/kafka/2.8.0/kafka_2.13-2.8.0.tgz";>Download</a>
+ <a
href="https://www.apache.org/dyn/closer.cgi?path=/kafka/3.1.0/kafka_2.13-3.1.0.tgz";>Download</a>
the latest Kafka release and extract it:
</p>
- <pre class="line-numbers"><code class="language-bash">$ tar -xzf
kafka_2.13-2.8.0.tgz
-$ cd kafka_2.13-2.8.0</code></pre>
+ <pre class="line-numbers"><code class="language-bash">$ tar -xzf
kafka_2.13-3.1.0.tgz
+$ cd kafka_2.13-3.1.0</code></pre>
</div>
<div class="quickstart-step">
diff --git a/docs/upgrade.html b/docs/upgrade.html
index d61d153..73ebe29 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_1_0" href="#upgrade_3_1_0">Upgrading to 3.1.0 from any
version 0.8.x through 3.0.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.0</code>, <code>2.8</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.0</code>, <code>2.8</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.1</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.1 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>
+
<h5><a id="upgrade_310_notable" href="#upgrade_310_notable">Notable changes in
3.1.0</a></h5>
<ul>
<li>Apache Kafka supports Java 17.</li>
@@ -36,8 +78,52 @@
Those applications will need to go through a bridge release, by first
upgrading to a version between 2.4 - 3.1 and setting the
<code>upgrade.from</code> config,
then removing that config and upgrading to the final version above
3.1. See <a
href="https://issues.apache.org/jira/browse/KAFKA-8575";>KAFKA-8575</a>
for more details.</li>
+ <li>IBP 3.1 introduces topic IDs to FetchRequest as a part of
+ <a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-516%3A+Topic+Identifiers";>KIP-516</a>.</li>
</ul>
+<h4><a id="upgrade_3_0_0" href="#upgrade_3_0_0">Upgrading to 3.0.0 from any
version 0.8.x through 2.8.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>2.8</code>, <code>2.7</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>2.8</code>, <code>2.7</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.0</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.0 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>
+
<h5><a id="upgrade_300_notable" href="#upgrade_300_notable">Notable changes in
3.0.0</a></h5>
<ul>
<li>ZooKeeper has been upgraded to version 3.6.3.</li>
