Table of contents

Upgrading Regulatory Accelerator

A project administrator can upgrade the Regulatory Accelerator on IBM® Cloud Pak for Data.

Before you begin

Required role: To complete this task, you must be an administrator of the project (namespace) where you deployed the service.

Important: Before you upgrade the service, ensure that the following tasks are complete:

If you are running the upgrade on an air-gapped cluster, ensure that a Red Hat® OpenShift® administrator has completed the steps in Preparing for air-gapped upgrades to download the required files for the service.

Ensure that the Mac OS or Linux machine where you will run the commands meets the appropriate requirements for your environment:

Requirements for the machine Cluster is connected to the internet Cluster is air-gapped
Can connect to the cluster.
Is connected to the internet.  
Has the oc command-line interface.

You can download the appropriate client tools for your operating system from either Get Started with the CLI 3.11 or Getting started with the CLI 4.5. Ensure that the version is compatible with the version of Red Hat OpenShift on your cluster.

Has the Cloud Pak for Data command-line interface.

See Obtaining the installation files. Use the same version of the command-line interface each time you run the commands.

Has the updated repo.yaml file in the same directory as the Cloud Pak for Data command-line interface.

See Obtaining the installation files.

 
Has the cpd-Operating_System-workspace directory, which contains the required files.

See Preparing for air-gapped upgrades.

 

Ensure that you have the following information from your Red Hat OpenShift cluster administrator:

Required information Description
OpenShift_URL:port The URL and port number to use when logging in to your Red Hat OpenShift cluster.

Ensure that you have the appropriate credentials to log into the cluster using oc login.

Value:

Your cluster administrator should tell you whether your cluster is connected to the internet or is air-gapped.

Target_version

Needed for air-gapped upgrades only.

The version of the assembly to upgrade to.

Value:

Storage_class_name The name of the storage class that was used when you installed the service. The storage class will be used for any new persistent volumes.

Value:

Registry_location The location to store the upgraded images in the registry server.

Unless you changed the location of your registry server after you installed the service, use the same value that you specified when you installed the service.

If you are upgrading the service when you are connected to the internet, ensure that you have the appropriate credentials to push images to the registry server.

Value:

Guidance for Red Hat OpenShift registry users:
  • To determine the external route to the registry, run the appropriate command for your environment:
    • OpenShift 3.11:
      oc get route/docker-registry -n default --template {{.spec.host}}

      The command returns a route similar to docker-registry-default.apps.my_cluster_address

      Append the project name to the route. For example:
      docker-registry-default.apps.my_cluster_address/project
    • OpenShift 4.5:
      oc get route/default-route -n openshift-image-registry --template='{{ .spec.host }}'

      The command returns a route similar to default-route-openshift-image-registry.apps.my_cluster_address.

      Append the project name to the route. For example:
      default-route-openshift-image-registry.apps.my_cluster_address/project
  • When you specify a value for the Registry_location variable, ensure that you include the project name.
Registry_from_cluster The location from which pods on the cluster can pull images.

Unless you changed the location of your registry server after you installed the service, use the same value that you specified when you installed the service.

Value:

Guidance for Red Hat OpenShift registry users:
  • This is the internal name of the registry service. The default service name is:
    • OpenShift 3.11:
      docker-registry.default.svc:5000/project
    • OpenShift 4.5:
      image-registry.openshift-image-registry.svc:5000/project
  • When you specify a value for the Registry_from_cluster variable, ensure that you include the project name.
Project The project (namespace) where the service is deployed.

Value:

About this task

If you need to upgrade multiple services on your cluster, you must run the upgrades one at a time and wait until the upgrade completes before you upgrade another service. You cannot run the upgrades in parallel.

Procedure

To upgrade the service:

Run the appropriate cpd command for your environment:
Tip: For a list of all available options, enter the command: ./cpd-Operating_System upgrade --help. For a list of all current Cloud Pak for Data services and their version levels, enter the command: ./cpd-Operating_System status.
  • To upgrade the service on a cluster that can connect to the internet:
    1. Change to the directory where you placed the Cloud Pak for Data command-line interface and the repo.yaml file.
    2. Log in to your Red Hat OpenShift cluster as a project administrator:
      oc login OpenShift_URL:port
    3. Run the following command to preview the modules, versions, and dependencies that will be upgraded:
      Important: If you are using the internal Red Hat OpenShift registry and you are using the default self-signed certificate, specify the --insecure-skip-tls-verify flag to prevent x509 errors.
      ./cpd-Operating_System upgrade \
      --repo ./repo.yaml \
      --assembly iira \
      --namespace Project \
      --storageclass Storage_class_name \
      --transfer-image-to Registry_location \
      --cluster-pull-prefix Registry_from_cluster \
      --ask-push-registry-credentials \
      --dry-run

      Replace the following values:

      Variable Replace with
      Operating_System For Linux, specify linux. For Mac OS, specify darwin.
      Project Use the value provided by your cluster administrator.
      Storage_class_name Use the value provided by your cluster administrator.
      Registry_location Use the value provided by your cluster administrator.
      Registry_from_cluster Use the value provided by your cluster administrator.
    4. Rerun the previous command without the --dry-run flag to upgrade the service.
    5. Verify that the service was updated:
      ./cpd-Operating_System status \
      --namespace Project \

      Use the same values that you specified when you upgraded the service.

      Ensure that the assembly and its modules are ready and at the same version.

  • To upgrade the service on an air-gapped cluster:
    1. Change to the directory where you placed the Cloud Pak for Data command-line interface.
    2. Log in to your Red Hat OpenShift cluster as a project administrator:
      oc login OpenShift_URL:port
    3. Run the following command to preview the modules, versions, and dependencies that will be upgraded:
      Important: If you are using the internal Red Hat OpenShift registry:
      • Do not specify the --ask-pull-registry-credentials parameter.
      • If you are using the default self-signed certificate, specify the --insecure-skip-tls-verify flag to prevent x509 errors.
      ./cpd-Operating_System upgrade \
      --assembly iira \
      --version Target_version \
      --namespace Project \
      --storageclass Storage_class_name \
      --cluster-pull-prefix Registry_from_cluster \
      --ask-pull-registry-credentials \
      --load-from Image_directory_location \
      --dry-run

      Replace the following values:

      Variable Replace with
      Operating_System For Linux, specify linux. For Mac OS, specify darwin.
      Target_version Use the value provided by your cluster administrator.
      Project Use the value provided by your cluster administrator.
      Storage_class_name Use the value provided by your cluster administrator.
      Registry_from_cluster Use the value provided by your cluster administrator.
      Image_directory_location The location of the cpd-Operating_System-workspace directory.
    4. Rerun the previous cpd upgrade command without the --dry-run flag to perform the upgrade of the service.
    5. Verify that the service was updated:
      ./cpd-Operating_System status \
      --namespace Project \

      Use the same values that you specified when you upgraded the service.

      Ensure that the assembly and its modules are ready and at the same version.

Results

The upgrade will list all modules, versions, and dependencies that have been upgraded.

What to do next

After you restore the route to the platform, the service is ready to use. See Governing data to comply with regulations with Regulatory Accelerator.