SupportConsoleDevelopersStart a trialContact

Chapter 40. Rolling Upgrades

40.1. Rolling Upgrades

In Red Hat JBoss Data Grid, rolling upgrades permit a cluster to be upgraded from one version to a new version without experiencing any downtime. This allows nodes to be upgraded without the need to restart the application or risk losing data.

In JBoss Data Grid, rolling upgrades can only be performed in Remote Client-Server mode.

Important

When performing a rolling upgrade it is recommended to not update any cache entries in the source cluster, as this may lead to data inconsistency.

40.2. Rolling Upgrades Using Hot Rod

The following process is used to perform rolling upgrades on Red Hat JBoss Data Grid running in Remote Client-Server mode, using Hot Rod. This procedure is designed to upgrade the data grid itself, and does not upgrade the client application.

Important

Ensure that the correct version of the Hot Rod protocol is used with your JBoss Data Grid version. This version must be specified on the client programmatically, and instructions on defining this are found inside the JBoss Data Grid Developer Guide . A list of Hot Rod protocol versions from each release are found below:

  • For JBoss Data Grid 7.1, use Hot Rod protocol version 2.5
  • For JBoss Data Grid 7.0, use Hot Rod protocol version 2.5
  • For JBoss Data Grid 6.6, use Hot Rod protocol version 2.3
  • For JBoss Data Grid 6.5, use Hot Rod protocol version 2.0
  • For JBoss Data Grid 6.4, use Hot Rod protocol version 2.0
  • For JBoss Data Grid 6.3, use Hot Rod protocol version 2.0
  • For JBoss Data Grid 6.2, use Hot Rod protocol version 1.3
  • For JBoss Data Grid 6.1, use Hot Rod protocol version 1.2

Prerequisite

This procedure assumes that a cluster is already configured and running, and that it is using an older version of JBoss Data Grid. This cluster is referred to below as the Source Cluster and the Target Cluster refers to the new cluster to which data will be migrated.

  1. Configure the Target Cluster

    Use either different network settings or a different JGroups cluster name to set the Target Cluster (consisting of nodes with new JBoss Data Grid) apart from the Source Cluster. For each cache, configure a RemoteCacheStore with the following settings:

    1. Ensure that remote-server points to the Source Cluster.
    2. Ensure that the cache name matches the name of the cache on the Source Cluster.
    3. Ensure that hotrod-wrapping is enabled (set to true).
    4. Ensure that purge is disabled (set to false).

    5. Ensure that passivation is disabled (set to false).

      Figure 40.1. Configure the Target Cluster with a RemoteCacheStore

      1460
    Note

    See the $JDG_HOME/docs/examples/configs/[path]standalone-hotrod-rolling-upgrade.xml file for a full example of the Target Cluster configuration for performing Rolling Upgrades.

  2. Start the Target Cluster

    Start the Target Cluster’s nodes. Configure each client to point to the Target Cluster instead of the Source Cluster. Eventually, the Target Cluster handles all requests instead of the Source Cluster. The Target Cluster then lazily loads data from the Source Cluster on demand using the RemoteCacheStore.

    Figure 40.2. Clients point to the Target Cluster with the Source Cluster as RemoteCacheStore for the Target Cluster.

    1461

  3. Dump the Source Cluster keyset

    When all connections are using the Target Cluster, the keyset on the Source Cluster must be dumped. This can be done using either JMX or the CLI:

    1. JMX

      Invoke the recordKnownGlobalKeyset operation on the RollingUpgradeManager MBean on the Source Cluster for every cache that must be migrated.

    2. CLI

      Invoke the upgrade --dumpkeys command on the Source Cluster for every cache that must be migrated, or use the --all switch to dump all caches in the cluster.

  4. Fetch remaining data from the Source Cluster

    The Target Cluster fetches all remaining data from the Source Cluster. Again, this can be done using either JMX or CLI:

    1. JMX

      Invoke the synchronizeData operation and specify the hotrod parameter on the RollingUpgradeManager MBean on the Target Cluster for every cache that must be migrated.

    2. CLI

      Invoke the upgrade --synchronize=hotrod command on the Target Cluster for every cache that must be migrated, or use the --all switch to synchronize all caches in the cluster.

  5. Disabling the RemoteCacheStore

    Once the Target Cluster has obtained all data from the Source Cluster, the RemoteCacheStore on the Target Cluster must be disabled. This can be done as follows:

    1. JMX

      Invoke the disconnectSource operation specifying the hotrod parameter on the RollingUpgradeManager MBean on the Target Cluster.

    2. CLI

      Invoke the upgrade --disconnectsource=hotrod command on the Target Cluster.

  6. Decommission the Source Cluster

    As a final step, decommission the Source Cluster.

40.3. Rolling Upgrades Using REST

The following procedure outlines using Red Hat JBoss Data Grid installations as a remote grid using the REST protocol. This procedure applies to rolling upgrades for the grid, not the client application.

Perform Rolling Upgrades Using REST

In the instructions, the Source Cluster refers to the old cluster that is currently in use and the Target Cluster refers to the destination cluster for our data.

  1. Configure the Target Cluster

    Use either different network settings or a different JGroups cluster name to set the Target Cluster (consisting of nodes with new JBoss Data Grid) apart from the Source Cluster. For each cache, configure a RestCacheStore with the following settings:

    1. Ensure that the host and port values point to the Source Cluster.
    2. Ensure that the path value points to the Source Cluster’s REST endpoint.

  2. Start the Target Cluster

    Start the Target Cluster’s nodes. Configure each client to point to the Target Cluster instead of the Source Cluster. Eventually, the Target Cluster handles all requests instead of the Source Cluster. The Target Cluster then lazily loads data from the Source Cluster on demand using the RestCacheStore.

  3. Do not dump the Key Set during REST Rolling Upgrades

    The REST Rolling Upgrades use case is designed to fetch all the data from the Source Cluster without using the recordKnownGlobalKeyset operation.

    Warning

    Do not invoke the recordKnownGlobalKeyset operation for REST Rolling Upgrades. If you invoke this operation, it will cause data corruption and REST Rolling Upgrades will not complete successfully.

  4. Fetch the Remaining Data

    The Target Cluster must fetch all the remaining data from the Source Cluster. This is done either using JMX or the CLI as follows:

    1. Using JMX

      Invoke the synchronizeData operation with the rest parameter specified on the RollingUpgradeManager MBean on the Target Cluster for all caches to be migrated.

    2. Using the CLI

      Run the upgrade --synchronize=rest on the Target Cluster for all caches to be migrated. Optionally, use the --all switch to synchronize all caches in the cluster.

  5. Disable the RestCacheStore

    Disable the RestCacheStore on the Target Cluster using either JMX or the CLI as follows:

    1. Using JMX

      Invoke the disconnectSource operation with the rest parameter specified on the RollingUpgradeManager MBean on the Target Cluster.

    2. Using the CLI

      Run the upgrade --disconnectsource=rest command on the Target Cluster. Optionally, use the --all switch to disconnect all caches in the cluster.

Result

Migration to the Target Cluster is complete. The Source Cluster can now be decommissioned.

40.4. RollingUpgradeManager Operations

The RollingUpgradeManager Mbean handles the operations that allow data to be migrated from one version of Red Hat JBoss Data Grid to another when performing rolling upgrades. The RollingUpgradeManager operations are:

  • recordKnownGlobalKeyset retrieves the entire keyset from the cluster running on the old version of JBoss Data Grid.
  • synchronizeData performs the migration of data from the Source Cluster to the Target Cluster, which is running the new version of JBoss Data Grid.
  • disconnectSource disables the Source Cluster, the older version of JBoss Data Grid, once data migration to the Target Cluster is complete.

40.5. RemoteCacheStore Parameters for Rolling Upgrades

40.5.1. rawValues and RemoteCacheStore

By default, the RemoteCacheStore store’s values are wrapped in InternalCacheEntry. Enabling the rawValues parameter causes the raw values to be stored instead for interoperability with direct access by RemoteCacheManagers.

rawValues must be enabled in order to interact with a Hot Rod cache via both RemoteCacheStore and RemoteCacheManager.

40.5.2. hotRodWrapping

The hotRodWrapping parameter is a shortcut that enables rawValues and sets an appropriate marshaller and entry wrapper for performing Rolling Upgrades.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.