Getting access to images from the public IBM Entitled Registry

To get access to the container images from the IBM entitled registry, you must have a key to pull the images from the IBM registry.

About this task

To get the entitlement key, log in with the IBMid and password that is associated with the entitled software here My IBM Container Software Library. Click Add new key and then click Copy. Save the key in a text file.

The deployment script uses the entitlement key to create the secret to pull the images. Therefore, you do not need to create the image pull secret unless you want to create the secret yourself or you do not plan to use the scripts.

You can update the global pull secret for your cluster to ensure that all namespaces on your cluster have the necessary credentials to pull images.

Important: If you use a public network to access the IBM Entitled Registry by using the domains cp.icr.io and icr.io, you must add the following hostnames to your firewall rules:
  • dd0.icr.io
  • dd2.icr.io
  • dd4.icr.io
  • dd6.icr.io
Users that are located in China, must also allow the following hostnames:
  • dd1-icr.ibm-zh.com
  • dd3-icr.ibm-zh.com
  • dd5-icr.ibm-zh.com
  • dd7-icr.ibm-zh.com

You can also add wildcard characters to hostnames in your allowlist, for example *.icr.io and *.ibm-zh.com.

Procedure

Choose one of the following options:

  • Choice: 1 If you plan to use the deployment scripts and you do not want to use a global image pull secret, then you do not need to do anything as the secrets are created for you.

  • Choice: 2 If you plan to use the OCP console to install, then you must create the secrets that you need in the appropriate namespaces.

    1. Click Workloads > Secrets, click Create, and then select "image pull secret". Make sure that you are in the NAMESPACE where you want to create the secret.
    2. In the Create Image Pull Secret window, add the following details, and then click Create.
      Table 1. Image pull details for target namespace secrets
      Field Value
      Name ibm-entitlement-key
      Authentication Type Image Registry Credentials
      Registry Server Address cp.icr.io
      Username cp
      Password Your IBM Entitlement Key
      Email Optional

  • Choice: 3 If you want to use the global pull secret, add the IBM Entitled Registry to the pull secret.

    Note: If a global pull secret exists for cp.icr.io, then the operator can already pull images from IBM Entitled Registry. If it does not exist, you must add it.

    Determine whether a global pull secret exists. In the OpenShift console, click Workloads > Secrets. Click Projects, toggle the Show default projects and select openshift-config. Search for pull-secret in the openshift-config project.

    From the OCP CLI, the following command generates a JSON file .dockerconfigjson if it does not exist.

    oc extract secret/pull-secret -n openshift-config
    Table 2. Add IBM Entitled Registry credentials to the global pull secret in the OpenShift console
    OpenShift console

    Click Workloads > Secrets, and switch to the openshift-config namespace. If the pull-secret secret does not exist, click Create, and then select "image pull secret".

    In the Create Image Pull Secret window, add the following details, and then click Create.
    • Name: pull-secret
    • Registry Server Address: cp.icr.io
    • Username: cp
    • Password: Your IBM Entitlement Key
    • Email: Optional

    If it does exist, select the secret and then click Actions > Edit Secret. Then click Add credentials, enter the information, and click Save.
    Table 3. Add IBM Entitled Registry credentials to the global pull secret from the command line
    OCP CLI

    If the .dockerconfigjson is empty.

    1. Set the following environment variables:
      export REGISTRY_USER=cp 
export REGISTRY_PASSWORD=entitlement-key 
export REGISTRY_SERVER=cp.icr.io

      Replace entitlement-key with your entitlement key.

    2. Run the following command to create the pull secret:
      oc create secret docker-registry \
   --docker-server=${REGISTRY_SERVER} \
   --docker-username=${REGISTRY_USER} \
   --docker-password=${REGISTRY_PASSWORD} \
   --docker-email=${REGISTRY_USER} \
   -n openshift-config pull-secret

    If the pull secret exists:

    1. Encode the username and password by using Base64 encoding: 
      echo -n "cp:entitlement-key" | base64

      Replace entitlement-key with your entitlement key.

    2. Add an entry for the container registry to the auths section in the JSON file. The following example has an existing entry:
      {
   "auths":{
         "myregistry.example.com":{
         "auth":"b3Blb=",
         "email":"not-used"
      }
   }
}

      The new entry can be added to the auths section:

      {
   "auths":{
         "registry-location":{
         "auth":"base64-encoded-credentials",
         "email":"not-used"
      },
         "myregistry.example.com":{
         "auth":"b3Blb=",
         "email":"not-used"
      }
   }
}
      Replace the following values:
      registry-location
      The value is cp.icr.io.
      base64-encoded-credentials
      The encoded credentials that you generated in the previous step. For example, cmVnX3VzZXJuYW1lOnJlZ19wYXNzd29yZAo=.
    3. Apply the new configuration:
      oc set data secret/pull-secret -n openshift-config \
--from-file=.dockerconfigjson

Results

Important: For deployments on IBM Cloud, you must reload the worker nodes in your cluster for the changes to take effect. For details, see Adding a private registry to the global pull secret.

If you have a VPC Gen2 cluster and you use Portworx storage, see Portworx storage limitations before you reload your worker nodes.

What to do next

For online deployments, you can now install the operator. For more information, see Installing the FileNet Content Manager operator.

For airgapped deployments, see topic Preparing your cluster for an air-gapped (offline) deployment on OCP