8.3. Creating custom catalogs using the oc-mirror plugin

Procedure

1. Get a list of available Red Hat-provided Operator catalogs to filter by running the following command:

   $ oc mirror list operators --version 4.17 --catalogs

2. Get a list of Operators in the Red Hat Operators catalog by running the following command:

   $ oc mirror list operators <--catalog=<catalog_source>> 

   1

   1

   Specifies your catalog source, such as registry.redhat.io/redhat/redhat-operator-index:v4.17 or quay.io/operatorhubio/catalog:latest.

3. Select an Operator. For this example, amq-broker-rhel8 is selected.

4. Optional: To inspect the channels and versions of the Operator you want to filter, enter the following commands:

   1. Get a list of channels by running the following command:

      $ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v4.17 --package=amq-broker-rhel8

   2. Get a list of versions within a channel by running the following command:

      $ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v4.17 --package=amq-broker-rhel8 --channel=7.11.x

Procedure

1. Use the oc mirror init command to create a template for the image set configuration and save it to a file called imageset-config.yaml:

   $ oc mirror init --registry <storage_backend> > imageset-config.yaml 

   1

   1

   Specifies the location of your storage backend, such as example.com/mirror/oc-mirror-metadata.

   Example default image set configuration file

   kind: ImageSetConfiguration
   apiVersion: mirror.openshift.io/v1alpha2
   storageConfig:
     registry:
       imageURL: registry.example.com/oc-mirror
       skipTLS: false
   mirror:
     platform: 

   1

   
       channels:
       - name: stable-4.17
         type: ocp
     operators:
     - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.17
       packages:
       - name: serverless-operator
         channels:
         - name: stable
     additionalImages: 

   2

   
     - name: registry.redhat.io/ubi8/ubi:latest
     helm: {} 

   3

   1

   The platform field and related fields are not supported by MicroShift and must be deleted.

   2

   Specify any additional images to include in the image set. If you do not need to specify additional images, delete this field.

   3

   Helm is not supported by MicroShift and must be deleted.

2. Edit the values of your image set configuration file to meet the requirements of both MicroShift and the Operator you want to mirror, like the following example:

   Example edited MicroShift image set configuration file

   kind: ImageSetConfiguration
   apiVersion: mirror.openshift.io/v1alpha2
   storageConfig: 

   1

   
     registry:
       imageURL: <storage_backend> 

   2

   
       skipTLS: false
   mirror:
     operators:
     - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.17 

   3

   
       packages:
       - name: amq-broker-rhel8 

   4

   
         channels:
         - name: 7.11.x 

   5

   1

   Set the backend location where the image set metadata is saved. This location can be a registry or local directory. It is required to specify storageConfig values.

   2

   Set the registry URL for the storage backend, such as <example.com/mirror/oc-mirror-metadata.

   3

   Set the Operator catalog to retrieve images from.

   4

   Specify the Operator packages to include in the image set. Remove this field to retrieve all packages in the catalog.

   5

   Specify only certain channels of the Operator packages to include in the image set. You must always include the default channel for the Operator package even if you do not use the bundles in that channel. You can find the default channel by running the following command: oc mirror list operators --catalog=<catalog_name> --package=<package_name>.

3. Save the updated file.

Verification

1. Navigate into the oc-mirror-workspace/ directory that was generated.
2. Navigate into the results directory, for example, results-1639608409/.
3. Verify that YAML files are present for the ImageContentSourcePolicy and CatalogSource resources.

Procedure

1. Confirm the contents of the imageContentSourcePolicy.yaml file by running the following command:

   $ cat oc-mirror-workspace/<results-directory>/imageContentSourcePolicy.yaml 

   1

   1

   Specify the results directory name, such as <results-1707148826>.

   Example output

   apiVersion: operator.openshift.io/v1alpha1
   kind: ImageContentSourcePolicy
   metadata:
     labels:
       operators.openshift.org/catalog: "true"
     name: operator-0
   spec:
     repositoryDigestMirrors:
     - mirrors:
       - registry.<example.com>/amq7
       source: registry.redhat.io/amq7

2. Transform the imageContentSourcePolicy.yaml into a format ready for CRI-O configuration by running the following command:

   yq '.spec.repositoryDigestMirrors[] as $item ireduce([]; . + [{"mirror": $item.mirrors[], "source": ($item | .source)}]) | .[] |
     "[[registry]]
         prefix = \"" + .source + "\"
         location = \"" + .mirror + "\"
         mirror-by-digest-only = true
         insecure = true
         "' ./icsp.yaml

   Example output

   [[registry]]
         prefix = "registry.redhat.io/amq7"
         location = "registry.example.com/amq7"
         mirror-by-digest-only = true
         insecure = true

3. Add the output to the CRI-O configuration file in the /etc/containers/registries.conf.d/ directory:

   Example crio-config.yaml mirror configuration file

   [[registry]]
         prefix = "registry.redhat.io/amq7"
         location = "registry.example.com/amq7"
         mirror-by-digest-only = true
         insecure = true
   
   [[registry]]
       prefix = ""
       location = "quay.io"
       mirror-by-digest-only = true
   [[registry.mirror]]
       location = "<registry_host>:<port>" 

   1

   
       insecure = false

   1

   Specify the host name and port of your mirror registry server, for example microshift-quay:8443.

4. Apply the CRI-O configuration changes by restarting MicroShift with the following command:

   $ sudo systemctl restart crio

Procedure

1. Apply the catalog source configuration file from the results directory to create the catalog source object by running the following command:

   $ oc apply -f ./oc-mirror-workspace/results-1708508014/catalogSource-cs-redhat-operator-index.yaml

   Example catalog source configuration file

   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
     name: redhat-catalog
     namespace: openshift-marketplace 

   1

   
   spec:
     sourceType: grpc
     image: registry.example.com/redhat/redhat-operator-index:v4.17
     updateStrategy:
       registryPoll:
         interval: 60m

   1

   Specifies the global namespace. Setting the metadata.namespace to openshift-marketplace enables the catalog to reference catalogs in all namespaces. Subscriptions in any namespace can reference catalogs created in the openshift-marketplace namespace.

   Example output

   catalogsource.operators.coreos.com/cs-redhat-operator-index created

2. Verify that the CatalogSource resources were successfully installed by running the following command:

   $ oc get catalogsource --all-namespaces

3. Verify that the catalog source is running by using the following command:

   $ oc get pods -n openshift-marketplace

   Example output

   NAME                             READY   STATUS    RESTARTS   AGE
   cs-redhat-operator-index-4227b   2/2     Running   0          2m5s

4. Create a Subscription CR, similar to the following example:

   Example Subscription CR

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: amq-broker
     namespace: openshift-operators
   spec:
     channel: 7.11.x
     name: amq-broker-rhel8
     source: cs-redhat-operator-index
     sourceNamespace: openshift-marketplace

5. Apply the Subscription CR configuration by running the following command:

   $ oc apply -f ./<my-subscription-cr.yaml> 

   1

   1

   Specify the name of your subscription, such as my-subscription-cr.yaml.

   Example output

   subscription.operators.coreos.com/amq-broker created