Applying your entitlement key (online installation)

The IBM Entitled Registry contains software images for the capabilities in IBM Cloud Pak® for Integration. To allow the Cloud Pak for Integration operators to automatically pull those software images, you must first obtain your entitlement key, then add your entitlement key in a pull secret.

Obtaining your entitlement key

  1. Go to the Container software library.
  2. Click Copy key.
  3. Copy the entitlement key to a safe place so you can use it when you add the pull secret in the next section.
  4. (Optional) Verify the validity of the key by logging in to the IBM Entitled Registry using a container tool.
    docker login cp.icr.io --username cp --password entitlement_key

Applying the pull secret

Your entitlement key must be added to the cluster as a pull secret to deploy Cloud Pak for Integration capabilities. You can either add a pull secret to each namespace you plan to use for Cloud Pak for Integration capabilities, or add a global pull secret, which enables deployment of Cloud Pak for Integration capabilities in all namespaces.

You only need to use one method to add the pull secret. The available options are:
Restriction: Depending on which option you choose, it must be performed by either an automation administrator or a cluster administrator (as indicated for each of the following options). For details on these functions, see Roles and permissions.

Adding the pull secret to a namespace using the OpenShift web console

This task must be performed by an automation administrator.

Note: If you need to apply the pull secret globally (in all namespaces), the only available method is to use the CLI. See Adding a global pull secret for all namespaces.
  1. Log in to the OpenShift web console and ensure you are in the Administrator perspective.
  2. In the left navigation, click Workloads > Secrets.
  3. Ensure that the Project is set to the namespace where you intend to install Cloud Pak for Integration capabilities.
  4. Click Create and select Image pull secret.
  5. Set the following parameters for the secret:
    Parameter Value
    Secret name ibm-entitlement-key
    Authentication type Image registry credentials
    Registry server address cp.icr.io
    Username cp
    Password Value of the entitlement key you copied when you obtained your entitlement key.
    Email (Optional value)
  6. Click Create to create the secret.

Adding a pull secret to a namespace using the CLI

This task must be performed by an automation administrator.

To deploy Cloud Pak for Integration capabilities in one or more (but not all) namespaces, run the following command. Note that you must add the pull secret in each namespace where you intend to deploy capabilities.

Create a docker registry secret named ibm-entitlement-key, using the following command. In the third line, replace entitlement_key with the value of your entitlement key from the previous section. In the last line, replace target_namespace with the name of your target namespace:

oc create secret docker-registry ibm-entitlement-key \
    --docker-username=cp \
    --docker-password=entitlement_key \
    --docker-server=cp.icr.io \
    --namespace=target_namespace

Adding a global pull secret for all namespaces

This task must be performed by a cluster administrator.

Note: The following procedure cannot be used with an OpenShift cluster on IBM Cloud.

To add a pull secret for the whole cluster, perform the following steps.

  1. Extract the current global pull secret:
    oc extract secret/pull-secret -n openshift-config --keys=.dockerconfigjson --to=. --confirm
  2. Convert the extracted global pull secret using jq (this assumes you have already installed the jq command-line JSON processor):
    cat .dockerconfigjson | jq . >  .dockerconfigjson.orig
mv .dockerconfigjson.orig .dockerconfigjson
  3. Convert your entitlement key to an auth string. Replace entitlement_key with the value of your entitlement key from the preceding section, "Obtaining your entitlement key".
    echo "cp:entitlement_key" | base64
  4. Edit the .dockerconfigjson file: In the auths section, add the cp.icr.io object (as shown in the following example) to the list of objects that already exist. Replace auth_string with the value of the auth string returned in the previous step.
    Important: You must enter the value of auth_string as a single, continuous string. If there are any line breaks, you will get an error.
    {
   "auths":
      "cp.icr.io" : {
         "auth": "auth_string"
      }
   }
}

    This action adds the new pull secret.

  5. Upload the new global pull secret:
    oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson
    After a successful upload, the system returns:
    secret/pull-secret data updated
    This update triggers a restart of all your cluster's nodes. It may take up to 15 minutes for changes to take effect, depending on the size of your cluster. During this time, nodes are drained and pods are rescheduled on the remaining nodes.
  6. When all nodes are back online, run this command (which makes status updates in real time) to confirm:
    oc get machineconfigpool -w