LATEST VERSION: 9.1.0 - CHANGELOG
Pivotal GemFire® v9.1

Windows/Unix/Linux—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 unexpected version conflicts.

Java Notes

  • 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.

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

  • 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.

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 each machine in the cluster, download the new version of GemFire from the Pivotal GemFire downloads page.

  6. On each machine in the cluster, move the compressed download to the desired installation directory, and uncompress or expand it. For example, to expand the compressed tar file:

    % tar -xzf pivotal-gemfire-9.0.0.tar.gz
    

    The file name and version number is likely to differ from the one shown in this example.

  7. On each machine in the cluster, reset all GemFire-related environment variables to point to the new installation. On a Linux/Unix machine, for example:

    export JAVA_HOME=/usr/java/jdk1.8.0_92
    export GEMFIRE=<PATH TO INSTALL LOCATION>/pivotal-gemfire-9.0.0
    export PATH=$JAVA_HOME/bin:$GEMFIRE/bin:$PATH
    

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

    % gfsh --version
    v9.0.0
    
  8. On each machine in the cluster, redeploy your environment’s configuration files to the new version installation.

  9. On each machine in the cluster, install updated server code. Point all client applications to the new installation of GemFire.

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

  11. 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.

    • If the old version of GemFire was installed from a ZIP file, uninstall that old version by deleting its product tree.
    • If the old version of GemFire was installed with an RPM, uninstall using
    rpm -e Pivotal_GemFire_XXX
    

    where XXX is replaced by the GemFire version number and also corresponds to the name of the product installation directory. As an example, the command for removing the GemFire 8.2.5 release would be

    rpm -e Pivotal_GemFire_825
    
    • If the old version of GemFire was installed with DEBs, uninstall using
    dpkg --remove pivotal-gemfire