LATEST VERSION: 9.0.4 - CHANGELOG
Pivotal GemFire® v9.0

Windows/Unix/Linux—Upgrade Pivotal GemFire

This is the upgrade procedure to a GemFire 9 version.

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. 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 geode.properties/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 installation.

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

  10. Redeploy applications.

  11. Test 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. As of this writing Java SE 7 is already End-of-Life.

  • 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 an 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. 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.2 clients, so a version 9 server will understand calls from an 8.2.2 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.2 peers or servers.

Pivotal GemFire 8.2.2 clients that use continuous queries cannot work with 9.x servers. Pivotal GemFire 8.2.2 clients that use continuous queries must be reimplemented to use the 9.x package names.

Pivotal GemFire 8.2.2 clients that run functions on servers using the Execution interface’s execute(Function function) signature cannot work with 9.x servers. Pivotal GemFire 8.2.2 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. Also implement package renaming for any client applications that are to be upgraded to Pivotal GemFire 9.x.

  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=172.16.139.180, port=1099] ..
    Successfully connected to: [host=172.16.139.180, port=1099]
    
    gfsh>list members
     Name   | Id
    ------- | -------------------------------------------
    server2 | 172.16.139.180(server2:29368)<v2>:35840
    locator | 172.16.139.180(locator:29181:locator):36278
    server1 | 172.16.139.180(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. Upgrade Java, if needed.

  5. Download the new version of GemFire from the Pivotal GemFire downloads page.

  6. 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 are likely to differ from those shown in this example.

  7. Reset all GemFire-related environment variables to point to the new installation. 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. Repeat steps 3-6 on all machines within the cluster.

  9. Redeploy your environment’s configuration files to the new version installation.

  10. Install updated server code. Point all client applications to the new installation of GemFire.

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

  12. Once all systems are functioning normally and all tests are successful, remove the old version of GemFire 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.1 release would be

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

Multi-site Upgrade using WAN Gateway

Systems that have both persistent disk stores and a bidirectional WAN gateway to replicate data among sites can implement an upgrade that does not require system down time. It requires multiple reconfigurations during the process, such that each site can be individually upgraded while the rest of the system continues.

The procedure assumes that each site has already been upgraded to at least Pivotal GemFire version 8.2.2.

This diagram shows the initial state of the system.

The procedure for upgrading two sites, Site A and Site B:

  1. Reconfigure to redirect all traffic away from Site B (which will be the first site that gets upgraded).
  2. Pause the gateway senders on Site A.
  3. Upgrade Site B to GemFire 9.x.
  4. Start GemFire 9.x on Site B.
  5. Pause the gateway senders on Site B.
  6. Start the gateway senders on Site A and wait for Site A’s queues to drain.
  7. Once the queues have drained sufficiently, reconfigure to redirect all traffic to Site B. Site A’s queues should now drain the rest of the way.
  8. Upgrade Site A to GemFire 9.x.
  9. Once Site A is back up, start Site B’s gateway senders and wait for the queues to drain sufficiently.
  10. Reconfigure to redistribute the load across both Site A and Site B.