Preparing for air-gapped upgrades

If you plan to upgrade IBM® Cloud Pak for Data or a service on an air-gapped cluster, a cluster administrator must make the required files available to the cluster before the upgrade.

Before you begin

Required role: To complete this task, you must be a cluster administrator.

Before you prepare for air-gapped upgrades:

About this task

You will download the required files for the software that you want to upgrade and then transfer the files to a machine that is accessible from the cluster.

Tip: By default, the commands to download the software use the /var/tmp directory for temporary storage. However, if you don't have sufficient space in your /var/tmp directory, the download fails.

If you don't have space in the /var/tmp directory, you can specify a different directory with more storage.

Run the following command to set the temporary directory on your command-line session:
export TMPDIR=directory_with_space

Replace directory_with_space with the name of a directory on your local file system.

This environment variable persists until you close your command-line session.

Procedure

  1. Download the files by completing the appropriate task for your environment:
  2. Complete the tasks listed in What to do next.

Downloading the latest version of the software

If you are upgrading multiple services on Cloud Pak for Data, you must repeat this task for each service that you want to upgrade.

  1. Change to the directory where you extracted the Cloud Pak for Data installation command-line interface.
  2. Run the following command to download the required files to your local machine.
    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-cli preload-images \
--repo repo.yaml \
--assembly Assembly_name \
--arch Cluster_architecture \
--action download
    Refresh 2 or later If you want to download the latest patches that are associated with the assembly, add the following line to your command after the --arch flag: 
    --include-patches \
    Tip: The patches that are downloaded depend on the software:
    • There might not be any patches that are associated with the software that you are downloading.
    • There might be multiple patches if the software requires prerequisite patches.
    After you run the command to download the files to your local machine, review the contents of the cpd-cli-workspace directory to determine which patches were downloaded:
    • If the command downloaded a single patch, install the patch after you install the software.
    • If the command downloaded multiple patches, install the software then install the patches in the correct order.

    For information about the patches, see Available patches.

    Replace the following values:

    Variable Replace with
    Assembly_name For the Cloud Pak for Data control plane, specify lite. For a service, specify the assembly name of the service.
    Cluster_architecture Specify the architecture of your cluster hardware:
    • For x86-64 hardware, remove this flag or specify x86_64.
    • For POWER hardware, specify ppc64le.
    • For IBM Z® hardware, specify s390x.

    Not all services are available on POWER or IBM Z. For information about which services run on POWER, see System requirements for services.

    The files are saved to the cpd-cli-workspace directory, which is created in the directory that contains the Cloud Pak for Data command-line interface.

    The directory contains the images, assembly manifest files, module manifest files, charts, and other artifacts that are required for the upgrade.

    Depending on the assembly that you specify, the directory might contain one or more directories that contain YAML files that describe the changes that must be made to the cluster. When you set up the cluster, you can optionally use these files to automatically apply the changes to your cluster.

  3. Transfer the following items to a machine that can connect to the cluster and to the registry server:
    • The cpd-cli-workspace directory. Ensure that the directory structure remains unchanged.
    • A copy of the Cloud Pak for Data installation command-line interface. Ensure that the command-line interface is compatible with the machine that you are transferring the files to and that it is the same version as the command-line interface that you ran in the preceding steps.
  4. From the machine that can connect to the cluster, run the following command to push the images to the registry server.
    Important: If you are using the internal registry server on Red Hat OpenShift:
    • Log in to the oc command-line interface before you push the images:
      oc login
    • If you are using the default self-signed certificate, specify the --insecure-skip-tls-verify parameter to prevent x509 errors. 
    ./cpd-cli preload-images \  
--assembly Assembly_name \
--arch Cluster_architecture \
--action push \
--ask-push-registry-credentials \
--load-from Image_directory_location \
--transfer-image-to Registry_location

    Replace the following values:

    Variable Replace with
    Assembly_name Use the value that you specified when you ran the cpd preload-images command with the --action download parameter.
    Cluster_architecture Specify the architecture of your cluster hardware:
    • For x86-64 hardware, remove this flag or specify x86_64.
    • For POWER hardware, specify ppc64le.
    • For IBM Z hardware, specify s390x.

    Not all services are available on POWER or IBM Z. For information about which services run on POWER, see System requirements for services.
    Image_directory_location The location of the cpd-cli-workspace directory.
    Registry_location The location to store the images on the registry server.
    You can run the following command to find the route to the registry:
    oc get routes --all-namespaces

    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 or 4.6:
        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.

Downloading a specific version of the software

In general, it is recommended that you upgrade to the latest version of the Cloud Pak for Data control plane and services on your cluster. However, if you have tested and validated a specific version of the software and want to install that software on another cluster, you can use the following steps to download the appropriate versions of the software.

  1. From a machine that can connect to the cluster, change to the directory where you extracted the Cloud Pak for Data installation 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 generate a YAML file called config.yaml that contains information about the assemblies that are currently installed:
    ./cpd-cli collect-config \
--namespace Project

    Replace Project with the name of the project where you plan to upgrade the software.

    The ./cpd-cli delta-images command uses the information in this file to ensure that the version dependencies are handled properly when you download the versions of the assemblies that you want to upgrade to.

  4. Transfer the config.yaml file to a machine that can connect to the internet.

  5. On a machine that can connect to the internet, create a file called download.yaml that lists the assemblies that you want to download. For each assembly, include the architecture and version of the software that you want to install.

    For example, the following YAML file will download:
    • Version 3.5.1 of the Cloud Pak for Data control plane for x86-64 hardware.
    • Version 3.5.0 of the Watson™ Studio service for x86-64 hardware.
    • Version 3.5.0 of the Watson Machine Learning service for x86-64 hardware.
    • Version 3.5.1 of the Cloud Pak for Data common core services for x86-64 hardware.
    assemblies:
- name: lite
  arch: x86_64
  version: 3.5.1
- name: wsl
  arch: x86_64
  version: 3.5.0
- name: wml
  arch: x86_64
  version: 3.5.0
- name: common-core-services
  arch: x86_64
  version: 3.5.1
    Important: Some of the assemblies that you include in the download.yaml file might have dependencies on one or more other assemblies. If any assemblies that you specify require an assembly that is not specified in the file, the ./cpd-cli delta-images command will download the required assembly. However, the command might not download the version of the assembly that you want. The version that is downloaded depends on the flags that you specify when you run the ./cpd-cli delta-images command:
    • If you specify the --latest-dependency flag, the latest version of the unlisted assembly will be downloaded.
    • If you do not specify the --latest-dependency flag, the minimum version of the unlisted assembly will be downloaded.

    If you want to ensure that you have the correct versions of each assembly, use the --dry-run flag when you run the ./cpd-cli delta-images command. This flag returns the full list of assemblies and versions that will be downloaded. If anything looks incorrect, update the contents of the download.yaml file.

    Use the following resources to determine the contents of the YAML file:
    Parameter Where to find information
    name For the control plane, specify lite.

    For services, the assembly names are available in the service installation documentation. For details, see Services and integrations.
    arch The control plane is supported on x86-64, POWER, and IBM Z hardware.

    For services, information on supported hardware is in the System requirements for services documentation.

    Specify the appropriate value:

    • For x86-64 hardware, specify x86_64.
    • For POWER hardware, specify ppc64le.
    • For IBM Z hardware, specify s390x.
    version For the control plane, see System requirements for IBM Cloud Pak for Data.

    For services, information on the available assembly versions is in the System requirements for services documentation.
  6. Change to the directory where you extracted the Cloud Pak for Data installation command-line interface.
  7. Run the following command to download the required files to your local machine.
    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-cli delta-images \
--repo repo.yaml \
--assembly-list download.yaml \
--config-yaml config.yaml \
--action download
    Tip: If you want to preview which assemblies will be downloaded, add the following flag to the end of the command:
    --dry-run

    If you are satisfied that the assemblies are correct, remove the --dry-run flag and run the command again.

    Important: If you run this command more than once, it will remove any files from the previous run before downloading the files in the download.yaml. Ensure that your download.yaml file includes all of the assemblies that you want to install at the correct version.

    The files are saved to the cpd-cli-workspace directory, which is created in the directory that contains the Cloud Pak for Data command-line interface.

    The directory contains the images, assembly manifest files, module manifest files, charts, and other artifacts that are required for installation.

    Depending on the assemblies that you specified in download.yaml, the directory might contain one or more directories that contain YAML files that describe the changes that must be made to the cluster. When you set up the cluster, you can optionally use these files to automatically apply the changes to your cluster. (These files will be used only if you run the cpd-cli adm command with the --apply parameter.)

  8. Transfer the following items to a machine that can connect to the cluster and to the registry server:
    • The cpd-cli-workspace directory. Ensure that the directory structure remains unchanged.
    • A copy of the Cloud Pak for Data installation command-line interface. Ensure that the command-line interface is compatible with the machine that you are transferring the files to and that it is the same version as the command-line interface that you ran in the preceding steps.
  9. From the machine that can connect to the cluster, run the following command to push the images to the registry server.
    Important: If you are using the internal registry server on Red Hat OpenShift:
    • Log in to the oc command-line interface before you push the images:
      oc login
    • If you are using the default self-signed certificate, specify the --insecure-skip-tls-verify parameter to prevent x509 errors. 
    ./cpd-cli delta-images \
--load-from Image_directory_location \
--action push \
--transfer-image-to Registry_location \
--ask-push-registry-credentials
    Tip: You can optionally preview the images and versions that will be pushed to the registry server by adding the following flag to the command:
    --dry-run

    If you are satisfied that the images are correct, remove the --dry-run flag and run the command again.

    Replace the following values:

    Variable Replace with
    Image_directory_location The location of the cpd-cli-workspace directory.
    Registry_location The location to store the images on the registry server.
    You can run the following command to find the route to the registry:
    oc get routes --all-namespaces

    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 or 4.6:
        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.

What to do next

Provide the following information to the person who will upgrade the software.

Required information Description
Download method If you used the delta-images command to download the images, let the person who will upgrade the software know.

If you download the images by running the delta-images command, the upgrade command cannot include the --latest-dependency flag.
OpenShift_URL:port The URL to use when logging in to the OpenShift cluster.
Assembly_name The name of the assembly to upgrade.
Cluster_architecture The architecture of your cluster hardware.
  • For x86-64 hardware, the value is x86_64. If you do not specify the architecture, the installation assumes that your cluster uses x86-64 hardware.
  • For POWER hardware, the value is ppc64le.
    • For IBM Z hardware, the value is s390x.

Not all services are available on POWER or IBM Z. For information about which services run on POWER, see System requirements for services.
Project The project where the software will be upgraded.
Storage_class_name Version 3.5.1 of the cpd-cli only. The storage class to use for the software.

For information about which storage classes are supported for each service, see System requirements for services.

When you use Version 3.5.2 of the cpd-cli, the cpd-cli upgrade command uses the storage class that was specified during installation.
Registry_location The location of the images that you pushed to the registry server.
Registry_from_cluster The location from which pods on the cluster can pull images.

Guidance for Red Hat OpenShift registry users:

You can run the following command to get the internal name of the Red Hat OpenShift registry service:
oc registry info --internal=true
  • The default service name is:
    • OpenShift 3.11:
      docker-registry.default.svc:5000/project
    • OpenShift 4.5 or 4.6:
      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.
Image_directory_location The location of the cpd-cli-workspace directory.

To upgrade the Cloud Pak for Data control plane, follow the instructions in Upgrading the control plane.

To upgrade a service, follow the appropriate instructions for the service. For services provided by IBM, you can find the installation instructions for each service in: