Configuring your cluster to pull Cloud Pak for Data images

To ensure that your cluster can pull Cloud Pak for Data software images, you must update your cluster configuration.

Permissions you need for this task
You must be a cluster administrator.
When you need to complete this task
You must complete this task the first time you install Cloud Pak for Data.

Before you begin

Best practice: You can run the commands in this task exactly as written if you set up environment variables for your installation. For instructions, see Best practice: Setting up install variables.

Ensure that you run the environment variable script before you run the commands in this task.

Procedure

The tasks that you must complete depend on whether your cluster pulls images directly from the IBM® Entitled Registry or from a private container registry.

Task IBM Entitled Registry Private container registry
1. Configuring the global image pull secret Required Required
2. Configuring an image content source policy Not applicable Required

1. Configuring the global image pull secret

Best practice: You can run the commands in this task exactly as written if you set up environment variables for your installation. For instructions, see Best practice: Setting up install variables.

Ensure that you run the environment variable script before you run the commands in this task.

The global image pull secret ensures that your cluster has the necessary credentials to pull images.

The credentials that you add to the global image pull secret depend on where you want to pull images from:

IBM Entitled Registry
If you are pulling images from the IBM Entitled Registry, the global image pull secret must contain your IBM entitlement API key.
Private container registry
If you are pulling images from a private container registry, the global image pull secret must contain the credentials of an account that can pull images from the registry.

If you have already configured the global image pull secret with the necessary credentials, you can skip this task.

Important: When you change the global image pull secret, each node in the cluster is automatically restarted so that the Machine Config Operator can apply the changes. This restart process happens one node at a time. The cluster will wait for a node to restart before starting the process on the next node. In some situations, it takes more than 30 minutes for all of the nodes to be restarted. During this process, you might notice that resources are temporarily unavailable.

If your deployment is on IBM Cloud, you must manually reload the worker nodes in your cluster for the changes to take effect.

To configure the global image pull secret:

  1. Confirm that the following installation environment variables are set based on the container registry that OpenShift® is going to pull from:
    IBM Entitled Registry 
    echo $IBM_ENTITLEMENT_SERVER
echo $IBM_ENTITLEMENT_USER
echo $IBM_ENTITLEMENT_KEY
    Private container registry 
    echo $PRIVATE_REGISTRY_LOCATION
echo $PRIVATE_REGISTRY_PULL_USER
echo $PRIVATE_REGISTRY_PULL_PASSWORD
  2. Create an environment variable that points to a temporary directory on your workstation. For example:
    export WORK_ROOT=$HOME/temp/work
  3. Download the pull secret to the temporary directory:
    oc get secret/pull-secret \
  -n openshift-config \
  --template='{{index .data ".dockerconfigjson" | base64decode}}' > ${WORK_ROOT}/global_pull_secret.cfg
  4. Add the new pull secret to the local copy of the global_pull_secret.cfg file:
    IBM Entitled Registry 
    oc registry login \
  --registry="${IBM_ENTITLEMENT_SERVER}" \
  --auth-basic="${IBM_ENTITLEMENT_USER}:${IBM_ENTITLEMENT_KEY}" \
  --to=${WORK_ROOT}/global_pull_secret.cfg
    Private container registry 
    oc registry login \
  --registry="${PRIVATE_REGISTRY_LOCATION}" \
  --auth-basic="${PRIVATE_REGISTRY_PULL_USER}:${PRIVATE_REGISTRY_PULL_PASSWORD}" \
  --to=${WORK_ROOT}/global_pull_secret.cfg
  5. Update the global pull secret on your cluster:
    oc set data secret/pull-secret \
-n openshift-config \
--from-file=.dockerconfigjson=${WORK_ROOT}/global_pull_secret.cfg
  6. Get the status of the nodes: 
    oc get nodes
    Wait until all the nodes are Ready before you proceed to the next step. For example, if you see Ready,SchedulingDisabled, wait for the process to complete:
    NAME                           STATUS                     ROLES    AGE     VERSION
master0                        Ready                      master   5h57m   v1.20.0
master1                        Ready                      master   5h57m   v1.20.0
master2                        Ready                      master   5h57m   v1.20.0
worker0                        Ready,SchedulingDisabled   worker   5h48m   v1.20.0
worker1                        Ready                      worker   5h48m   v1.20.0
worker2                        Ready                      worker   5h48m   v1.20.0
    Tip: You can use the watch oc get nodes command to monitor the status of the nodes. The command provides an update every 2 seconds. When all of the nodes return Ready you can exit the command by pressing Ctrl+C.

    Alternatively, if you find that the oc get nodes command returns Ready prematurely, you can use the oc get mcp command to get the real-time status of the nodes.

What's next Complete the appropriate task for your environment:
IBM Entitled Registry
Now that you've updated the global pull secret to include your IBM entitlement API key, you're ready to complete Creating catalog sources.
Private container registry
Now that you've updated the global pull secret to include the credentials of an account that can pull images from the registry, you're ready to complete 2. Configuring an image content source policy.

2. Configuring an image content source policy

If you mirrored images to a private container registry, you must tell your cluster where to find the software images. (For more information how Red Hat® OpenShift Container Platform locates images from an mirrored repository, see Configuring image registry repository mirroring in the Red Hat OpenShift Container Platform documentation.)

Important: This process will temporarily disable scheduling on each node in the cluster, so you might notice that resources are temporarily unavailable. However, this process happens on one node at a time. The cluster will temporarily disable scheduling on a node, apply the configuration change, and then re-enable scheduling before starting the process on the next node.

To configure an image content source policy:

  1. Confirm that the following installation environment variables is set:
    echo $PRIVATE_REGISTRY_LOCATION
  2. Create an image content source policy. The contents of the policy depend on whether you have an existing policy for IBM Cloud Pak® foundational services.
    Options Image content source policy
    IBM Cloud Pak foundational services is already installed on the cluster If IBM Cloud Pak foundational services Version 3.18.0 is already installed, it is likely that you already have an image content source policy for icr.io/cpopen/cpfs. Therefore, you do not need to create a mirroring policy for those images.
    cat <<EOF |oc apply -f -
apiVersion: operator.openshift.io/v1alpha1
kind: ImageContentSourcePolicy
metadata:
  name: cloud-pak-for-data-mirror
spec:
  repositoryDigestMirrors:
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/cp
    source: cp.icr.io/cp
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/cp/cpd
    source: cp.icr.io/cp/cpd
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/cpopen
    source: icr.io/cpopen
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/db2u
    source: icr.io/db2u
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/guardium-insights
    source: icr.io/guardium-insights
EOF
    IBM Cloud Pak foundational services is not installed on the cluster If IBM Cloud Pak foundational services is not installed, it is unlikely that you have an image content source policy for icr.io/cpopen/cpfs, so you should create a mirroring policy for those images.
    cat <<EOF |oc apply -f -
apiVersion: operator.openshift.io/v1alpha1
kind: ImageContentSourcePolicy
metadata:
  name: cloud-pak-for-data-mirror
spec:
  repositoryDigestMirrors:
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/cpopen/cpfs
    source: icr.io/cpopen/cpfs
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/cp
    source: cp.icr.io/cp
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/cp/cpd
    source: cp.icr.io/cp/cpd
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/cpopen
    source: icr.io/cpopen
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/db2u
    source: icr.io/db2u
  - mirrors:
    - ${PRIVATE_REGISTRY_LOCATION}/guardium-insights
    source: icr.io/guardium-insights
EOF
  3. Verify that the image content source policy was created:
    oc get imageContentSourcePolicy
  4. Confirm that the output includes cloud-pak-for-data-mirror.
  5. Get the status of the nodes: 
    oc get nodes
    Wait until all the nodes are Ready before you proceed to the next step. For example, if you see Ready,SchedulingDisabled, wait for the process to complete:
    NAME                           STATUS                     ROLES    AGE     VERSION
master0                        Ready                      master   5h57m   v1.20.0
master1                        Ready                      master   5h57m   v1.20.0
master2                        Ready                      master   5h57m   v1.20.0
worker0                        Ready,SchedulingDisabled   worker   5h48m   v1.20.0
worker1                        Ready                      worker   5h48m   v1.20.0
worker2                        Ready                      worker   5h48m   v1.20.0
    Tip: You can use the watch oc get nodes command to monitor the status of the nodes. The command provides an update every 2 seconds. When all of the nodes return Ready you can exit the command by pressing Ctrl+C.

    Alternatively, if you find that the oc get nodes command returns Ready prematurely, you can use the oc get mcp command to get the real-time status of the nodes.

What's next Now that you've configured the image content source policy, you're ready to complete Creating catalog sources.