Chapter 8. Patching Data Grid Server Installations

Install and manage patches for Data Grid server installations.

You can apply patches to multiple Data Grid servers with different versions to upgrade to a desired target version. However, patches do not take effect if Data Grid servers are running. For this reason you install patches while servers are offline. If you want to upgrade Data Grid clusters without downtime, create a new cluster with the target version and perform a rolling upgrade to that version instead of patching.

8.1. Data Grid Server Patches

Data Grid server patches are .zip archives that contain artifacts that you can apply to your $RHDG_HOME directory to fix issues and add new features.

Patches also provide a set of rules for Data Grid to modify your server installation. When you apply patches, Data Grid overwrites some files and removes others, depending on if they are required for the target version.

However, Data Grid does not make any changes to configuration files that you have created or modified when applying a patch. Server patches do not modify or replace any custom configuration or data.

8.2. Downloading Server Patches

Download patches that you can apply to Data Grid servers.

Procedure

  1. Access the Red Hat customer portal.
  2. Download the appropriate Data Grid server patch from the software downloads section.
  3. Open a terminal window and navigate to $RHDG_HOME.

  4. Start the CLI. 

    $ bin/cli.sh
[disconnected]>

  5. Describe the patch file you downloaded. 

    [disconnected]> patch describe /path/to/redhat-datagrid-$version-server-patch.zip
Red Hat Data Grid patch target=$target_version source=$source_version created=$timestamp
    • $target_version is the Data Grid version that applies when you install the patch on a server.
    • $source_version is one or more Data Grid server versions where you can install the patch.

Verification

Use the checksum to verify the integrity of your download.

  1. Run the md5sum or sha256sum command with the downloaded patch as the argument, for example: 

    $ sha256sum redhat-datagrid-$version-server-patch.zip
  2. Compare with the MD5 or SHA-256 checksum value on the Data Grid Software Details page.

8.3. Creating Server Patches

You can create patches for Data Grid servers from an existing server installation.

You can create patches for Data Grid servers starting from 8.0.1. You can patch 8.0 GA servers with 8.0.1. However you cannot patch 7.3.x or earlier servers with 8.0.1 or later.

You can also create patches that either upgrade or downgrade the Data Grid server version. For example, you can create a patch from version 8.0.1 and use it to upgrade version 8.0 GA or downgrade a later version.

Important

Red Hat supports patched server deployments only with patches that you download from the Red Hat customer portal. Red Hat does not support server patches that you create yourself.

Procedure

  1. Navigate to $RHDG_HOME for a Data Grid server installation that has the target version for the patch you want to create.

  2. Start the CLI. 

    $ bin/cli.sh
[disconnected]>

  3. Use the patch create command to generate a patch archive and include the -q option with a meaningful qualifier to describe the patch. 

    [disconnected]> patch create -q "this is my test patch" path/to/mypatch.zip \
path/to/target/server/home path/to/source/server/home

    The preceding command generates a .zip archive in the specified directory. Paths are relative to $RHDG_HOME for the target server.

    Tip

    Create single patches for multiple different Data Grid versions, for example: 

    [disconnected]> patch create -q "this is my test patch" path/to/mypatch.zip \
path/to/target/server/home \
path/to/source/server1/home path/to/source/server2/home

    Where server1 and server2 are different Data Grid versions where you can install "mypatch.zip".

  4. Describe the generated patch archive. 

    [disconnected]> patch describe path/to/mypatch.zip

Red Hat Data Grid patch target=$target_version(my test patch)  source=$source_version created=$timestamp
    • $target_version is the Data Grid server version from which the patch was created.

    • $source_version is one or more Data Grid server versions to which you can apply the patch.

      You can apply patches to Data Grid servers that match the $source_version only. Attempting to apply patches to other versions results in the following exception: 

      java.lang.IllegalStateException: The supplied patch cannot be applied to `$source_version`

8.4. Installing Server Patches

Apply patches to Data Grid servers to upgrade or downgrade an existing version.

Prerequisites

  • Download a server patch for the target version.

Procedure

  1. Navigate to $RHDG_HOME for the Data Grid server you want to patch.

  2. Stop the server if it is running.

    Note

    If you patch a server while it is running, the version changes take effect after restart. If you do not want to stop the server, create a new cluster with the target version and perform a rolling upgrade to that version instead of patching.

  3. Start the CLI. 

    $ bin/cli.sh
[disconnected]>

  4. Install the patch. 

    [disconnected]> patch install path/to/patch.zip

Red Hat Data Grid patch target=$target_version source=$source_version \
created=$timestamp installed=$timestamp
    • $target_version displays the Data Grid version that the patch installed.
    • $source_version displays the Data Grid version before you installed the patch.

  5. Start the server to verify the patch is installed. 

    $ bin/server.sh
...
ISPN080001: Red Hat Data Grid Server $version

    If the patch is installed successfully $version matches $target_version.

Tip

Use the --server option to install patches in a different $RHDG_HOME directory, for example: 

[disconnected]> patch install path/to/patch.zip --server=path/to/server/home

8.5. Rolling Back Server Patches

Remove patches from Data Grid servers by rolling them back and restoring the previous Data Grid version.

Important

If a server has multiple patches installed, you can roll back the last installed patch only.

Rolling back patches does not revert configuration changes you make to Data Grid server. Before you roll back patches, you should ensure that your configuration is compatible with the version to which you are rolling back.

Procedure

  1. Navigate to $RHDG_HOME for the Data Grid server installation you want to roll back.
  2. Stop the server if it is running.

  3. Start the CLI. 

    $ bin/cli.sh
[disconnected]>

  4. List the installed patches. 

    [disconnected]> patch ls

Red Hat Data Grid patch target=$target_version source=$source_version
created=$timestamp installed=$timestamp
    • $target_version is the Data Grid server version after the patch was applied.
    • $source_version is the version for Data Grid server before the patch was applied. Rolling back the patch restores the server to this version.

  5. Roll back the last installed patch. 

    [disconnected]> patch rollback

  6. Quit the CLI. 

    [disconnected]> quit

  7. Start the server to verify the patch is rolled back to the previous version. 

    $ bin/server.sh
...
ISPN080001: Data Grid Server $version

    If the patch is rolled back successfully $version matches $source_version.

Tip

Use the --server option to rollback patches in a different $RHDG_HOME directory, for example: 

[disconnected]> patch rollback --server=path/to/server/home