Getting access to the new container images for upgrade

To get access to the container images, you must have an IBM entitlement registry key to pull the images from the IBM docker registry or download the packages (.tgz files) from Passport Advantage (PPA).

About this task

Airgap scenario
For users with a cluster in a private network that doesn’t have public internet access, follow the steps in Setting up the private registry.
Non-Airgap scenario
For other users, you can choose one of the options:

Downloading container images from the IBM Entitled Registry

About this task

The deployment script uses the entitlement key to create the secret to pull the images. You can obtain your entitlement key from the Container Library. 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.

If your platform is OpenShift based, you can also update the global pull secret for your cluster to ensure that all namespaces on your cluster have the necessary credentials to pull images.

Procedure

Choose one of the four 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 OCP or any CNCF Kubernetes platform, you can manually create pull secrets in the required namespaces.

    You can create manually image pull secrets using the kubectl command-line. Following is an example using the IBM Entitled Registry. For more information about the procedure as it could be used with private registries, see Kubernetes documentation.

    To pull images from the IBM Entitled Registry, create a secret in the target namespace naming the secret ibm-entitlement-key:
    kubectl create secret docker-registry ibm-entitlement-key --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email> -n <namespace>
    where:

    • <your-registry-server> is cp.icr.io.

    • <your-name> is cp.

    • <your-pword> is your entitlement-key.

    • <your-email> is your email.

    • <namespace> is the namespace created for the deployment.

  • Choice 3: 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 4: If you plan to use OCP and want to use the global pull secret:

    Determine whether a global pull secret exists. From the OpenShift console, click Workloads > Secrets and 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
    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.
    Table 2. Add IBM Entitled Registry credentials to the global pull secret
    OpenShift console OCP CLI

    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.

    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 -w0

      Replace entitlement-key with your entitlement key.

    2. Add an entry for the container registry to the auths section in the JSON file. In the following example, 1 is the new entry and 2 is the existing entry:
      {
   "auths":{
       1 "registry-location":{
         "auth":"base64-encoded-credentials",
         "email":"not-used"
      },
       2 "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=.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.

(V5.5.8 and earlier) Downloading container images from Passport Advantage

Procedure

  1. Make sure that you are able to access the container-samples directory within the GitHub repository.
    Download or clone the repository on your local machine and change to the operator folder in your local repository.
    git clone -b 5.5.x https://github.com/ibm-ecm/container-samples

    Where 5.5.x is replaced with the version that you want to use.

    To change to the operator folder:
    cd container-samples
  2. Download the packages from PPA and load the images.

    IBM Passport Advantage (PPA) provides archives (.tgz) for the software. To view the list of Passport Advantage eAssembly installation images, refer to the download document.

    1. Download one or more PPA packages to a server that is connected to your Docker registry.
    2. Log in to your cluster.
    3. Check that you can run a docker or podman command.
      docker ps
      podman ps
    4. Log in to the Docker registry with a token: 
      docker login <registry url> -u <ADMINISTRATOR> -p <password>
      Or, with Open Shift:
      podman login $(oc registry info) -u <administrator> -p $(oc whoami -t) 
      Note: You can connect to a node in the cluster to resolve the docker-registry.default.svc parameter.
    5. Run a kubectl command to make sure that you can use Kubernetes.
      kubectl cluster-info
    6. Run the scripts/loadimages.sh script to load the images into your Docker registry. Specify the two mandatory parameters in the command line.
      -p  PPA archive files location or archive file name
-r  Target Docker registry and namespace
-l  Optional: Target a local registry

      The following example shows the input values in the command line.

      cd scripts
./loadimages.sh -p <PPA-ARCHIVE>.tgz -r docker-registry.default.svc:5000/<project-name>
      Note: The project-name variable is the name of the project that you created when you set up your cluster. If you want to use an external Docker registry, take a note of the docker registry service name or the URL so that you can enter it during deployment. If you connect remotely to the cluster from a Linux host/VM, then you must have Docker and the OpenShift command line interface (CLI) installed on OCP. If you have access to the master node on the cluster, the OCP CLI and Docker are already installed.
      Or, with Open Shift:
      ./loadimages.sh -p <PPA-ARCHIVE>.tgz  -r $(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')/my_project_name
    7. Check that the images are pushed correctly to the registry. Using the OpenShift CLI:
      oc get is
    8. In your target namespace, create a Docker registry secret if you want to use an external Docker registry or reuse a secret in the target project if you want to use an internal Docker registry.
      If you want to pull directly from the IBM entitled registry, reuse the secret that you created in Step 1 Option 1:
      imagePullSecrets:
   name: "admin.registrykey"
      Note: The secret_name must match the imagePullSecrets.name parameter in the operator deployment (.yaml) file, for example, admin.registrykey.
      Create a secret to access an external Docker registry:
      $ oc create secret docker-registry admin.registrykey --docker-server=<registry_url> --docker-username=<your_account> --docker-password=<your_password> --docker-email=fncmtest@ibm.com
      For an internal Docker registry:
      $ oc project <my-project>
$ oc get secret
  3. In your target namespace, at deployment time, verify that the secret that you created for your image pull secret is still valid and has not expired. If needed, delete and recreate the secret as applicable in the previous steps.

What to do next

To upgrade the operator version and the components, see topic Upgrading the operator version and your components.