[[rolling_upgrades]]
== Performing Rolling Upgrades

Upgrade {brandname} without downtime or data loss. You can perform rolling upgrades in Remote Client/Server Mode to start using a more recent version of {brandname}.

[NOTE]
====
This section explains how to upgrade {brandname} servers, see the appropriate documentation for your Hot Rod client for upgrade procedures.
====

From a high-level, you do the following to perform rolling upgrades:

. Set up a target cluster. The target cluster is the {brandname} version to which you want to migrate data. The source cluster is the {brandname} deployment that is currently in use. After the target cluster is running, you configure all clients to point to it instead of the source cluster.
. Synchronize data from the source cluster to the target cluster.

=== Setting Up a Target Cluster

. Start the target cluster with unique network properties or a different JGroups cluster name to keep it separate from the source cluster.
. Configure a `RemoteCacheStore` on the target cluster for each cache you want to migrate from the source cluster.
+
`RemoteCacheStore` settings::
+
* `remote-server` must point to the source cluster via the `outbound-socket-binding` property.
* `remoteCacheName` must match the cache name on the source cluster.
* `hotrod-wrapping` must be `true` (enabled).
* `shared` must be `true` (enabled).
* `purge` must be `false` (disabled).
* `passivation` must be `false` (disabled).
* `protocol-version` matches the Hot Rod protocol version of the source cluster.
+
.Example `RemoteCacheStore` Configuration
[source,xml,options="nowrap"]
----
<distributed-cache>
   <remote-store cache="MyCache" socket-timeout="60000" tcp-no-delay="true" protocol-version="2.5" shared="true" hotrod-wrapping="true" purge="false" passivation="false">
      <remote-server outbound-socket-binding="remote-store-hotrod-server"/>
   </remote-store>
</distributed-cache>
...
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
  ...
  <outbound-socket-binding name="remote-store-hotrod-server">
     <remote-destination host="198.51.100.0" port="11222"/>
  </outbound-socket-binding>
  ...
</socket-binding-group>
----
+
. Configure the target cluster to handle all client requests instead of the source cluster:
.. Configure all clients to point to the target cluster instead of the source cluster.
.. Restart each client node.
+
The target cluster lazily loads data from the source cluster on demand via `RemoteCacheStore`.

=== Synchronizing Data from the Source Cluster

. Call the `synchronizeData()` method in the `TargetMigrator` interface. Do one of the following on the target cluster for each cache that you want to migrate:
+
JMX::
+
Invoke the `synchronizeData` operation and specify the `hotrod` parameter on the `RollingUpgradeManager` MBean.
+
CLI::
+
[source,bash,options="nowrap"]
----
$ JDG_HOME/bin/cli.sh --connect controller=127.0.0.1:9990 -c "/subsystem=datagrid-infinispan/cache-container=clustered/distributed-cache=MyCache:synchronize-data(migrator-name=hotrod)"
----
+
Data migrates to all nodes in the target cluster in parallel, with each node
receiving a subset of the data.
+
Use the following parameters to tune the operation:
+
* `read-batch` configures the number of entries to read from the source cluster at a time. The default value is `10000`.
* `write-threads` configures the number of threads used to write data. The default value is the number of processors available.
+
For example:
+
`synchronize-data(migrator-name=hotrod, read-batch=100000, write-threads=3)`
+
. Disable the `RemoteCacheStore` on the target cluster. Do one of the following:
+
JMX::
+
Invoke the `disconnectSource` operation and specify the `hotrod` parameter on the `RollingUpgradeManager` MBean.
+
CLI::
+
[source,bash,options="nowrap"]
----
$ JDG_HOME/bin/cli.sh --connect controller=127.0.0.1:9990 -c "/subsystem=datagrid-infinispan/cache-container=clustered/distributed-cache=MyCache:disconnect-source(migrator-name=hotrod)"
----
+
. Decommission the source cluster.
