Preparing for air-gapped installations

If you plan to install 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 installation.

Before you begin

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

Before you prepare for air-gapped installations:
  • Ensure that the installation node is connected to the internet.
  • Download the Cloud Pak for Data command-line interface to the machine from which you will run the commands. See Obtaining the installation files.
  • If you are using the internal registry server on Red Hat® OpenShift®, create the project (namespace) where you will deploy the software. The project must exist before you push the images to the registry server.

About this task

You will download the required files for the software that you want to install 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 installing multiple services on Cloud Pak for Data, you must repeat this task for each service that you want to install.

  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 installation.

    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. (These files will be used only if you run the cpd-cli adm command with the --apply parameter.)

  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. If you are using the Red Hat OpenShift internal registry server, ensure that the Red Hat OpenShift project (namespace) where you plan to install the software exists.

    If the project doesn't exist and you try to push the images to the registry server, you will get the following error: unable to retrieve auth token: invalid username/password: unauthorized: authentication required

    If the project doesn't exist, To create the project, run the following command:
    oc new-project project_name
  5. 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 install 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. 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 specify in the download.yaml file might have dependencies on one or more other assemblies. You can run the ./cpd-cli delta-images command with the --dry-run flag to see the complete list of dependent 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 latest required assembly. You can either:

    • Ensure that you get exactly the versions that you want by specifying all of the dependent assemblies at the required versions in the download.yaml file.

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

    • Let the cpd-cli download the latest version of any dependent assemblies that are not specified in 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.
  2. Change to the directory where you extracted the Cloud Pak for Data installation command-line interface.
  3. 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 \
--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.)

  4. 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.
  5. If you are using the Red Hat OpenShift internal registry server, ensure that the Red Hat OpenShift project (namespace) where you plan to install the software exists.

    If the project doesn't exist and you try to push the images to the registry server, you will get the following error: unable to retrieve auth token: invalid username/password: unauthorized: authentication required

    If the project doesn't exist, To create the project, run the following command:
    oc new-project project_name
  6. 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 install the software.

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

If you download the images by running the delta-images command, the installation 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 install.
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 installed.
Storage_class_name The storage class to use for the software.

For information about which storage classes are supported for each service, see System requirements for services.
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 install the Cloud Pak for Data control plane, follow the instructions in Installing the Cloud Pak for Data control plane from cpd-cli.

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