Upgrading Open Data for Industries from Version 4.0 to Version 4.5

Before you begin

Ensure that the cluster meets the minimum requirements for Open Data for Industries. For details, see System requirements.

Also ensure that a cluster administrator completed the required per-installation for your environment.

1. The latest Cloud Pak for Data refresh is installed. For more information, see Upgrading from IBM Cloud Pak for Data Version 4.0.
2. For environments that use a private container registry, such as air-gapped environments, the Open Data for Industries software images are mirrored to the private container registry. For more information, see Mirroring images to a private container registry.
3. To update the catalog source for Open Data for Industries follow the guidance in Upgrading catalog sources.
   1. Download the CASE package for Open Data for Industries with the following command:

      cloudctl case save \
      --repo ${PATH_CASE_REPO} \
      --case ibm-osdu \
      --version 4.0.0 \
      --outputdir ${OFFLINEDIR_CPD}

   2. Create the catalog source for Open Data for Industries using the following command:

      cloudctl case launch \
        --case ${OFFLINEDIR_CPD}/ibm-osdu-4.0.0.tgz \
        --inventory osduOperatorSetup \
        --namespace ${PROJECT_CATSRC} \
        --action install-catalog \
          --args "--inputDir ${OFFLINEDIR_CPD} --recursive"

   3. Ensure that the ibm-osdu-operator-catalog is READY with the flowing command:

      oc get catalogsource -n ${PROJECT_CATSRC} ibm-osdu-operator-catalog \
      -o jsonpath='{.status.connectionState.lastObservedState} {"\n"}'

4. To upgrade the operator for Open Data for Industries follow the guidance in Upgrading operator subscriptions with the following Open Data for Industries commands:
   1. Create a config map that is used by the osdu operator for namespace resolution:

      oc create configmap namespace-scope --from-literal=namespaces=<namespace>

   2. Determine which version of the operator is installed on the cluster:

      oc get sub --namespace ${PROJECT_CPD_OPS} osdu-ibm-operator \
      -o jsonpath='{.status.installedCSV} {"\n"}'
      

      If the command returns osdu-ibm-operator.v3.0.0, complete the next step to update the operator subscription.

   3. Run the following command to update the channel in the operator subscription:

      oc patch subscription osdu-ibm-operator \
      --namespace ${PROJECT_CPD_OPS} \
      --type merge \
      --patch '{"spec": {"channel":"v2.0"}}'
      

   4. Run the following command to confirm that the subscription was triggered:

      oc get sub --namespace ${PROJECT_CPD_OPS} osdu-ibm-operator \
      -o jsonpath='{.status.installedCSV} {"\n"}'
      

      Verify that the command returns osdu-ibm-operator.v4.0.0.

   5. Run the following command to confirm that the cluster service version (CSV) is ready:

      oc get csv -n ${PROJECT_CPD_OPS} osdu-ibm-operator \
      -o jsonpath='{ .status.phase } : { .status.message} {"\n"}'
      

      Verify that the command returns Succeeded : install strategy completed with no errors.

   6. Run the following command to confirm that the operator is ready:

      oc get deployments -n ${PROJECT_CPD_OPS}  -l olm.owner="osdu-ibm-operator.v4.0.0" \
      -o jsonpath="{.items[0].status.availableReplicas} {'\n'}"
      

      Verify that the command returns an integer greater than or equal to 1. If the command returns 0, wait for the deployment to become available.

5. Since the supporting utilities operators and osdu operator are in the same namespace, you need to manually approve the operator upgrade.
   1. Log in to the Red Hat® OpenShift Container Platform as administrator.
   2. Choose Installed operators.
   3. Search for IBM OSDU operator and click on it.
   4. Go to Subscription page. In the Update Status section you will see one manual approval pending.
   5. Approve the manual InstallPlan in the pop-up window.

If these tasks are not complete, the Open Data for Industries upgrade will fail.

Procedure

Complete the following tasks to upgrade Open Data for Industries:

1. Upgrading the service
2. Verifying the upgrade
3. Choosing a service upgrade plan
4. What to do next

Upgrading the service

To upgrade Open Data for Industries:

1. Log in to Red Hat OpenShift Container Platform as a user with sufficient permissions to complete the task:

   oc login OpenShift_URL:port

2. Edit the OSDU custom resource:

   oc edit OSDU osdu-sample \
   --namespace project-name

3. Update the version entry to 4.0.0.
4. Save your changes and exit. For example, if you are using vi, hit Esc and then enter :wq.

When you update the custom resource, the Open Data for Industries operator upgrades Open Data for Industries.

Verifying the upgrade

The Open Data for Industries operator continually monitors the contents of the custom resource and updates the microservices that comprise Open Data for Industries as needed. The OSDU microservice is defined by the osdu-sample custom resource. Open Data for Industries is upgraded when the OSDU status is Completed.

To check the status of the upgrade:

1. Change to the project where Open Data for Industries is installed:

   oc project project-name

2. Get the status of Open Data for Industries (osdu-sample):

   oc get OSDU osdu-sample -o jsonpath='{.status.Status} {"\n"}'

   Open Data for Industries is ready when the command returns Completed.

Choosing a service upgrade plan

You can choose how Open Data for Industries is upgraded when you install a newer version of the Open Data for Industries operator on the cluster.

Automatic upgrade (recommended)

If you want Open Data for Industries to be automatically upgraded when you install a newer version of the Open Data for Industries operator on the cluster, remove the version entry from the OSDU custom resource.

To remove the version entry, run the following command. You must update the command with the appropriate project name before you run the command.

oc patch OSDU osdu-sample \
--namespace  project-name \
--type=json \
--patch '[{ "op": "remove", "path": "/spec/version" }]'

Manual upgrade

If you want to manually upgrade Open Data for Industries when you install a newer version of the Open Data for Industries operator, you can optionally pin the installation to a specific version in the OSDU custom resource.

For a list of operand versions supported by the Open Data for Industries operator, see Operator and operand versions.

The following command adds or updates the version entry to pin the installation at 4.0.0. You must update the command with the appropriate project name and version before you run the command.

oc patch OSDU osdu-sample \
--namespace project-name \
--type=merge \
--patch '{"spec": {"version":"4.0.0"}}'

Rolling back the upgrade

If you are running Open Data for Industries on Cloud Pak for Data Version 4.0.x, you can roll back Open Data for Industries to the previous refresh after you upgrade.

To roll back to the previous version of Open Data for Industries:

1. Update the version entry in the OSDU custom resource to specify the previous version.

   The following command adds or updates the version entry to 3.0.0, the previous refresh of Open Data for Industries. You must update the command with the appropriate project name and version before you run the command.

   oc patch OSDU osdu-sample \
   --namespace project-name \
   --type=merge \
   --patch '{"spec": {"version":"3.0.0"}}'

2. Confirm that the rollback was successful:
   1. Get the status of Open Data for Industries:

      oc get OSDU osdu-sample \
      --namespace project-name \
      -o jsonpath='{.status.Status} {"\n"}'

      Open Data for Industries is ready when the command returns Completed.

   2. Get the version of Open Data for Industries:

      oc get OSDU osdu-sample \
      --namespace project-name \
      -o jsonpath='{.status.Version} {"\n"}'

What to do next

• Configure and validate your environment.