Upgrades

Upgrade summary

Upgrades to the same Operator Lifecycle Manager (OLM) channel for IBM Edge Application Manager (IEAM) Management Hub and IBM Cloud Platform Common Services occur automatically through OLM which comes pre-installed on your OpenShift Container Platform (OCP) Cluster.

IEAM channels are defined by minor version (for example v4.2, and v4.3) and will automatically update patch versions (for example 4.2.x) only. For minor version upgrades you must manually change channels to initiate the upgrade. In order to initiate a minor version upgrade, you must be at the latest patch version available of the previous minor version, then switching channels will initiate the upgrade.

Notes:

Upgrading the IEAM Management Hub from 4.3.2 to 4.3.3

  1. Make a backup prior to upgrading. For more information, see Backup and recovery.
  2. Navigate to the OCP web console for your cluster.
  3. Navigate to Operators -> Installed Operators.
  4. Select the ibm-edge project.
  5. Ensure that IEAM Management Hub shows Upgrade Available in the Status column.
  6. Select IBM Cloud Platform Common Services.
  7. Select the Subscription tab.
  8. Under Subscription Details, the channel should be set to stable-v1.
  9. Click the edit icon next to stable-v1, and then select the v3 option.
  10. Click Save. The upgrade should happen for IBM Foundational Services first, followed by the IEAM Management Hub upgrade.

Upgrading the IEAM Management Hub from 4.2.x to 4.3.x

  1. Take a backup prior to upgrading. For more information, see Backup and recovery.
  2. Navigate to the OCP web console for your cluster.
  3. Navigate to Operators -> Installed Operators.
  4. Search for IEAM and click on the IEAM Management Hub result.
  5. Navigate to the Subscription tab.
  6. Click on the v4.2 link in the Channel section.
  7. Click the radio button to switch your active channel to v4.3 to initiate the upgrade.

To verify that the upgrade is complete, see steps 1 through 5 in the Installation verification post-installation section.

To update example services, see steps 1 through 3 in the Post installation configuration section.

Upgrading edge nodes

Existing IEAM nodes do not upgrade automatically. The IEAM 4.2.1 agent version (2.28.0-338) is supported with an IEAM 4.3.3 Management Hub. In order to upgrade the IBM Edge Application Manager agent on your edge devices and edge clusters, you first need to put the 4.3.3 edge node files into the Cloud Sync Service (CSS).

Perform steps 1-3 under Installing the latest CLI to your environment even if you do not wish to upgrade your edge nodes at this time. This ensures new edge nodes will be installed with the latest IEAM 4.3.3 agent code.

Installing the latest CLI to your environment

  1. If you have not downloaded the 4.3.0 bundle, use the following commands with your Entitled Registry Key:
     docker login cp.icr.io --username cp && \
 docker rm -f ibm-eam-4.3.3-bundle; \
 docker pull cp.icr.io/cp/ieam/ibm-eam-bundle:2.29.0-638 && \
 docker create --name ibm-eam-4.3.3-bundle cp.icr.io/cp/ieam/ibm-eam-bundle:2.29.0-638 bash && \
 docker cp ibm-eam-4.3.3-bundle:/ibm-eam-4.3.3-bundle.tar.gz ibm-eam-4.3.3-bundle.tar.gz && \
 tar -zxvf ibm-eam-4.3.3-bundle.tar.gz

  2. Install the hzn CLI using the instructions for your supported platform:

    • Navigate to the agent directory and unpack the agent files:

      cd ibm-eam-4.3.3-bundle/agent && \
tar -zxvf edge-packages-4.3.3.tar.gz

      • Debian Linux example:

        sudo apt-get install ./edge-packages-4.3.3/linux/deb/amd64/horizon-cli*.deb

      • Red Hat Linux example:

        sudo dnf install -yq ./edge-packages-4.3.3/linux/rpm/x86_64/horizon-cli-*.x86_64.rpm

      • macOS example:

        sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain edge-packages-4.3.3/macos/pkg/x86_64/horizon-cli.crt && \
sudo installer -pkg edge-packages-4.3.3/macos/pkg/x86_64/horizon-cli-*.pkg -target /
  3. Follow the steps in Gather edge node files to push the agent installation files into the CSS.

Upgrading the agent on edge nodes

  1. Log in to your edge node as root on a device, or as an admin on your cluster and set the horizon environment variables:

    export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
export HZN_ORG_ID=<your-exchange-organization>
export HZN_FSS_CSSURL=https://<ieam-management-hub-ingress>/edge-css/

  2. Set the required environment variables based on your cluster type (skip this step if you're upgrading a device):

    • On OCP edge clusters:

      Set the storage class the agent should use:

      oc get storageclass
export EDGE_CLUSTER_STORAGE_CLASS=<rook-ceph-cephfs-internal>

      Set the registry username to the service account name you created:

      oc get serviceaccount -n openhorizon-agent
export EDGE_CLUSTER_REGISTRY_USERNAME=<service-account-name>

      Set the registry token: 

      export EDGE_CLUSTER_REGISTRY_TOKEN=`oc serviceaccounts get-token $EDGE_CLUSTER_REGISTRY_USERNAME`

    • On k3s:

      Instruct agent-install.sh to use the default storage class:

      export EDGE_CLUSTER_STORAGE_CLASS=local-path

    • On microk8s:

      Instruct agent-install.sh to use the default storage class:

      export EDGE_CLUSTER_STORAGE_CLASS=microk8s-hostpath

  3. Pull agent-install.sh from the CSS:

    curl -u $HZN_ORG_ID/$HZN_EXCHANGE_USER_AUTH $HZN_FSS_CSSURL/api/v1/objects/IBM/agent_files/agent-install.sh/data -o agent-install.sh --insecure && chmod +x agent-install.sh

  4. Run agent-install.sh to get the updated files from CSS and configure the Horizon agent:

    • On edge devices:

      sudo -s -E ./agent-install.sh -i 'css:' -s

    • On edge clusters:

      ./agent-install.sh -D cluster -i 'css:' -s

Note: Include the -s option while running agent install to skip registration, which leaves the edge node in the same state it was in before the upgrade.

Known issues and FAQ

IEAM 4.2