Moving images for cpd-cli plug-ins to a private container registry

Important: IBM Cloud Pak® for Data Version 4.8 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.8 reaches end of support. For more information, see Upgrading from IBM Cloud Pak for Data Version 4.8 to IBM Software Hub Version 5.1.

Several of the cpd-cli plug-ins use images. If your cluster pulls images from a private container registry or if your cluster is in a restricted network, you can push the images to the private container registry so that users can run the cpd-cli commands against the cluster.

Who needs to complete this task?
A user who has permissions to push images to the private container registry must complete this task.
When do you need to complete this task?
Complete this task if your cluster is in a restricted network or if your security policies require all images to be pulled from a private container registry.

You can skip this task if your workstations can connect to the public internet and to the cluster at the same time.

Which cpd-cli plug-ins require images?

The following table lists the images that are required by each cpd-cli plug-in:
Plug-in Purpose Required images
config Use this plug-in to create a local user configuration and profile to enable you to run cpd-cli commands against an instance of Cloud Pak for Data. This plug-in doesn't require any images.
cpdbr Use this plug-in to back up and restore Cloud Pak for Data volumes.
This plug-in requires the following images:
cpdbr image
Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
The image is automatically mirrored when you mirror the Cloud Pak for Data (cpd_platform) images.
cpdbr-oadp Use this plug-in to back up and restore Cloud Pak for Data deployments, including volumes.
This plug-in uses several images. The images that you need depend on the following factors:
  • The type of storage that you are using
  • The method you are using to perform the backup and restore.
ubi-minimal image

This image is required for all backup and restore scenarios.

Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
You must manually mirror the ubi-minimal image to your private container registry.
cpdbr-velero-plugin image

This image is required for all backup and restore scenarios.

Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
This image is automatically mirrored when you mirror the Cloud Pak for Data (cpd_platform) images.
cpdbr-oadp image

This image is required only if you are using IBM® Storage Fusion Data Protection, NetApp Astra Control Center, or Portworx Enterprise to back up Cloud Pak for Data deployments.

Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
This image is automatically mirrored when you mirror the Cloud Pak for Data (cpd_platform) images.
cpdbr-api image

This image is required only if you are using OpenShift® APIs for Data Protection to back up Cloud Pak for Data deployments using REST API calls.

Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
This image is automatically mirrored when you mirror the Cloud Pak for Data (cpd_platform) images.
cpdctl

Use this plug-in to automate activities performed on different types of workspace and assets across multiple Cloud Pak for Data clusters.

 This plug-in doesn't require any images.
cpdtool

Use this plug-in to export and import data, including metadata.
This plug-in requires the following images:
cpdtool image
Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
This image is automatically mirrored when you mirror the Cloud Pak for Data (cpd_platform) images.
health Query the health of your Red Hat OpenShift cluster and the Cloud Pak for Data platform.
This plug-in requires the following images:
centos
This image is required for the storage-validation command.
Supported hardware
  • x86_64
Obtaining the image
You must manually mirror the centos image to your private container registry.
k8s-storage-perf image

This image is required for the storage-performance command.

Supported hardware
  • x86_64
Obtaining the image
You must manually mirror the storage-performance image to your private container registry.
k8s-storage-test

This image is required for the storage-validation command.

Supported hardware
  • x86_64
Obtaining the image
You must manually mirror the k8s-storage-test image to your private container registry.
storage-gcc
This image is required for the storage-validation command.
Supported hardware
  • x86_64
Obtaining the image
You must manually mirror the storage-gcc image to your private container registry.
storage-util
This image is required for the storage-validation command.
Supported hardware
  • x86_64
Obtaining the image
You must manually mirror the storage-util image to your private container registry.
xsysbench

This image is required for the storage-performance command.

Supported hardware
  • x86_64
Obtaining the image
You must manually mirror the xsysbench image to your private container registry.
manage

Use this plug-in to install and upgrade Cloud Pak for Data
This plug-in requires the following images:
olm-utils-v2 image

This image is required to install and upgrade Cloud Pak for Data.

Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
This image is automatically mirrored when you mirror the Cloud Pak for Data (cpd_platform) images.
zen-rsi-adm-controller image

This image is required only if you plan to use the resource specification injection (RSI) feature.

Important: The RSI feature is recommended only for advanced Red Hat® OpenShift Container Platform users.
Supported hardware
  • x86_64
  • ppc64le
  • s390x
Obtaining the image
This image is automatically mirrored when you mirror the Cloud Pak for Data (cpd_platform) images.
platform-diag

Use this plug-in to gather diagnostic information about a Cloud Pak for Data deployment.

This plug-in doesn't require any images.
platform-mgmt

Use this plug-in to manage service instances and users associated with a Cloud Pak for Data deployment.

This plug-in doesn't require any images.

Before you begin

Complete the following tasks before you move the images to the private container registry:

  1. Setting up a client workstation to install Cloud Pak for Data
  2. Setting up installation environment variables

Mirroring the ubi-minimal image to the private container registry

The steps that you must complete depend on whether the workstation can connect to both the internet and the private container registry at the same time:

The workstation can connect to the internet and to the private container registry
  1. Ensure that Docker or Podman is running on the workstation.
  2. Log in to the private container registry:
    Podman
    podman login ${PRIVATE_REGISTRY_LOCATION} \
-u ${PRIVATE_REGISTRY_PUSH_USER} \
-p ${PRIVATE_REGISTRY_PUSH_PASSWORD}
    Docker
    docker login ${PRIVATE_REGISTRY_LOCATION} \
-u ${PRIVATE_REGISTRY_PUSH_USER} \
-p ${PRIVATE_REGISTRY_PUSH_PASSWORD}
  3. Log in to the Red Hat entitled registry.
    1. Set the REDHAT_USER environment variable to the username of a user who can pull images from registry.redhat.io:
      export REDHAT_USER=<enter-your-username>
    2. Set the REDHAT_PASSWORD environment variable to the password for the specified user:
      export REDHAT_PASSWORD=<enter-your-password>
    3. Log in to registry.redhat.io:
      Podman
      podman login registry.redhat.io \
-u ${REDHAT_USER} \
-p ${REDHAT_PASSWORD}
      Docker
      docker login registry.redhat.io \
-u ${REDHAT_USER} \
-p ${REDHAT_PASSWORD}
  4. Run the following command to mirror the ubi-minimal image the private container registry.

    The same image is used for all cluster hardware architectures:

    Version 4.8.0 - 4.8.3 
    oc image mirror registry.redhat.io/ubi8/ubi-minimal:latest ${PRIVATE_REGISTRY_LOCATION}/ubi8/ubi-minimal:latest --insecure
    Version 4.8.4 and later 
    oc image mirror registry.redhat.io/ubi9/ubi-minimal:latest ${PRIVATE_REGISTRY_LOCATION}//ubi9/ubi-minimal:latest --insecure
The workstation cannot connect to the private container registry at the same time
  1. From a workstation that can connect to the internet:
    1. Ensure that Docker or Podman is running on the workstation.
    2. Ensure that the olm-utils-v2 image is available on the client workstation:
      cpd-cli manage restart-container
    3. Log in to the Red Hat entitled registry.
      1. Set the REDHAT_USER environment variable to the username of a user who can pull images from registry.redhat.io:
        export REDHAT_USER=<enter-your-username>
      2. Set the REDHAT_PASSWORD environment variable to the password for the specified user:
        export REDHAT_PASSWORD=<enter-your-password>
      3. Log in to registry.redhat.io:
        Podman
        podman login registry.redhat.io \
-u ${REDHAT_USER} \
-p ${REDHAT_PASSWORD}
        Docker
        docker login registry.redhat.io \
-u ${REDHAT_USER} \
-p ${REDHAT_PASSWORD}
    4. Run the following command to save the ubi-minimal image to the client workstation:

      The same image is used for all cluster hardware architectures:

      Version 4.8.0 - 4.8.3 
      cpd-cli manage save-image \
--from=registry.redhat.io/ubi8/ubi-minimal:latest
      Version 4.8.4 and later 
      cpd-cli manage save-image \
--from=registry.redhat.io/ubi9/ubi-minimal:latest
  2. Transfer the compressed file to a client workstation that can connect to the cluster.

    Ensure that you place the ubi8_registry.redhat.io_ubi8_ubi-minimal_latest.tar.gz or ubi9_registry.redhat.io_ubi9_ubi-minimal_latest.tar.gz TAR file in the work/offline directory.

  3. From the workstation that can connect to the cluster:
    1. Ensure that Docker or Podman is running on the workstation.
    2. Log in to the private container registry.

      The following command assumes that you are using private container registry that is secured with credentials:

      cpd-cli manage login-private-registry
${PRIVATE_REGISTRY_LOCATION} \
${PRIVATE_REGISTRY_PUSH_USER} \
${PRIVATE_REGISTRY_PUSH_PASSWORD}

      If your private registry is not secured, omit the username and password.

    3. Run the following command to copy the ubi-minimal image to the private container registry:
      Version 4.8.0 - 4.8.3 
      cpd-cli manage copy-image \
--from=registry.redhat.io/ubi8/ubi-minimal:latest \
--to=${PRIVATE_REGISTRY_LOCATION}/ubi8/ubi-minimal:latest
      Version 4.8.4 and later 
      cpd-cli manage copy-image \
--from=registry.redhat.io/ubi9/ubi-minimal:latest \
--to=${PRIVATE_REGISTRY_LOCATION}/ubi9/ubi-minimal:latest

Mirroring the images required for the storage-performance command to the private container registry

If you plan to use the cpd-cli health storage-performance command, you must mirror the following images to your private container registry:
  • k8s-storage-perf
  • xsysbench

The steps that you must complete depend on whether the workstation can connect to both the internet and the private container registry at the same time:

The workstation can connect to the internet and to the private container registry
  1. Ensure that Docker or Podman is running on the workstation.
  2. Ensure that the olm-utils-v2 image is available on the client workstation:
    cpd-cli manage restart-container
  3. Log in to the private container registry.

    The following command assumes that you are using private container registry that is secured with credentials:

    cpd-cli manage login-private-registry
${PRIVATE_REGISTRY_LOCATION} \
${PRIVATE_REGISTRY_PUSH_USER} \
${PRIVATE_REGISTRY_PUSH_PASSWORD}

    If your private registry is not secured, omit the username and password.

  4. Log in to the IBM Entitled Registry entitled registry:
    cpd-cli manage login-entitled-registry \
${IBM_ENTITLEMENT_KEY}
  5. Run the following commands to mirror the required images to the private container registry:
    1. Mirror the k8s-storage-perf image:
      cpd-cli manage copy-image \
--from=icr.io/cpopen/cpd/k8s-storage-perf:v1.0.0 \
--to=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/k8s-storage-perf:v1.0.0
    2. Mirror the xsysbench image:
      cpd-cli manage copy-image \
--from=quay.io/ibm-cp4d-public/xsysbench:1.1-amd64 \
--to=${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/xsysbench:1.1-amd64
The workstation cannot connect to the private container registry at the same time
  1. From a workstation that can connect to the internet:
    1. Ensure that Docker or Podman is running on the workstation.
    2. Ensure that the olm-utils-v2 image is available on the client workstation:
      cpd-cli manage restart-container
    3. Run the following command to save the required images to the client workstation:
      1. Save the k8s-storage-perf image:
        cpd-cli manage save-image \
--from=icr.io/cpopen/cpd/k8s-storage-perf:v1.0.0
      2. Save the xsysbench image:
        cpd-cli manage copy-image \
--from=quay.io/ibm-cp4d-public/xsysbench:1.1-amd64 \
--to=${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/xsysbench:1.1-amd64
  2. Transfer the compressed files to a client workstation that can connect to the cluster.

    Ensure that you place the TAR files in the work/offline directory:

    • icr.io_cpopen_cpd_k8s-storage-perf_v1.0.0.tar.gz
    • quay.io_ibm-cp4d-public_xsysbench_1.1-amd64.tar.gz
  3. From the workstation that can connect to the cluster:
    1. Ensure that Docker or Podman is running on the workstation.
    2. Log in to the private container registry.

      The following command assumes that you are using private container registry that is secured with credentials:

      cpd-cli manage login-private-registry
${PRIVATE_REGISTRY_LOCATION} \
${PRIVATE_REGISTRY_PUSH_USER} \
${PRIVATE_REGISTRY_PUSH_PASSWORD}

      If your private registry is not secured, omit the username and password.

    3. Run the following commands to copy the required images to the private container registry:
      1. Copy the k8s-storage-perf image:
        cpd-cli manage copy-image \
--from=icr.io/cpopen/cpd/k8s-storage-perf:v1.0.0 \
--to=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/k8s-storage-perf:v1.0.0
      2. Copy the xsysbench image:
        cpd-cli manage copy-image \
--from=quay.io/ibm-cp4d-public/xsysbench:1.1-amd64 \
--to=${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/xsysbench:1.1-amd64

Mirroring the images required for the storage-validation command to the private container registry

If you plan to use the cpd-cli health storage-validation command, you must mirror the following images to your private container registry:

  • centos
  • k8s-storage-test
  • storage-gcc
  • storage-util

The steps that you must complete depend on whether the workstation can connect to both the internet and the private container registry at the same time:

The workstation can connect to the internet and to the private container registry
  1. Ensure that Docker or Podman is running on the workstation.
  2. Ensure that the olm-utils-v2 image is available on the client workstation:
    cpd-cli manage restart-container
  3. Log in to the private container registry.

    The following command assumes that you are using private container registry that is secured with credentials:

    cpd-cli manage login-private-registry
${PRIVATE_REGISTRY_LOCATION} \
${PRIVATE_REGISTRY_PUSH_USER} \
${PRIVATE_REGISTRY_PUSH_PASSWORD}

    If your private registry is not secured, omit the username and password.

  4. Log in to the IBM Entitled Registry entitled registry:
    cpd-cli manage login-entitled-registry \
${IBM_ENTITLEMENT_KEY}
  5. Run the following command to mirror the required image the private container registry:
    1. Mirror the centos image:
      cpd-cli manage copy-image \
--from=quay.io/centos/amd64:latest \
--to=${PRIVATE_REGISTRY_LOCATION}/centos/amd64:latest
    2. Mirror the k8s-storage-test image:
      cpd-cli manage copy-image \
--from=icr.io/cpopen/cpd/k8s-storage-test:v1.0.0 \
--to=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/k8s-storage-test:v1.0.0
    3. Mirror the storage-gcc image:
      cpd-cli manage copy-image \
--from=quay.io/ibm-cp4d-public/storage-gcc:1.0-amd64 \
--to=${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/storage-gcc:1.0-amd64
    4. Mirror the storage-util image:
      cpd-cli manage copy-image \
--from=quay.io/ibm-cp4d-public/storage-util:1.0-amd64 \
--to=${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/storage-util:1.0-amd64
The workstation cannot connect to the private container registry at the same time
  1. From a workstation that can connect to the internet:
    1. Ensure that Docker or Podman is running on the workstation.
    2. Ensure that the olm-utils-v2 image is available on the client workstation:
      cpd-cli manage restart-container
    3. Run the following commands to save the required images to the client workstation:
      1. Save the centos image:
        cpd-cli manage save-image \
--from=quay.io/centos/amd64:latest
      2. Save the k8s-storage-test image:
        cpd-cli manage save-image \
--from=icr.io/cpopen/cpd/k8s-storage-test:v1.0.0
      3. Save the storage-gcc image:
        cpd-cli manage save-image \
--from=quay.io/ibm-cp4d-public/storage-gcc:1.0-amd64
      4. Save the storage-util image:
        cpd-cli manage save-image \
--from=quay.io/ibm-cp4d-public/storage-util:1.0-amd64
  2. Transfer the compressed files to a client workstation that can connect to the cluster.

    Ensure that you place the TAR files in the work/offline directory:

    • icr.io_cpopen_cpd_k8s-storage-test_v1.0.0.tar.gz
    • quay.io_centos_amd64_latest.tar.gz
    • quay.io_ibm-cp4d-public_storage-gcc_1.0-amd64.tar.gz
    • quay.io_ibm-cp4d-public_storage-util_1.0-amd64.tar.gz
  3. From the workstation that can connect to the cluster:
    1. Ensure that Docker or Podman is running on the workstation.
    2. Log in to the private container registry.

      The following command assumes that you are using private container registry that is secured with credentials:

      cpd-cli manage login-private-registry
${PRIVATE_REGISTRY_LOCATION} \
${PRIVATE_REGISTRY_PUSH_USER} \
${PRIVATE_REGISTRY_PUSH_PASSWORD}

      If your private registry is not secured, omit the username and password.

    3. Run the following command to copy the required images to the private container registry:
      1. Copy the centos image:
        cpd-cli manage copy-image \
--from=quay.io/centos/amd64:latest \
--to=${PRIVATE_REGISTRY_LOCATION}/centos/amd64:latest
      2. Copy the k8s-storage-test image:
        cpd-cli manage copy-image \
--from=icr.io/cpopen/cpd/k8s-storage-test:v1.0.0 \
--to=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/k8s-storage-test:v1.0.0
      3. Copy the storage-gcc image:
        cpd-cli manage copy-image \
--from=quay.io/ibm-cp4d-public/storage-gcc:1.0-amd64 \
--to=${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/storage-gcc:1.0-amd64
      4. Copy the storage-util image:
        cpd-cli manage copy-image \
--from=quay.io/ibm-cp4d-public/storage-util:1.0-amd64 \
--to=${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/storage-util:1.0-amd64

What to do next

After the images are mirrored or pushed to the private container registry, users must ensure that the cpd-cli plug-ins use the images from the private container registry.

Plug-in How to use the images in the private container registry
config Not applicable. This plug-in doesn't require any images.
cpdbr Users who want to run cpd-cli backup-restore commands against the cluster must specify the --image-prefix=${PRIVATE_REGISTRY_LOCATION} option when they run the cpd-cli backup-restore init command.
cpdbr-oadp Users who want to run cpd-cli oadp commands against the cluster must specify the --image-prefix=${PRIVATE_REGISTRY_LOCATION} option when they run some cpd-cli oadp commands.
cpdctl Not applicable. This plug-in doesn't require any images.
cpdtool Users who want to run cpd-cli export-import commands against the cluster must specify the --image-prefix=${PRIVATE_REGISTRY_LOCATION} option when they run the cpd-cli export-import init command.
health The next steps depend on the commands that you want to run:
k8s-storage-perf
  1. Run the cpd-cli manage load-image command to load the k8s-storage-perf image to the client workstation before you run the cpd-cli health storage-performance command.
  2. Create a YAML file named storage-images.yaml with the following content:
    cat << EOF > ./storage-images.yaml
imageurl: ${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/xsysbench:1.1
docker_registry: "${PRIVATE_REGISTRY_LOCATION}"
EOF
    Important: When you run the cpd-cli health storage-performance command, you must specify --param=<fully-qualified-path-of-the-storage-images.yaml-file>
k8s-storage-test
  1. Run the cpd-cli manage load-image command to load the k8s-storage-test image to the client workstation before you run the cpd-cli health storage-validation command.
  2. Create a YAML file named storage-images.yaml with the following content:
    cat << EOF > ./storage-images.yaml
imageurl: ${PRIVATE_REGISTRY_LOCATION}/ibm-cp4d-public/xsysbench:1.1
docker_registry: "${PRIVATE_REGISTRY_LOCATION}"
EOF
    Important: When you run the cpd-cli health storage-validation command, you must specify --param=<fully-qualified-path-of-the-storage-images.yaml-file>
manage The next steps depend on the commands that you want to run:
olm-utils-v2
Users who want to run cpd-cli manage commands against the cluster must add the OLM_UTILS_IMAGE environment variable to their environment variables script:
x86-64 clusters
export OLM_UTILS_IMAGE=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/olm-utils-v2:${VERSION}
ppc64le clusters
export OLM_UTILS_IMAGE=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/olm-utils-v2:${VERSION}.ppc64le
s390x clusters
export OLM_UTILS_IMAGE=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/olm-utils-v2:${VERSION}.s390x
zen-rsi-adm-controller
When you install the RSI webhook, you must specify the --rsi_image option.
x86-64 clusters
--rsi_image=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/zen-rsi-adm-controller:${VERSION}-x86_64
ppc64le clusters
--rsi_image=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/zen-rsi-adm-controller:${VERSION}-ppc64le
s390x clusters
--rsi_image=${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/zen-rsi-adm-controller:${VERSION}-s390x
platform-diag Not applicable. This plug-in doesn't require any images.
platform-mgmt Not applicable. This plug-in doesn't require any images.