rolling update considerations in migration guide

akka-docs/rst/java/cluster-sharding.rst

@@ -167,7 +167,7 @@ must be to begin the rebalancing. This strategy can be replaced by an applicatio
 implementation.
 
 The state of shard locations in the ``ShardCoordinator`` is persistent (durable) with
-:ref:`distributed_data-java` or :ref:`persistence-java` to survive failures. When a crashed or 
+:ref:`distributed_data_java` or :ref:`persistence-java` to survive failures. When a crashed or 
 unreachable coordinator node has been removed (via down) from the cluster a new ``ShardCoordinator`` singleton
 actor will take over and the state is recovered. During such a failure period shards
 with known location are still available, while messages for new (unknown) shards

akka-docs/rst/java/remoting-artery.rst

@@ -458,7 +458,7 @@ Akka internals do not rely on Java serialization (exceptions to that being ``jav
 
   One may think that network bandwidth and latency limit the performance of remote messaging, but serialization is a more typical bottleneck.
   
-For user messages, the default serializer, implemented using Java serialization, remains available and enabled in Artery.
+For user messages the default serializer implemented using Java serialization remains available and enabled by default.
 We do however recommend to disable it entirely and utilise a proper serialization library instead in order effectively utilise 
 the improved performance and ability for rolling deployments using Artery. Libraries that we recommend to use include, 
 but are not limited to, `Kryo`_ by using the `akka-kryo-serialization`_ library or `Google Protocol Buffers`_ if you want

akka-docs/rst/java/remoting.rst

@@ -295,7 +295,7 @@ Akka internals do not rely on Java serialization (exceptions to that being ``jav
 
   One may think that network bandwidth and latency limit the performance of remote messaging, but serialization is a more typical bottleneck.
   
-For user messages, the default serializer, implemented using Java serialization, remains available and enabled by default.
+For user messages the default serializer implemented using Java serialization remains available and enabled by default.
 We do however recommend to disable it entirely and utilise a proper serialization library instead in order effectively utilise 
 the improved performance and ability for rolling deployments using Artery. Libraries that we recommend to use include, 
 but are not limited to, `Kryo`_ by using the `akka-kryo-serialization`_ library or `Google Protocol Buffers`_ if you want

akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst

@@ -266,6 +266,8 @@ which explains using and implementing GraphStages in more practical terms than t
 Remote
 ======
 
+.. _mig25_mutual:
+
 Mutual TLS authentication now required by default for netty-based SSL transport
 -------------------------------------------------------------------------------
 
@@ -283,6 +285,8 @@ It is still possible to make a rolling upgrade from a version < 2.4.12 by doing
 For more information see the documentation for the ``akka.remote.netty.ssl.require-mutual-authentication`` configuration setting
 in :ref:`akka-remote's reference.conf <config-akka-remote>`.
 
+.. _mig25_addser:
+
 additional-serialization-bindings
 ---------------------------------
 
@@ -305,9 +309,37 @@ it is possible to disable the additional serializers and continue using Java ser
 Please note that this setting must be the same on all nodes participating in a cluster, otherwise 
 the mis-aligned serialization configurations will cause deserialization errors on the receiving nodes.
 
+Wire Protocol Compatibility
+---------------------------
+
+It is possible to use Akka Remoting between nodes running Akka 2.4.16 and 2.5-M1, but some settings have changed so you might need
+to adjust some configuration as described in :ref:`mig25_rolling`.
+
 Cluster
 =======
 
+.. _mig25_rolling:
+
+Rolling Update
+----------------
+
+It is possible to do a rolling update from Akka 2.4.16 to 2.5-M1, i.e. running a cluster of 2.4.16 nodes and
+join nodes running 2.5-M1 followed by shutting down the old nodes.
+
+You must first update all nodes to 2.4.16. It's not supported to update directly from an older version than
+2.4.16 to 2.5-M1. For example, if you are running 2.4.11 you must first do a rolling update to 2.4.16, shut down
+all 2.4.11 nodes, and then do the rolling update to 2.5-M1.
+
+For some configuration settings it's important to use the same values on all nodes in the cluster.
+Some settings have changed default value in 2.5-M1 and therefore you need to review your configuration
+before doing a rolling update to 2.5-M1. Such settings are mentioned elsewhere in this migration guide
+and here is a summary of things to consider.
+
+* :ref:`mig25_addser`
+* :ref:`mig25_weaklyup`
+* :ref:`mig25_sharding_store`
+* :ref:`mig25_mutual`
+
 Coordinated Shutdown
 --------------------
 
@@ -336,6 +368,8 @@ used in the test::
   akka.coordinated-shutdown.run-by-jvm-shutdown-hook = off
   akka.cluster.run-coordinated-shutdown-when-down = off 
 
+.. _mig25_weaklyup:
+
 WeaklyUp
 --------
 
@@ -346,6 +380,8 @@ WeaklyUp
 You should not run a cluster with this feature enabled on some nodes and disabled on some. Therefore
 you might need to enable/disable it in configuration when performing rolling upgrade from 2.4.x to 2.5.0.
 
+.. _mig25_sharding_store:
+
 Cluster Sharding state-store-mode
 ---------------------------------
 

akka-docs/rst/scala/remoting-artery.rst

@@ -458,7 +458,7 @@ Akka internals do not rely on Java serialization (exceptions to that being ``jav
 
   One may think that network bandwidth and latency limit the performance of remote messaging, but serialization is a more typical bottleneck.
   
-For user messages, the default serializer, implemented using Java serialization, remains available and enabled in Artery.
+For user messages the default serializer implemented using Java serialization remains available and enabled by default.
 We do however recommend to disable it entirely and utilise a proper serialization library instead in order effectively utilise 
 the improved performance and ability for rolling deployments using Artery. Libraries that we recommend to use include, 
 but are not limited to, `Kryo`_ by using the `akka-kryo-serialization`_ library or `Google Protocol Buffers`_ if you want

akka-docs/rst/scala/remoting.rst

@@ -301,7 +301,7 @@ Akka internals do not rely on Java serialization (exceptions to that being ``jav
 
   One may think that network bandwidth and latency limit the performance of remote messaging, but serialization is a more typical bottleneck.
   
-For user messages, the default serializer, implemented using Java serialization, remains available and enabled by default.
+For user messages the default serializer implemented using Java serialization remains available and enabled by default.
 We do however recommend to disable it entirely and utilise a proper serialization library instead in order effectively utilise 
 the improved performance and ability for rolling deployments using Artery. Libraries that we recommend to use include, 
 but are not limited to, `Kryo`_ by using the `akka-kryo-serialization`_ library or `Google Protocol Buffers`_ if you want