Upgrading IBM Spectrum Scale components with the installation toolkit

Do the following steps to upgrade IBM Spectrum Scale using the installation toolkit:

1. Download the new IBM Spectrum Scale self-extracting package using the sub-steps and then place it on the installer node.
   1. Go to the IBM Spectrum Scale page on Fix Central, select the new spectrumscale package and then click Continue.
   2. Choose the download option Download using Download Director to download the new spectrumscale package and place it in the wanted location on the install node.
      Note: Although it is not recommended but if you must use the download option Download using your browser (HTTPS), instead of clicking the down arrow to the left of the package name, you must right-click on the package name and select the Save Link As.. option. If you click the download arrow, the browser might hang.
2. Extract the new IBM Spectrum Scale self-extracting package by using the package name (for example, /tmp/Spectrum_Scale_Protocols_Standard-4.2.3.0_x86_64-Linux_install).

   This creates a new directory structure (/usr/lpp/mmfs/4.2.3.0/).

3. Accept the license agreement. After the self-extracting package extraction is done several next steps and instructions are displayed on the screen including:
   • cluster installation and protocol deployment
   • upgrading an existing cluster using the install toolkit
   • adding nodes to an existing cluster using the install toolkit
   • adding NSDs or file systems to an existing cluster using the install toolkit
4. Depending on your setup, do one of the following:
   • If you already have IBM Spectrum Scale installed and did not use the installation toolkit to do so, but you would like to upgrade using the toolkit, do the following:
     1. Configure your cluster definition file as explained in the following topics:
        • Setting up the install node
        • Defining configuration options for the spectrumscale installation toolkit
     2. Populate the cluster definition file with the current cluster state by issuing the ./spectrumscale config populate command. For more information, see Populating cluster definition file with current cluster state using the installation toolkit.
   • If you have IBM Spectrum Scale installed and have already used the installation toolkit, follow these steps:
     1. If you want to change the install node before the upgrade, issue the spectrumscale setup -s InstallNodeIP command to set up the new install node.
     2. Copy the cluster definition file from /usr/lpp/mmfs/4.2.x.x/installer/configuration/clusterdefinition.txt to the newly extracted /usr/lpp/mmfs/4.2.3.0/installer/configuration/clusterdefinition.txt directory.
     Note: You can populate the cluster definition file with the current cluster state by issuing the ./spectrumscale config populate command. For more information, see Populating cluster definition file with current cluster state using the installation toolkit.
5. Ensure that the cluster definition file is accurate and reflects the current state of your IBM Spectrum Scale cluster.
   Note: If you are upgrading to IBM Spectrum Scale release 4.2.2, ensure that the operating system and architecture fields in the output of the ./spectrumscale node list command are updated. These fields are automatically updated when you perform the upgrade precheck with ./spectrumscale upgrade --precheck or you can update these fields by issuing the ./spectrumscale config update command. For more information, see Running upgrade prechecks.

   If you want to upgrade IBM Spectrum Scale on IBM Spectrum Archive™ Enterprise Edition (EE) nodes using the installation toolkit, you must perform some additional steps to manage IBM Spectrum Archive components. For more information, see Upgrading IBM Spectrum Scale on IBM Spectrum Archive Enterprise Edition (EE) nodes using the installation toolkit.

6. Run the upgrade precheck using the ./spectrumscale upgrade --precheck command. For more information about upgrade precheck, see Running upgrade prechecks.
   Note: If you do not plan to run the upgrade precheck, make sure that you run the ./spectrumscale config update before starting the upgrade.
7. Run the upgrade process using the ./spectrumscale upgrade command. For more information, see Upgrading all components.
   Note:

   • Accept the warnings for system impact and interruption during the upgrade.
   • If you are upgrading to IBM Spectrum Scale release 4.2.2.1 or later on SLES 12 nodes, ignore the following warning generated by the local zypper repository created by the installation toolkit:

     WARN: Chef::Config[:zypper_check_gpg] was not set. 
     All packages will be installed without gpg signature checks. This is a security hazard.

8. After upgrade is successful, complete the migration to new code level to take advantage of the new functionality. For more information, see Completing the migration to a new level of IBM Spectrum Scale.

The spectrumscale upgrade command

As with all spectrumscale commands, use the -v flag for verbose output. The -v flag must be placed immediately after ./spectrumscale.

For example: ./spectrumscale -v upgrade

Running upgrade prechecks

./spectrumscale config perfmon -r on

./spectrumscale config perfmon -r off

If you are upgrading to IBM Spectrum Scale version 4.2.2 or later, the operating system and architecture fields in the cluster definition file must be updated. The upgrade precheck updates the operating system and CPU architecture fields in the cluster definition file. Alternatively, you can issue the spectrumscale config update command to update the operating system and CPU architecture fields in the cluster definition file.

/usr/lpp/mmfs/4.2.3.0/installer/spectrumscale upgrade -pr

Upgrading all components

All components can be upgraded at once using the following command:

./spectrumscale upgrade

This command can still be used even if all protocols are not enabled; however, the packages for other protocols will be also upgraded but not started.

This will cause a brief outage of the performance monitoring tool and SMB (if enabled). Refer to the following sections for more information about the impact of upgrade on each component.

Once upgrade is complete, run the spectrumscale upgrade -ve command to show the versions of the packages installed to ensure that they are all at the desired level.

After this, proceed to the next step which is migration to a new level of GPFS. For more information, see Completing the migration to a new level of IBM Spectrum Scale.

Failure recovery

If a failure occurs during an upgrade, examine the log at the location provided in the output from the install toolkit to determine the cause. More information on each spectrumscale error will be provided in the output from the install toolkit.

Certain failures will cause the upgrade process to stop. In this case, the cause of the failure should be addressed on the node on which it occurred. Once the problem has been addressed, the upgrade command can be run again. This will not affect any nodes that were upgraded successfully and will continue once the point of failure has been reached.

An example of a failure during upgrade is:

A protocol is enabled in the configuration file, but is not running on a node.

Using the mmces service list command on the node that failed will highlight which process is not running (the output from the install toolkit will also report which component failed). Make sure the component is started on all nodes with mmces service start nfs | smb | obj, or alternatively disable the protocol in the configuration using spectrumscale disable nfs|smb|object if the component has been intentionally stopped.

CAUTION:

When a protocol is disabled, the protocol is stopped on all protocol nodes in the cluster and all protocol-specific configuration data is removed.

For information on troubleshooting installation, deployment, and upgrade related issues, see Resolving most frequent problems related to installation, deployment, and upgrade.