Preparation steps

Perform the following preparation steps before you run the apupgrade command and upgrade your system.

Before you begin

Always read the Release notes to learn about any known issues that might apply to your IAS version.

Depending on which version you are upgrading, additional steps might apply:
  • If you are upgrading Integrated Analytics System from a version earlier than version 1.0.2.0, contact your IBM® representative for assistance with the upgrade.
  • When upgrading Integrated Analytics System to version 1.0.6.0, under certain circumstances external connectivity to the appliance might be lost. This is a known issue. It is important that you check if your system might be affected. Before running apupgrade, run the following command:
    ip r | grep default | grep fbond && echo "Upgrade impacted, do not proceed"
    Do not proceed if the warning is displayed. Contact IBM Support to upgrade the system manually.
  • If you are upgrading from version 1.0.9.0 to 1.0.10.x and you are using EMC NetWorker for database backup operations, back up your configuration before upgrading by following the steps found in DEPRECATED: Backing up and restoring the EMC NetWorker configuration.
  • If you are upgrading to version 1.0.12.0 or earlier, and you have EMC NetWorker configured, run this manual check as bluadmin within the container:
    db2 connect to bludb &> /dev/null ; db2 get db cfg for bludb | grep 'LOGARCHMETH2.*.libnsrdb2.so' && echo "Upgrade impacted by known issue (EMC NetWorker), do not proceed and contact support"
  • When running apupgrade to start the upgrade on the appliance on versions 1.0.11.0 - 1.0.14.0, Platform Manager might time out resulting in node0101 (or current head node) rebooting, or, in some cases, powering itself off. Restart the database with apstop -p --service and apstart -p before upgrading to avoid this condition.
  • If you are upgrading from version 1.0.10.1 or below, to version 1.0.16.0, you must perform a two-step upgrade: first upgrade to 1.0.15.0, and then upgrade again from 1.0.15.0 to 1.0.16.0.
  • Upgrading to 1.0.19.7 includes a Db2 database engine upgrade to version 11.5. Additional preparation and post-upgrade steps are required as described in Upgrading to 1.0.19.7.
  • To upgrade to 1.0.21.0 and any future releases, you must be on IAS 1.0.19.7 first. Follow the preparation steps and the upgrade procedure as described in Upgrading to 1.0.19.7.
  • The upgrade to 1.0.25.0 cannot be a partial one. Do a complete upgrade of the whole system.
  • Upgrade to 1.0.27.0 can be partial - container only upgrade is supported.
  • Run the following commands to backup the home directory before upgrading the Integrated Analytics System 1.0.30.0 IF1 except apuser, and then restore it after the upgrade.
    • To backup:
      tar --exclude='/path/to/apuser' czvf /path/to/backup/location/home_backup.tar.gz /home/
    • To restore:
      tar xvfz /path/to/backup/location/home_backup.tar.gz

The standard upgrade process takes approximately 8-12 hours.

Regardless of the version your system is on, always follow these steps to prepare for upgrade:

Procedure

  1. Download or copy the Integrated Analytics System bundle to /localrepo.
    Note: The upgrade bundle must be downloaded to the actual /localrepo partition on the node running the upgrade. GPFS is stopped during the upgrade, so if the bundle is downloaded to GPFS storage, the upgrade fails.
  2. Run ap issues and resolve any of the issues that might impact the upgrade process.
  3. Copy the tar.gz file from the downloaded location to a directory on node0101 with the same name as the version of the file name.
    1. Create the new directory outside the container on node0101:
      mkdir /localrepo/w.x.y.z_release
      where w.x.y.z is the release number. In this case, /localrepo defines the upgrade directory for the --upgrade-directory parameter that is used later.

      The directory name cannot start with release or iias prefix. Use the release number.

    2. Move the upgrade package (tar.gz) file into this new directory:
      mv package.tar.gz /localrepo/w.x.y.z_release
  4. Run a preliminary check to verify that the system is ready for an upgrade. This command also extracts the bundle.
    apupgrade --upgrade-directory /localrepo --use-version <new-version>
          --preliminary-check
    Perform any suggested steps to fix the issues that were reported.
    Note: It might take significant time to fix the issues, so it is important to run this pre-check ahead of the upgrade window.
    Once you run the pre-check, open a PMR with the details, so IBM Support can help you verify whether the system is in good health for the upgrade.
  5. (This step applies to IAS versions before 1.0.14.0.) Run apupgrade with the --upgrade-details option. This command prints details, such as currently installed version, target version, and estimated upgrade time for each component.
    apupgrade --upgrade-details --upgrade-directory upgrade_directory --use-version w.x.y.z_release
    For example:
    apupgrade --upgrade-details --upgrade-directory /localrepo --use-version 1.0.1.0_release

    In versions 1.0.14.0 and later, the upgrade details are included in the preliminary check.

  6. Ensure that the system is up and running:
    ap state -d
  7. Run the following commands to ensure that there are no new issues listed.
    ap issues
    ap issues -sw

Results

The ap state command should return the following message:
System state is 'Ready'.
Application state is 'Ready'.
Platform management state is 'Active'. 
If not, fix any issues and run apstart. Then run the following command again:
ap state -d

What to do next

Proceed with the upgrade as described in Upgrading with apupgrade.