Migrating from Docker to the IBM Container Registry

IBM has an anonymous registry and is migrating operator-related images from docker.io/ibmcom to icr.io/cpopen. The IBM® Operator Catalog and related images are now also available by way of IBM controlled sources for consumption.

Important: If you operate in an internet-connected Red Hat® OpenShift® Container Platform cluster, you must migrate your images from Docker to the IBM Container Registry by 30 September 2021. IBM Operator Catalog related images can be sourced from icr.io/cpopen.

If you operate in an air-gapped Red Hat® OpenShift® Container Platform cluster (not connected to the internet and mirroring images from Docker), you can proceed to step 3 of the air-gapped installation instructions: Mirror images to portable registry.

You must consider two aspects of container migration to ensure that your cluster is migrated to the IBM source image repository:

Updating catalog source values

Internet connected clusters that have installed the IBM Operator Catalog from docker.io/ibmcom must have their catalog source in ibm-operator-catalog CatalogSource.yaml file that is updated to reference the new image location (icr.io/cpopen/ibm-operator-catalog:latest). You can perform this update in three different ways:

Edit the YAML with the CLI

  1. Enter the following command to edit the CatalogSource:

    oc edit catalogsource ibm-operator-catalog -n openshift-marketplace
    
  2. Navigate to the spec section of the YAML file, then update the image reference to be icr.io/cpopen/ibm-operator-catalog:latest.

    Updated image value

  3. Save your edited CatalogSource YAML file. If the file is successfully edited and saved, the following message appears:

    catalogsource.operators.coreos.com/ibm-operator-catalog edited
    
  4. Restart the ibm-operator-catalog pod. Navigate to your openshift-marketplace project and enter the following command to ensure that the pod restarted:

    oc get catalogsource ibm-operator-catalog -n openshift-marketplace
    

Edit the YAML with the console

Important: Make sure you have the role of Administrator before editing the CatalogSource.

  1. Click Home > Explore, then enter catalogsource as the filter value to locate your CatalogSource YAML file.

    Filtering by `catalogsource`

  2. Click CatalogSource, then click Instances and search for ibm-operator-catalog.

  3. Click the options menu (three vertical dots) and select Edit CatalogSource.

    Options > Edit CatalogSource

  4. Scroll to the spec section of the YAML file and replace docker.io/ibmcom with icr.io/cpopen, then click Save.

    Updating the `spec` section

  5. Verify that CatalogSource has been implemented:

    1. From the navigation bar, click Workloads > Pods.
    2. Select openshift-marketplace in the Project drop-down menu.
    3. Enter ibm-operator-catalog in the search bar.
    4. Click ibm-operator-catalog link, then scroll to the Conditions to ensure that the CatalogSource has been updated.

      Verifying CatalogSource updates

Upgrade with a Helm chart

You can also upgrade the IBM Operator Helm chart from 1.0.0 to 1.1.0. This upgrade automatically changes the image reference from docker.io/ibmcom/ibm-operator-catalog:latest to icr.io/cpopen/ibm-operator-catalog:latest.

  1. Log in to your console instance and select the Developer view.

    Selecting the Developer view

  2. Click Add, then click From Catalog.

    Adding from catalog

  3. Enter the project and namespace where you want to install the Helm release.

    Entering a project space for the Helm release

  4. Select Helm Charts and enter operator in the search bar.

    Searching for operator

  5. Click the Ibm Operator Catalog tile, then click Install Helm Chart.

  6. Accept the license by entering true in the license field.

    Entering `true` to accept the license

  7. Click Install.

Note: The 1.1.0 version of the Helm chart gives you the option to Deploy Mirror Config. If that value is toggled to true, it will also upgrade the ImageContentSourcePolicy (the next step and second consideration of your migration from Docker to the IBM Container Registry).

Deploy Mirror Config option of the Helm chart

Implementing ImageContentSourcePolicy to redirect to the IBM Container Registry

The second consideration is upgrading or implementing an ImageContentSourcePolicy to redirect you cluster from docker.io/ibmcom to icr.io/cpopen.

What is an ImageContentSourcePolicy?

The Red Hat OpenShift Container Platform ImageContentSourcePolicy resource updates the image pull process, allowing cluster level configuration of registry mirrors. After the mirror is added, for every image pull attempted by using a digest from the source registry (docker.io/ibmcom), the node attempts to pull from the mirror registry (icr.io/cpopen). If the digest is not found, the cluster reverts to the source registry.

Important: An ImageContentSourcePolicy is implemented by changing the configuration of the cluster nodes. For Red Hat OpenShift Container Platform 4.6 and earlier, all of the worker nodes restart one at a time after implementation. From Red Hat OpenShift Container Platform 4.7 and later, worker nodes are drained, one at a time, without restarting the node. During this process, pods are rescheduled on to alternative nodes. You must ensure that your cluster has sufficient capacity.

Creating or updating ImageContentSourcePolicy

You can create or update an ImageContentSourcePolicy by either of the following methods:

Creating a new ImageContentSourcePolicy

  1. From the navigation bar, click Explore, then enter “imagecontentsourcepolicy” in the filter bar.

  2. Click ImageContentSourcePolicy

    Filtering and clicking ImageContentSourcePolicy

  3. Click Instances, then click Create ImageContentSourcePolicy.

    Creating an ImageContentSourcePolicy

  4. Update the name and spec section, then click Create.

    metadata:
      name: ibm-cpopen-mirror-config
    spec:
      repositoryDigestMirrors:
      - mirrors:
        - icr.io/cpopen
        source: docker.io/ibmcom
    

    Updating `name` and `spec`

  5. Verify that the ImageContentSourcePolicy has been created by clicking Details.

    Verifying the ImageContentSourcePolicy

Updating an ImageContentSourcePolicy

  1. From the navigation bar, click Explore, then enter “imagecontentsourcepolicy” in the filter bar.

  2. Click ImageContentSourcePolicy

    Filtering and clicking ImageContentSourcePolicy

  3. Click Instances, then select the ImageContentSourcePolicy that you want to update.

    Selecting an ImageContentSourcePolicy to update

  4. Click YAML to edit the source YAML. Update the mirrors section to include a mirror from docker.io/ibmcom to icr.io/cpopen.

    Updating the mirror by editing the ImageContentSourcePolicy YAML

  5. Click Save.

    Successfully updated ImageContentSourcePolicy

You have now migrated your images from Docker to the IBM Container Registry.