Obtaining and applying your IBM Entitled Registry entitlement key

The IBM® Entitled Registry contains software images for the IBM App Connect components that can be used to create your authoring and runtime environments, and other resources. To allow the IBM App Connect Operator to pull these software images from the IBM Entitled Registry, you must first obtain your entitlement key (if you do not already have one) and then supply it as a Kubernetes pull secret. If you use the secret name ibm-entitlement-key, this secret is automatically used to pull images from the IBM Entitled Registry.

You can add a pull secret to each namespace in which you want to create your authoring and runtime environments, and resources. Or, you can add a global pull secret, which enables deployment of the authoring and runtime environments, and resources in all namespaces. A cluster administrator or a user with the required permissions must complete this procedure.


If you installed the Operator in an air-gapped environment on Red Hat® OpenShift®, an entitlement was obtained and applied as part of the mirroring process. Therefore, you can skip this task.

If you installed the Operator in an online environment on Red Hat OpenShift or Kubernetes, you need to complete this task.

Obtaining an entitlement key


To obtain an entitlement key, complete the following steps:

  1. Log in the IBM Container software library with the IBMid and password that are associated with the entitled software.
  2. Complete either of the following steps:
    • To obtain a new key, click Get entitlement key or Add new key, and then click Copy.
    • If you have an existing key to use, click Copy.
  3. Save the generated entitlement key to a safe place for later use.
  4. Optional: Verify the validity of the key by using a container tool such as docker. From a command prompt, log in to the IBM Entitled Registry by running the following command, using cp as the user name, cp.icr.io as the Docker server, and your entitlement key as the password:
    docker login cp.icr.io --username cp --password myEntitlementKey

Adding an entitlement key to a namespace

You can use standard Kubernetes tools to create a pull secret (which contains your entitlement key) in the installation namespace of your IBM App Connect components. You must create the secret in every namespace where you want to install IBM App Connect components.


To add an entitlement key to a namespace, complete the following step.

Create a Docker registry secret by running the following command, with ibm-entitlement-key as the secret name, cp as the user name, your entitlement key as the password, and your required target namespace:
oc create secret docker-registry ibm-entitlement-key \
    --docker-username=cp \
    --docker-password=myEntitlementKey \
    --docker-server=cp.icr.io \

You can also use the kubectl tool instead of the oc tool to create the secret.

Adding a global pull secret for all namespaces


To add a pull secret for the whole cluster, complete 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 by using jq. Install the jq command-line JSON processor if you do not already have it installed.
    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 Obtaining an entitlement key.
    echo -n "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. Replace auth_string with the value of the auth string that was returned in the previous step.
    Important: You must enter the value of auth_string as a single, continuous string. If any line breaks are included, 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 the following message.

    secret/pull-secret data updated

    This update triggers a restart of all your cluster's nodes. It can take up to an hour for the change to take effect, depending on your cloud provider and the size of your cluster.

  6. When all nodes are back online, run this command (which makes status updates in real time) to confirm.
    oc get machineconfigpool -w