Updating IBM Cloud Pak foundational services from version 3.x

Some updates of WebSphere Automation (such a version 1.6.4 to 1.7.x, 1.7.x to 1.7.5, or 1.7.5 to 1.8.0) require that you first update IBM Cloud Pak foundational services to version 4.9. Instructions are provided for both network-connected installations and installations in air gap environments.

Before you begin

Read the instructions completely before you begin updating IBM Cloud Pak foundational services. Changes to the namespace strategy in IBM Cloud Pak foundational services 4.x affect the entire cluster. Sizing requirements might also be higher after the upgrade.

Scripts are available to help you update IBM Cloud Pak foundational services to version 4.9. Download the migration scripts by using the following commands. If you have previously downloaded the scripts, download them again to make sure that you have the most recent instances. The scripts are occasionally updated.

wget https://github.com/IBM/ibm-websphere-automation/raw/main/scripts/cs4-migration.tgz
tar -xvzf cs4-migration.tgz
cd cs4-migration
Note: In the code examples, optional parameters are indicated by brackets ( [ ] ). If you use optional parameters in a command, delete the appropriate brackets. Do not include undefined optional parameters in a command.
All of the following scripts require yq version 4.18.1 or later. Run a script similar to the following one to install the latest version of yq. Set the BINARY variable for your operating system, and ensure a compatible version is installed before you continue.
BINARY=yq_linux_amd64
# BINARY=yq_linux_ppc64
# BINARY=yq_linux_s390x

wget https://github.com/mikefarah/yq/releases/latest/download/${BINARY} -O /usr/bin/yq && chmod +x /usr/bin/yq
  • Updating an OwnNamespace installation. Use this scenario if you have installed WebSphere Automation in OwnNamespace mode, and it is the only application that depends on IBM Cloud Pak foundational services in the cluster. In OwnNamespace mode, the WebSphere Automation operator and the WebSphere Automation instance are in the same namespace.
  • Updating an OwnNamespace installation when a different IBM Cloud Pak is also installed in the cluster. Use this scenario if you have installed WebSphere Automation in OwnNamespace mode, and there is another IBM Cloud Pak or IBM product that depends on the existing version of IBM Cloud Pak foundational services in the cluster.
  • Updating an AllNamespaces installation. Use this scenario if you have installed WebSphere Automation in AllNamespace mode. There can be other IBM Cloud Paks that depend on the existing version of IBM Cloud Pak foundational services in the ibm-common-services namespace in the cluster. IBM Cloud Pak foundational services is updated for the entire cluster; make sure that the other IBM Cloud Paks are compatible with IBM Cloud Pak foundational services 4.9.

Updating an OwnNamespace installation

This procedure removes IBM Cloud Pak foundational services version 3.x from the ibm-common-services namespace and installs IBM Cloud Pak foundational services version 4.9 into the WebSphere Automation instance namespace.

  1. Update IBM Cloud Pak foundational services to version 4.9 by running the following migration script.
    ./remove-ics.sh --operator-namespace WSA_OPERATOR_NAMESPACE \
                --instance-namespace WSA_INSTANCE_NAMESPACE \
                [--cert-manager-namespace CERT_MANAGER_NAMESPACE] \
                [--licensing-service-namespace LICENSING_SERVICE_NAMESPACE] \
                [--cert-manager-catalog-source CERT_MANAGER_CATALOG_SOURCE] \
                [--licensing-service-catalog-source LICENSING_SERVICE_CATALOG_SOURCE] \
                [--common-services-catalog-source COMMON_SERVICES_CATALOG_SOURCE] \
                [--common-services-upgrade-channel COMMON_SERVICES_UPGRADE_CHANNEL] \
                [--common-services-case-version COMMON_SERVICES_CASE_VERSION] \
                [--skip-checks] \
                [--allow-errors]
    Where:
    • WSA_OPERATOR_NAMESPACE is the namespace where the WebSphere Automation operator is located (for example, websphere-automation).
    • WSA_INSTANCE_NAMESPACE is the namespace where the WebSphere Automation instance is located (for example, websphere-automation).

      For OwnNamespace installations, WSA_OPERATOR_NAMESPACE and WSA_INSTANCE_NAMESPACE are the same value.

    • For air gap environments only, set the --common-services-catalog-source flag and set the value of the COMMON_SERVICES_CATALOG_SOURCE variable to opencloud-operators.
    • Other flags are optional. If they are not specified, the following default values are used.
      CERT_MANAGER_NAMESPACE = ibm-cert-manager
LICENSING_SERVICE_NAMESPACE = ibm-licensing
CERT_MANAGER_CATALOG_SOURCE = ibm-cert-manager-catalog
LICENSING_SERVICE_CATALOG_SOURCE = ibm-licensing-catalog
COMMON_SERVICES_CATALOG_SOURCE = ibm-operator-catalog
COMMON_SERVICES_UPGRADE_CHANNEL = v4.9
COMMON_SERVICES_CASE_VERSION = 4.9.0
    • The skip-checks flag causes the script to skip version checks prior to starting the upgrade. Set this flag if you do not want to check the current versions of WebSphere Automation and IBM Cloud Pak foundational services operator, for example, if you exited the upgrade script early and would like to resume the upgrade again without being blocked. The default behavior (that is, if this is not set) is for the script to check that WebSphere Automation is installed and running on the latest upgradable version (1.6.4) and running the latest upgradable IBM Cloud Pak foundational services operator (3.23.12).
    • The allow-errors flag disables termination of the script in the event of a non-zero exit code and bypasses failing commands. The default behavior (that is, if this flag is not set) is for all upgrade scripts to terminate when a command returns a non-zero exit code.

    The ibm-common-services namespace is deleted, and the WebSphere Automation namespace is ready for WebSphere Automation operator to be installed in OwnNamespace mode.

  2. Install the WebSphere Automation operator. Ensure that you specify OwnNamespace mode when you install the operator.

Updating an OwnNamespace installation when a different IBM Cloud Pak is also installed in the cluster

This procedure installs IBM Cloud Pak foundational services version 4.9 in the instance namespace for WebSphere Automation, and preserves IBM Cloud Pak foundational services version 3.x in the ibm-common-services namespace.

  1. Update IBM Cloud Pak foundational services to version 4.9 by running the following migration script.
    ./preserve-ics.sh --operator-namespace WSA_OPERATOR_NAMESPACE \ 
                  --instance-namespace WSA_INSTANCE_NAMESPACE \
                  [--cert-manager-namespace CERT_MANAGER_NAMESPACE] \
                  [--licensing-service-namespace LICENSING_SERVICE_NAMESPACE] \
                  [--common-services-control-namespace COMMON_SERVICES_CONTROL_NAMESPACE] \
                  [--cert-manager-catalog-source CERT_MANAGER_CATALOG_SOURCE] \
                  [--licensing-service-catalog-source LICENSING_SERVICE_CATALOG_SOURCE] \
                  [--common-services-catalog-source COMMON_SERVICES_CATALOG_SOURCE] \
                  [--common-services-upgrade-channel COMMON_SERVICES_UPGRADE_CHANNEL] \
                  [--common-services-case-version COMMON_SERVICES_CASE_VERSION] \
                  [--skip-checks] \
                  [--allow-errors]
    Where:
    • WSA_OPERATOR_NAMESPACE is the namespace where the WebSphere Automation operator is located (for example, websphere-automation).
    • WSA_INSTANCE_NAMESPACE is the namespace where the WebSphere Automation instance is located (for example, websphere-automation).

      For OwnNamespace installations, WSA_OPERATOR_NAMESPACE and WSA_INSTANCE_NAMESPACE are the same value.

    • For air gap environments only, set the --common-services-catalog-source flag and set the value of the COMMON_SERVICES_CATALOG_SOURCE variable to opencloud-operators.
    • Other flags are optional. If they are not specified, the following default values are used.
      CERT_MANAGER_NAMESPACE = ibm-cert-manager
LICENSING_SERVICE_NAMESPACE = ibm-licensing
COMMON_SERVICES_CONTROL_NAMESPACE = cs-control
CERT_MANAGER_CATALOG_SOURCE = ibm-cert-manager-catalog
LICENSING_SERVICE_CATALOG_SOURCE = ibm-licensing-catalog
COMMON_SERVICES_CATALOG_SOURCE = ibm-operator-catalog
COMMON_SERVICES_UPGRADE_CHANNEL = v4.9
COMMON_SERVICES_CASE_VERSION = 4.9.0
    • The skip-checks flag causes the script to skip version checks prior to starting the upgrade. Set this flag if you do not want to check the current versions of WebSphere Automation and IBM Cloud Pak foundational services operator, for example, if you exited the upgrade script early and would like to resume the upgrade again without being blocked. The default behavior (that is, if this is not set) is for the script to check that WebSphere Automation is installed and running on the latest upgradable version (1.6.4) and running the latest upgradable IBM Cloud Pak foundational services operator (3.23.12).
    • The allow-errors flag disables termination of the script in the event of a non-zero exit code and bypasses failing commands. The default behavior (that is, if this flag is not set) is for all upgrade scripts to terminate when a command returns a non-zero exit code.

    The ibm-common-services namespace now supports the other IBM Cloud Paks installed in the cluster. The WebSphere Automation instance namespace contains IBM Cloud Pak foundational services 4.9 and is ready for WebSphere Automation operator to be installed in OwnNamespace mode.

  2. Install the WebSphere Automation operator. Ensure that you specify OwnNamespace mode when you install the operator.

Updating an AllNamespaces installation

This procedure updates IBM Cloud Pak foundational services in the ibm-common-services namespace to version 4.9. This procedure causes IBM Cloud Pak foundational services to be temporarily unavailable, as well as any applications that depend on IBM Cloud Pak foundational services.

Note: Before proceeding, check the prerequisites for the other IBM Cloud Paks in the cluster. Updating to a later version of IBM Cloud Pak foundational services might cause loss of functionality.
  1. Update IBM Cloud Pak foundational services to version 4.9 by running the following migration script.
    ./all-ns-upgrade-ics.sh --operator-namespace openshift-operators \
                        --instance-namespace WSA_INSTANCE_NAMESPACE \
                        [--cert-manager-namespace CERT_MANAGER_NAMESPACE] \
                        [--licensing-service-namespace LICENSING_SERVICE_NAMESPACE] \
                        [--cert-manager-catalog-source CERT_MANAGER_CATALOG_SOURCE] \
                        [--licensing-service-catalog-source LICENSING_SERVICE_CATALOG_SOURCE] \
                        [--common-services-catalog-source COMMON_SERVICES_CATALOG_SOURCE] \
                        [--common-services-upgrade-channel COMMON_SERVICES_UPGRADE_CHANNEL] \
                        [--common-services-case-version COMMON_SERVICES_CASE_VERSION] \
                        [--skip-checks] \
                        [--allow-errors]
    Where:
    • WSA_INSTANCE_NAMESPACE is the instance namespace for WebSphere Automation (for example, websphere-automation).
    • For air gap environments only, set the --common-services-catalog-source flag and set the value of the COMMON_SERVICES_CATALOG_SOURCE variable to opencloud-operators.
    • Other flags are optional. If they are not specified, the following default values are used.
      CERT_MANAGER_NAMESPACE = ibm-cert-manager
LICENSING_SERVICE_NAMESPACE = ibm-licensing
CERT_MANAGER_CATALOG_SOURCE = ibm-cert-manager-catalog
LICENSING_SERVICE_CATALOG_SOURCE = ibm-licensing-catalog
COMMON_SERVICES_CATALOG_SOURCE = ibm-operator-catalog
COMMON_SERVICES_UPGRADE_CHANNEL = v4.9
COMMON_SERVICES_CASE_VERSION = 4.9.0
    • The skip-checks flag causes the script to skip version checks prior to starting the upgrade. Set this flag if you do not want to check the current versions of WebSphere Automation and IBM Cloud Pak foundational services operator, for example, if you exited the upgrade script early and would like to resume the upgrade again without being blocked. The default behavior (that is, if this is not set) is for the script to check that WebSphere Automation is installed and running on the latest upgradable version (1.6.4) and running the latest upgradable IBM Cloud Pak foundational services operator (3.23.12).
    • The allow-errors flag disables termination of the script in the event of a non-zero exit code and bypasses failing commands. The default behavior (that is, if this flag is not set) is for all upgrade scripts to terminate when a command returns a non-zero exit code.

    The openshift-operators namespace now has IBM Cloud Pak foundational services 4.9, and the WebSphere Automation instance namespace is ready for the WebSphere Automation operator to be installed in AllNamespaces mode.

  2. Install the WebSphere Automation operator. Ensure that you specify AllNamespaces mode when you install the operator.
  3. If other IBM Cloud Paks or IBM products do not support IBM Cloud Pak foundational services, update them to a version that supports IBM Cloud Pak foundational services 4.9.