Preparing an offline cluster for installation in an airgap environment by using a portable compute device

If your cluster has no internet connectivity, you can use a portable device, such as a laptop, to store the product code and images and transfer them to a local, airgap network. You do not need a bastion device to install in your airgap environment.

  1. Ensure that your cluster meets the prerequisites
  2. Prepare a local Docker registry
  3. Prepare a portable host
  4. Create environment variables for the installer and image inventory
  5. Download the IBM Cloud Pak for Multicloud Management installer and image inventory
  6. Create the portable Docker registry
  7. Mirror the images to the portable Docker registry
    1. Obtain the entitlement key
    2. Mirror the images
  8. Connect the portable host to the airgap network
    1. Log in to the OpenShift Container Platform cluster as a cluster administrator
    2. Configure the cluster and mirror the images
    3. Create the IBM Cloud Pak for Multicloud Management and common services catalog sources
  9. Create the entitled registry secret
  10. Install the IBM Cloud Pak after your cluster is prepared

Ensure that your cluster meets the prerequisites

Check cluster health

Run the following checks before you start the IBM Cloud Pak for Multicloud Management installation procedure. To resolve any issue, contact OpenShift Container Platform support Opens in a new tab.

Prepare a local Docker registry

You need a local, Docker registry for mirroring all images in your local environment. You can use an existing registry or create a registry. The registry that you use must meet the following requirements:

If you need to create a registry, you can do so by completing the steps in the following OpenShift Container Platform documentation:

You must configure the registry that you are using. See Configure the portable Docker registry.

Configure the local Docker registry

Configure the Docker registry.

Note: If the user account that you are going to use in the Mirror the images and configure the cluster step supports auto-creation of namespaces, then you do not need to complete the following step to create the registry namespaces. The namespaces are automatically created when you mirror the images.

  1. Create registry namespaces.

    Create a separate registry namespace for each public registry source.

  2. Verify that each namespace meets the following requirements:

Prepare a portable host

Prepare a portable host that can be physically connected to the internet and to the airgap network with access to the OpenShift Container Platform cluster and the local Docker registry. The portable host must be on a Linux® x86_64 platform with any operating system that the IBM Cloud Pak® CLI and the OpenShift Container Platform CLI support.

The portable host must have sufficient storage to hold all of the software that is to be transferred to the local Docker registry.

Complete these steps on your portable host:

  1. Install Docker or Podman. See the following required versions:

  2. Install httpd-tools.

    yum install httpd-tools

  3. Install the IBM Cloud Pak® CLI. Install the latest version of the binary file for your platform. For more information, see cloud-pak-cli Opens in a new tab. Note: You can install IBM Cloud Pak® CLI Version 3.4.4 or higher in your IBM Cloud Pak for Multicloud Management cluster. However, installing the latest version is ideal.

    1. Download the binary file.
      wget https://github.com/IBM/cloud-pak-cli/releases/latest/download/<binary-file-name>
      For example, wget https://github.com/IBM/cloud-pak-cli/releases/latest/download/cloudctl-linux-amd64.tar.gz.
    2. Extract the binary file.
      tar -xf <binary-file-name>
    3. Run the following commands to modify and move the file.
      chmod 755 <file-name>
mv <file-name> /usr/local/bin/cloudctl
    4. Confirm that cloudctl is installed:
      cloudctl --help
      The cloudctl usage is displayed.

  4. Install the oc OpenShift Container Platform CLI tool. For more information, see OpenShift Container Platform CLI tools.

  5. Install the skopeo CLI version 1.1.1 or higher. For more information, see Installing skopeo from packages Opens in a new tab.

  6. Create a directory that serves as the offline store, and set environment variable for this offline directory. The following is an example directory. This example is used in the subsequent steps.

    mkdir $HOME/<offline_folder>
export OFFLINE_DIR=$HOME/<offline_folder>

    You need to designate <offline_folder> with the real directory that you created as the offline store.

    Notes:

Create environment variables for the installer and image inventory

Create the following environment variables with the installer CASE name and the image inventory.

export CASE_ARCHIVE=ibm-cp-management-100.2.0+2.2.7.tgz
export CASE_INVENTORY_SETUP=cp4mcmInstallerSetup

Note: This CASE version installs the latest fix pack version of IBM Cloud Pak for Multicloud Management. This fix pack includes the same functionality of the base version with additional fixes to address known issues.

Download the IBM Cloud Pak for Multicloud Management installer and image inventory

Download the IBM Cloud Pak for Multicloud Management installer and image inventory to the portable host.

cloudctl case save \
  --case https://github.com/IBM/cloud-pak/raw/master/repo/case/${CASE_ARCHIVE} \
  --outputdir $OFFLINE_DIR/ \
  --tolerance 1

Note: The directory $OFFLINE_DIR should be new, and do not reuse the existing offline directory that contains previous release installer and image inventory.

Create the portable Docker registry

Complete these steps to create the Docker registry.

  1. Create environment variables with the image and portable Docker registry information.

    export PORTABLE_DOCKER_REGISTRY=<IP_or_FQDN_of_portable_Docker_registry>:<port>
export PORTABLE_DOCKER_USER=<username>
export PORTABLE_DOCKER_PASSWORD=<password>

    Following are the parameter descriptions:

  2. Create the Docker registry.

    cloudctl case launch \
  --case $OFFLINE_DIR/${CASE_ARCHIVE} \
  --inventory ${CASE_INVENTORY_SETUP} \
  --action create-registry-airgap \
  --args "--registry ${PORTABLE_DOCKER_REGISTRY} --user ${PORTABLE_DOCKER_USER} --pass ${PORTABLE_DOCKER_PASSWORD} --registryDir $HOME/cp4mcm-registry" \
  --tolerance 1

    Note: The "--registryDir" parameter is used to specify the local directory for the Docker registry. You can specify any directory that you want to use.

  3. Verify that the registry is available.

    curl -u ${PORTABLE_DOCKER_USER}:${PORTABLE_DOCKER_PASSWORD} -k https://${PORTABLE_DOCKER_REGISTRY}/v2/_catalog

    If the request is successful, you see the following response:

    {"repositories":[]}

Mirror the images to the portable Docker registry

Connect the portable host to the internet and disconnect it from the local, airgap network.

Complete one of these steps on your portable host:

Obtain the entitlement key

Obtain the entitlement key that is assigned to your ID.

  1. Log in to MyIBM Container Software Library Opens in a new tab with the IBMid and password that are associated with the entitled software.
  2. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard. You use this key as the registry password in the Mirror the images and configure the cluster section.

Download images from IBM Passport Advantage

Before you download images, ensure that there is sufficient disk space available on the bastion host. See the Prerequisites.

To download images from Passport Advantage, see Passport Advantage part numbers for part numbers and links to the IBM® Passport Advantage® Opens in a new tab website.

  1. Download the images.

  2. Create an environment variable with the file name and path.

    export PPA_TAR=<full_path_to_the_TAR_file>

Mirror the images

Complete these steps to mirror the images:

Note: Do not use the tilde within double quotation marks in any command. For example, do not use args "--registry <registry> --user <registry userid> --pass <registry password> --inputDir ~/offline". The tilde does not expand and your commands might fail.

  1. Store authentication credentials for all source Docker registries. The IBM Cloud Pak for Multicloud Management installer is stored in a public registry and does not require authentication. However, most of the components, including third-party components, require one or more authenticated registries. The following registry requires authentication:

  2. Configure an authentication secret for the portable Docker registry. Note: This step needs to be done only one time.

    cloudctl case launch \
  --case $OFFLINE_DIR/${CASE_ARCHIVE} \
  --inventory ${CASE_INVENTORY_SETUP} \
  --action configure-creds-airgap \
  --args "--registry ${PORTABLE_DOCKER_REGISTRY} --user ${PORTABLE_DOCKER_USER} --pass ${PORTABLE_DOCKER_PASSWORD}" \
  --tolerance 1

    The command stores and caches the registry credentials in a file on your file system in the $HOME/.airgap/secrets location.

  3. Mirror the images to the portable registry.

Connect the portable host to the airgap network

Connect the portable host to the airgap network and disconnect it from the internet.

The portable host must have access to the local Docker registry and to the OpenShift Container Platform cluster.

Log in to the OpenShift Container Platform cluster as a cluster administrator

Following is an example command to log in to the OpenShift Container Platform cluster:

oc login <cluster host:port> --username=<cluster admin user> --password=<cluster admin password>

Configure the cluster and mirror the images

Complete these steps to create the installation resources and to mirror the images:

  1. Create environment variables with namespaces to install the IBM Cloud Pak®. Then, create the namespaces. In the following command, replace <namespace-to-install-the-IBM Cloud Pak> with the namespace for your IBM Cloud Pak. For example, you can replace it with cp4mcm.

    export NAMESPACE=<namespace-to-install-the-IBM Cloud Pak>
export CS_NAMESPACE=common-service
oc create namespace ${NAMESPACE}
oc create namespace ${CS_NAMESPACE}

  2. Create environment variables with the portable and local Docker registry connection information.

    export PORTABLE_DOCKER_REGISTRY=<IP_or_FQDN_of_portable_Docker_registry>:<port>
export LOCAL_DOCKER_REGISTRY=<IP_or_FQDN_of_local_docker_registry>:<port>
export LOCAL_DOCKER_USER=<username>
export LOCAL_DOCKER_PASSWORD=<password>

  3. Configure an authentication secret for the local Docker registry. Note: This step needs to be done only one time.

    cloudctl case launch \
  --case $OFFLINE_DIR/${CASE_ARCHIVE} \
  --inventory ${CASE_INVENTORY_SETUP} \
  --action configure-creds-airgap \
  --args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass ${LOCAL_DOCKER_PASSWORD}" \
  --tolerance 1

    The command stores and caches the registry credentials in a file on your file system in the $HOME/.airgap/secrets location.

  4. Mirror the images from the portable host Docker registry to the local registry.

    cloudctl case launch \
  --case $OFFLINE_DIR/${CASE_ARCHIVE} \
  --inventory ${CASE_INVENTORY_SETUP} \
  --action mirror-images \
  --args "--fromRegistry ${PORTABLE_DOCKER_REGISTRY} --registry ${LOCAL_DOCKER_REGISTRY} --inputDir $OFFLINE_DIR" \
  --tolerance 1

  5. Configure a global image pull secret and ImageContentSourcePolicy.

    cloudctl case launch \
  --case $OFFLINE_DIR/${CASE_ARCHIVE} \
  --inventory ${CASE_INVENTORY_SETUP} \
  --action configure-cluster-airgap \
  --namespace ${NAMESPACE} \
  --args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass ${LOCAL_DOCKER_PASSWORD} --inputDir $OFFLINE_DIR" \
  --tolerance 1

  6. Verify that the ImageContentSourcePolicy resource is created.

    oc get imageContentSourcePolicy ibm-management-installer

  7. Optional: If you are using an insecure registry, you must add the local registry to the cluster insecureRegistries list.

    oc patch image.config.openshift.io/cluster --type=merge -p '{"spec":{"registrySources":{"insecureRegistries":["'${LOCAL_DOCKER_REGISTRY}'"]}}}'

  8. Verify the MachineConfigPools (mcp). The MachineConfigPool reports whether all nodes are successfully updated and whether any nodes are degraded.
    If the MachineConfigPool update is successful, the changes from the imageContentSourcePolicy and global image pull secret are rolled out to all nodes successfully.
    Note: If you only verify whether all nodes are ready instead of using the MachineConfigPool, you might not detect whether something is preventing the rollout of configurations to your cluster nodes.
    For example, to use the MachineConfigPool, run the following command: 

    oc get mcp

    The results from this command can resemble the following sample output: 

    NAME     CONFIG                                             UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
master   rendered-master-701c25357febdcc8c625d9537075074b   True      False      False      3              3                   3                     0                      2d1h
worker   rendered-worker-65da0d7b7b6cbbc91b818dab7a49e8c4   True      False      False      3              3                   3                     0                      2d1h

Create the IBM Cloud Pak for Multicloud Management and common services catalog sources

  1. Create a catalog source for IBM Cloud Pak for Multicloud Management and common services.

    cloudctl case launch \
  --case $OFFLINE_DIR/${CASE_ARCHIVE} \
  --inventory ${CASE_INVENTORY_SETUP} \
  --action install-catalog \
  --namespace ${NAMESPACE} \
  --args "--registry ${LOCAL_DOCKER_REGISTRY} --inputDir $OFFLINE_DIR --recursive" \
  --tolerance 1

  2. Verify that the package manifests for ibm-management-orchestrator and ibm-common-service-operator are available. It might take a few minutes for the manifests to be available.

    oc get packagemanifest ibm-management-orchestrator
oc get packagemanifest ibm-common-service-operator

Create the entitled registry secret

If you plan to install the IBM Cloud Pak for Multicloud Management by using the console, you need to create the entitled registry secret. Use the entitled registry key value that you got in the Obtain the entitlement key step.

Complete these steps to create the secret:

  1. Log in to your OpenShift Container Platform cluster by using the oc login command.

  2. Create these environment variables.

    export ENTITLED_REGISTRY=cp.icr.io

    export ENTITLED_REGISTRY_USER=cp

    export ENTITLED_REGISTRY_KEY=<entitlement_key>

  3. Create a Kubernetes Docker-registry secret in your IBM Cloud Pak for Multicloud Management namespace.

    oc create secret docker-registry <any_name_for_the_secret> --docker-username=$ENTITLED_REGISTRY_USER --docker-password=$ENTITLED_REGISTRY_KEY --docker-email=<your_docker_email_address> --docker-server=$ENTITLED_REGISTRY -n <your_IBM Cloud Pak for Multicloud Management_namespace>

Install the IBM Cloud Pak after your cluster is prepared

After your offline cluster is prepared, continue with the installation of the IBM Cloud Pak for Multicloud Management.