Upgrade from Version 8.2 to Version 9

This is the upgrade procedure to a GemFire 9 version from Pivotal GemFire 8.2.3 or a more recent release of Pivotal GemFire 8.2.

General Upgrade Steps

These steps identify the ordering of an upgrade. A more detailed procedure is given below.

  1. Implement package renaming for server-side callbacks in a test environment. The server class path uses geode-dependencies.jar in place of the no longer used gemfire.jar and server-dependencies.jar. Change your server-side callbacks and functions to use org.apache.geode packages instead of com.gemstone.gemfire packages. Also implement package renaming for any client applications that are to be upgraded to a Pivotal GemFire 9 version.

  2. Make backups, so you can restore your GemFire version 8 cluster if the upgrade does not complete to your satisfaction.

    • Back up all existing disk-stores and data.
    • Back up all configuration files including gemfire.properties and .xml configurations.

  3. Check system requirements and make changes where applicable.

  4. Shut down the cluster.

  5. Upgrade the Java JDK to v1.8.0_92 or later, if necessary.

  6. Install the new version of GemFire, and update environment variables to point to the new installation.

  7. Install revised server-side callbacks and any upgraded clients.

  8. Start the cluster using the new GemFire version 9 installation.

  9. Test the new installation to assure that the cluster has been properly redeployed.

  10. Redeploy client applications.

  11. Test client applications for proper functionality.

  12. Remove the old distribution to prevent inadvertent version conflicts.

Java Notes

  • The Pivotal GemFire product download does not include Java. You must download and install a supported JRE or JDK on each system running GemFire. GemFire recommends the installation of a full JDK (and not just a JRE) to obtain better performance with gfsh status and gfsh stop commands.

  • To check your current Java version, type java -version at a command-line prompt.

  • Pivotal GemFire 9.x requires Java SE 8, version 92 or a more recent version. Pivotal GemFire 8.0 was the last GemFire release to support Java SE 6, and Java SE 7 is in End-of-Life status.

RHEL/Centos: with previous installation via RPM

RPMs existed for GemFire 8.x, but they are not available for GemFire 9.x. To install on a RHEL/Centos system, follow these upgrade procedure instructions, with a modified final step of uninstalling the GemFire 8.x version using rpm -e.

Ubuntu: with previous installation via Debian packaging

DEBs existed for GemFire 8.x, but they are not available for GemFire 9.x. To install on an Ubuntu system, follow the upgrade procedure instructions, with a modified final step of uninstalling the GemFire 8.x version using dpkg --remove or dpkg --purge.

Package Renaming

Pivotal GemFire 9.x uses the same packages as open-source Apache Geode. Pivotal GemFire 8.x did not use the Apache Geode package naming. All com.gemstone.gemfire package names are now org.apache.geode. If you have written code that explicitly imports gemfire packages, you must change those references to use the geode names. This applies to all server side code. Search and replace com.gemstone.gemfire with org.apache.geode.

The Pivotal GemFire 9.x release is backwards compatible with Pivotal GemFire 8.2.3 and more recent 8.2 clients, so a version 9 server will understand calls from an 8.2.3 client that uses the old com.gemstone.gemfire package names. Pivotal GemFire 9.x peers and servers are not compatible with Pivotal GemFire 8.2.3 peers or servers.

Pivotal GemFire 8.2.3 and more recent version 8.2 clients that run functions on servers using the Execution interface’s execute(Function function) signature can not work with 9.x servers. The clients that run functions with this signature must be reimplemented as 9.x clients which use the 9.x package names.

The Upgrade Procedure, Step by Step

Follow these steps to upgrade to Pivotal GemFire 9.x on Linux, Unix, or Windows.

  1. Implement package renaming for server-side callbacks in a test environment. The server class path uses geode-dependencies.jar in place of the no longer used gemfire.jar and server-dependencies.jar. Change your server-side callbacks and functions to use org.apache.geode packages instead of com.gemstone.gemfire packages. Also implement package renaming for any client applications that are to be upgraded to a Pivotal GemFire 9 version.

  2. Make backup copies of all existing disk-stores, server-side code, configuration files, and data across the entire cluster. To get a backup of the data that includes the most recent changes may require that traffic across the cluster is stopped before the backup is made.

  3. Shut down the cluster running with the prior version. Open a gfsh prompt:

    % gfsh

    Connect to the locator:

    gfsh>connect --locator=localhost[10334]
Connecting to Locator at [host=localhost, port=10334] ..
Connecting to Manager at [host=192.0.2.0, port=1099] ..
Successfully connected to: [host=192.0.2.0, port=1099]

gfsh>list members
 Name   | Id
------- | -------------------------------------------
server2 | 192.0.2.0(server2:29368)<v2>:35840
locator | 192.0.2.0(locator:29181:locator):36278
server1 | 192.0.2.0(server1:29285)<v1>:40574

    Shut down the entire cluster (by pressing Y at the prompt, this will lose no persisted data):

    gfsh>shutdown --include-locators=true
As a lot of data in memory will be lost, including possibly events in queues,
do you really want to shutdown the entire distributed system? (Y/n): Y
succeeded in shutting down

    Since GemFire is a Java process, to check before continuing that all GemFire members successfully stopped, it is useful to use the JDK-included jps command to check running java processes:

    % jps
29664 Jps

  4. On each machine in the cluster, upgrade Java, if needed.

  5. On the machine hosting the locator you wish to upgrade, install the new version of the software (alongside the older version of the software). See Installing Pivotal GemFire.

  6. On each machine in the cluster, install the new version of the software (alongside the older version of the software). See Installing Pivotal GemFire.

    To check that the system finds the new installation, open a gfsh prompt and check the GemFire version:

    % gfsh --version
v9.0.0

  7. On each machine in the cluster, redeploy your environment’s configuration files to the new version installation.

  8. Restart all system members according to your usual procedures.

  9. Upgrade Tanzu GemFire clients. See Upgrading Clients for details.

  10. Once all systems are functioning normally and all tests are successful, remove the old version of GemFire from each machine in the cluster, to reduce possibility of version complications in the future. See Uninstalling GemFire for instructions.