[
https://issues.apache.org/jira/browse/KAFKA-7481?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16677334#comment-16677334
]
ASF GitHub Bot commented on KAFKA-7481:
---------------------------------------
lindong28 closed pull request #5857: KAFKA-7481; Add upgrade/downgrade notes
for 2.1.x
URL: https://github.com/apache/kafka/pull/5857
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/upgrade.html b/docs/upgrade.html
index 41e2277bb24..33d9964113a 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -20,6 +20,47 @@
<script id="upgrade-template" type="text/x-handlebars-template">
<h4><a id="upgrade_2_1_0" href="#upgrade_2_1_0">Upgrading from 0.8.x, 0.9.x,
0.10.0.x, 0.10.1.x, 0.10.2.x, 0.11.0.x, 1.0.x, 1.1.x, or 2.0.0 to 2.1.0</a></h4>
+
+<p><b>Note that 2.1.x contains a change to the internal schema used to store
consumer offsets. Once the upgrade is
+ complete, it will not be possible to downgrade to previous versions. See the
rolling upgrade notes below for more detail.</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.
0.8.2, 0.9.0, 0.10.0, 0.10.1, 0.10.2, 0.11.0, 1.0, 1.1).</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 0.11.0.x, 1.0.x, 1.1.x, or 2.0.x 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 (0.11.0,
1.0, 1.1, 2.0).</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 2.1.
+ </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 2.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>
+
<p><b>Additional Upgrade Notes:</b></p>
<ol>
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
> Consider options for safer upgrade of offset commit value schema
> ----------------------------------------------------------------
>
> Key: KAFKA-7481
> URL: https://issues.apache.org/jira/browse/KAFKA-7481
> Project: Kafka
> Issue Type: Bug
> Reporter: Jason Gustafson
> Assignee: Jason Gustafson
> Priority: Blocker
> Fix For: 2.1.0
>
>
> KIP-211 and KIP-320 add new versions of the offset commit value schema. The
> use of the new schema version is controlled by the
> `inter.broker.protocol.version` configuration. Once the new inter-broker
> version is in use, it is not possible to downgrade since the older brokers
> will not be able to parse the new schema.
> The options at the moment are the following:
> 1. Do nothing. Users can try the new version and keep
> `inter.broker.protocol.version` locked to the old release. Downgrade will
> still be possible, but users will not be able to test new capabilities which
> depend on inter-broker protocol changes.
> 2. Instead of using `inter.broker.protocol.version`, we could use
> `message.format.version`. This would basically extend the use of this config
> to apply to all persistent formats. The advantage is that it allows users to
> upgrade the broker and begin using the new inter-broker protocol while still
> allowing downgrade. But features which depend on the persistent format could
> not be tested.
> Any other options?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
