Performing online upgrade by using the installation toolkit

Use the following procedure to do an online upgrade of IBM Spectrum Scale by using the installation toolkit

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.
Extract the new IBM Spectrum Scale self-extracting package by using the package name (for example, /tmp/Spectrum_Scale_Standard-5.0.3.x_x86_64-Linux_install).
This creates a new directory structure (/usr/lpp/mmfs/5.0.3.x/).
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 installation toolkit
- adding nodes to an existing cluster using the installation toolkit
- adding NSDs or file systems to an existing cluster using the installation toolkit
Depending on your setup, do one of the following to obtain the current cluster configuration through the cluster definition file:
- If you are upgrading an IBM Spectrum Scale cluster that was created by using the installation toolkit, do these steps to upgrade by using the installation toolkit.
  Note: If you have used the installation toolkit for the initial installation and deployment, it is assumed that the prerequisites are already in place.
  1. If you want to change the installer node before the upgrade, issue the spectrumscale setup -s InstallNodeIP command to set up the new installer node.
  2. Create a backup of the cluster definition file present in the installer configuration directory of the target version. For example: /usr/lpp/mmfs/5.0.3.x/installer/configuration
    This backup can be used in case the config populate command fails.
  3. From the installer directory of the target version that you are upgrading to, 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 and Limitations of config populate option of the installation toolkit.
    If the config populate command fails, before proceeding with the upgrade, do the following.
    1. Copy the cluster definition file from the /usr/lpp/mmfs/PreviousVersionDir/installer/configuration directory to the /usr/lpp/mmfs/5.0.3.x/installer/configuration directory.
      Where PreviousVersionDir is the directory that is named according to the version that you are upgrading from. For example, 4.2.3.10 or 5.0.1.1.
    2. Update the cluster definition file with the cluster state change operations that were done after the initial installation and deployment by using the ./spectrumscale commands. These cluster state change operations include:
      Node-related changes such as adding nodes
      
      NSD-related changes such as adding or modifying NSDs
      
      File system changes such as creating or modifying file systems
      
      Protocols-related changes such as enabling or disabling protocols
- If you are upgrading a manually created IBM Spectrum Scale cluster, do these steps to upgrade by using the installation toolkit.
  1. Ensure that the prerequisite steps for using the installation toolkit are completed. For more information, see Preparing to use the installation toolkit.
  2. Configure your cluster definition file as explained in the following topics:
    - Setting up the installer node
    - Defining the cluster topology for the installation toolkit
  3. From the installer directory of the target version that you are upgrading to, 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 and Limitations of config populate option of the installation toolkit.
    If the config populate command fails, before proceeding with the upgrade, update the cluster definition file with the cluster state change operations that were done after the initial installation and deployment by using the ./spectrumscale commands. These cluster state change operations include:
    - Node-related changes such as adding nodes
    - NSD-related changes such as adding or modifying NSDs
    - File system changes such as creating or modifying file systems
    - Protocols-related changes such as enabling or disabling protocols
Ensure that the cluster definition file is accurate and reflects the current state of your IBM Spectrum Scale cluster.
Note: If you are upgrading from IBM Spectrum Scale release 4.2.1 or earlier, 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.

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.
Run the upgrade precheck using the ./spectrumscale upgrade precheck command.
Important: It is highly recommended to run the upgrade precheck while you are planning to upgrade, before the actual upgrade procedure. Doing this allows you adequate time to address any issues flagged during the upgrade precheck.
For any cluster with existing performance monitoring collectors, the upgrade prechecks might find that a reconfiguration is required. To enable the installation toolkit to perform the reconfiguration, issue the following command:
```
./spectrumscale config perfmon -r on
```
To keep your existing algorithms, issue the following command:
```
./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.

To perform an offline upgrade based on the findings in the precheck results, do the steps in Designating nodes as offline in the upgrade configuration.
Run the upgrade process using the ./spectrumscale upgrade run command.
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.
```
Note: On Ubuntu 16.04 LTS systems, if the call home capability is enabled, after upgrading the call home packages to version 5.0.1 or later, issue the following commands from one of the nodes that is a part of a call home group.
```
mmcallhome capability disable
mmcallhome capability enable accept
```
After the upgrade is completed, the installation toolkit automatically runs the upgrade post checks. You can manually run the upgrade post checks by issuing the ./spectrumscale upgrade postcheck command.
Do an upgrade rerun as required if the fresh upgrade is not successful. For more information, see Upgrade rerun after an upgrade failure.
After the upgrade process is done, complete the upgrade to the new code level to take advantage of the new functionality. For more information, see Completing the upgrade to a new level of IBM Spectrum Scale.