Page
Defining and configuring your operators for use with oc-mirror
Now that you have a list of operators that can be feasibly used with the version of OpenShift deployed in your environment, itβs time to set up a YAML file to define the set of operator catalogs, packages, channels, and versions to be mirrored.
- Refer to this documentation for ImageSetConfiguration parameters.
- Refer to this documentation for ImageSetConfiguration examples.
Prerequisites:
- Available operator catalogs for your OpenShift version.
In this lesson, you will:
- Construct an
ImageSetConfigurationYAML file for your particular set of operators.
The following example demonstrates a sample ImageSetConfiguration used to mirror Operators with oc mirror version 2.
It is recommended to create a dedicated ImageSetConfiguration file for each catalog to maintain clarity and modularity. In this approach, separate configuration files have been created for Red Hat Operators and Certified Operators.
This segregation simplifies catalog management and supports better traceability during installation or upgrade activities in disconnected environments.
The Red Hat Operators ImageSetConfiguration:
apiVersion: mirror.openshift.io/v2alpha1
kind: ImageSetConfiguration
mirror:
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.17
packages:
- name: kiali-ossm
channels:
- name: stable
minVersion: '1.65.11'
maxVersion: '1.73.4'
- name: cincinnati-operator
channels:
- name: v1
minVersion: 5.0.0
maxVersion: 5.0.2
- name: servicemeshoperator
channels:
- name: stable
minVersion: '2.4.5-0'
maxVersion: '2.5.0-0'
- name: compliance-operator
channels:
- name: stable
minVersion: '1.4.0'
maxVersion: '1.6.0'
additionalImages:
- name: registry.redhat.io/ubi9/ubi:latest
- name: registry.redhat.io/rhel9/support-tools:latest
helm: {}The Certified Operators ImageSetConfiguration:
kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v2alpha1
mirror:
operators:
- catalog: registry.redhat.io/redhat/certified-operator-index:v4.17
packages:
- name: redis-enterprise-operator-cert
channels:
- name: production
minVersion: '7.4.6-2.3'
maxVersion: '7.4.6-6.3'
additionalImages:
- name: registry.redhat.io/ubi9/ubi:latest
- name: registry.redhat.io/rhel9/support-tools:latest
helm: {}The oc-mirror v2 plugin introduces significant enhancements and architectural changes to the Operator and OpenShift image mirroring workflows. Unlike the v1 workflow, which relied on Docker registry metadata and multiple manual steps, v2 leverages a declarative configuration model that streamlines the mirroring process, improves reproducibility, and provides more granular control over the images and catalogs being mirrored.
Changes from oc-mirror plugin v1 to v2
Before migrating from the oc-mirror plugin v1 to v2, note the following differences between oc-mirror plugin v1 and v2:
Explicit version selection: Users must explicitly specify --v2 when using oc-mirror. If no version is specified, v1 is executed by default. This behavior is expected to change in future releases, where --v2 will be the default.
Updated commands: Commands for mirroring workflows have changed to align with the oc-mirror plugin v2βs new workflow.
- For mirror-to-disk, run the following command:
oc-mirror --config isc.yaml file://<directory_name> --v2
- For disk-to-mirror, run the following command:
oc-mirror --config isc.yaml --from file://<directory_name> docker://<remote_registry> --v2
- For mirror-to-mirror, run the following command:
oc-mirror --config isc.yaml --workspace file://<directory_name> docker://<remote_registry> --v2
More detailed information about oc-mirror plugin v2 is available in this guide.
In this example, we will be mirroring both Red Hat and Certified Operators to a designated mirror registry. To streamline the process and ensure organized resource management, the following directory structure is employed:
Red Hat Operators:
/registry/ocp417/rh-operatorsCertified Operators:
/registry/ocp417/certified-operator[root@registry IB]# oc-mirror --v2 -c rh_op_ibimagest-config.yaml --workspace file:///registry/ocp417/rh-operators/ docker://registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/rh-operators --dest-tls-verify=false 2025/05/06 12:49:45 [INFO] : π Hello, welcome to oc-mirror 2025/05/06 12:49:45 [INFO] : βοΈ setting up the environment for you... 2025/05/06 12:49:45 [INFO] : π workflow mode: mirrorToMirror 2025/05/06 12:49:45 [INFO] : π΅ going to discover the necessary images... 2025/05/06 12:49:45 [INFO] : π collecting release images... 2025/05/06 12:49:45 [INFO] : π collecting operator images... β (0s) Collecting catalog registry.redhat.io/redhat/redhat-operator-index:v4.17 2025/05/06 12:49:45 [INFO] : π collecting additional images... 2025/05/06 12:49:45 [INFO] : π collecting helm images... 2025/05/06 12:49:45 [INFO] : π rebuilding catalogs 2025/05/06 12:49:45 [INFO] : π Start copying the images... 2025/05/06 12:49:45 [INFO] : π images to copy 94 β (1m19s) kiali-rhel8@sha256:78ab615c0fd4d86a9b524066229ff78879d5e587c0b3bd0263ea0898a60d4ed6 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/rh-operators/openshift-service-mesh/ β (1m39s) openshift-compliance-rhel8-operator@sha256:f00b64570a1e753f68e617d3583956d71084073541f50d7c2e3ac9d66d6a0486 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/rh-operators/compliance/ β (1m41s) kiali-rhel8@sha256:ce946458d16ed9f56480def29aa85c5954c7868b33e08b88fe8c89ed650bb478 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/rh-operators/openshift-service-mesh/ β (2m4s) kiali-rhel8@sha256:7ef41fb8e5ce2b394d67d8dd06bb23f49e249e0c4371cc49659cf2049ae8ad9a β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/rh-operators/openshift-service-mesh/ [.....] # Output Truncated 94 / 94 (12m49s) [=====================================================================================================================================================================================================================================================] 100 % β (1m7s) redhat-operator-index:v4.17 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/rh-operators/redhat/ 2025/05/06 13:02:35 [INFO] : === Results === 2025/05/06 13:02:35 [INFO] : β 92 / 92 operator images mirrored successfully 2025/05/06 13:02:35 [INFO] : β 2 / 2 additional images mirrored successfully 2025/05/06 13:02:35 [INFO] : π Generating IDMS file... 2025/05/06 13:02:35 [INFO] : /registry/ocp417/rh-operators/working-dir/cluster-resources/idms-oc-mirror.yaml file created 2025/05/06 13:02:35 [INFO] : π Generating ITMS file... 2025/05/06 13:02:35 [INFO] : /registry/ocp417/rh-operators/working-dir/cluster-resources/itms-oc-mirror.yaml file created 2025/05/06 13:02:35 [INFO] : π Generating CatalogSource file... 2025/05/06 13:02:35 [INFO] : /registry/ocp417/rh-operators/working-dir/cluster-resources/cs-redhat-operator-index-v4-17.yaml file created 2025/05/06 13:02:35 [INFO] : π Generating ClusterCatalog file... 2025/05/06 13:02:35 [INFO] : /registry/ocp417/rh-operators/working-dir/cluster-resources/cc-redhat-operator-index-v4-17.yaml file created 2025/05/06 13:02:35 [INFO] : mirror time : 12m49.870945165s 2025/05/06 13:02:35 [INFO] : π Goodbye, thank you for using oc-mirror [root@registry IB]#Similarly, the Certified Operators are mirrored to the internal mirror registry using a structured directory approach for efficient resource management. The directory designated for Certified Operators is:
Certified Operators:
/registry/ocp417/certified-operators[root@registry IB]# cat ce_op_ibimagest-config.yaml kind: ImageSetConfiguration apiVersion: mirror.openshift.io/v2alpha1 mirror: operators: - catalog: registry.redhat.io/redhat/certified-operator-index:v4.17 packages: - name: redis-enterprise-operator-cert channels: - name: production minVersion: '7.8.4-9.0' maxVersion: '7.8.6-1.0' additionalImages: - name: registry.redhat.io/ubi9/ubi:latest - name: registry.redhat.io/rhel9/support-tools:latest helm: {}[root@registry IB]# oc-mirror --v2 -c ce_op_ibimagest-config.yaml --workspace file:///registry/ocp417/certified-operators/ docker://registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/certified-operators --dest-tls-verify=false 2025/05/06 13:05:19 [INFO] : π Hello, welcome to oc-mirror 2025/05/06 13:05:19 [INFO] : βοΈ setting up the environment for you... 2025/05/06 13:05:19 [INFO] : π workflow mode: mirrorToMirror 2025/05/06 13:05:19 [INFO] : π΅ going to discover the necessary images... 2025/05/06 13:05:19 [INFO] : π collecting release images... 2025/05/06 13:05:19 [INFO] : π collecting operator images... β (28s) Collecting catalog registry.redhat.io/redhat/certified-operator-index:v4.17 2025/05/06 13:05:48 [INFO] : π collecting additional images... 2025/05/06 13:05:48 [INFO] : π collecting helm images... 2025/05/06 13:05:48 [INFO] : π rebuilding catalogs β (1s) Rebuilding catalog docker://registry.redhat.io/redhat/certified-operator-index:v4.17 2025/05/06 13:05:50 [INFO] : π Start copying the images... 2025/05/06 13:05:50 [INFO] : π images to copy 17 β (29s) services-manager@sha256:e14a4cdef083787e2b8f82a01ebfaef5f17d57dc968564a94831d3fb0aa8e311 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/certified-operators/redislabs/ β (29s) redis-enterprise-operator@sha256:1482441faf169399d9fd43114a954c45f8fe20ad62de4b3193babd6664b5efa9 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/certified-operators/redislabs/ β (29s) redis-enterprise-operator@sha256:89e6a66ff6bf0d4830daa372ea15e1462c2a3057f4f42534aa1ccff056d512b5 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/certified-operators/redislabs/ 17 / 17 (2m45s) [====================================================================================================================================================================================================================] 100 % β (1m27s) redis-enterprise@sha256:4ba0c414a74268bed9c6757e447b340db7c912afa864cfb096ddf88f11feeaf9 β‘οΈ registry.shemadhr.tamlab.rdu2.redhat.com/quayadmin/ocp417/certified-operators/redislabs/ 2025/05/06 13:08:36 [INFO] : === Results === 2025/05/06 13:08:36 [INFO] : β 15 / 15 operator images mirrored successfully 2025/05/06 13:08:36 [INFO] : β 2 / 2 additional images mirrored successfully 2025/05/06 13:08:36 [INFO] : π Generating IDMS file... 2025/05/06 13:08:36 [INFO] : /registry/ocp417/certified-operators/working-dir/cluster-resources/idms-oc-mirror.yaml file created 2025/05/06 13:08:36 [INFO] : π Generating ITMS file... 2025/05/06 13:08:36 [INFO] : /registry/ocp417/certified-operators/working-dir/cluster-resources/itms-oc-mirror.yaml file created 2025/05/06 13:08:36 [INFO] : π Generating CatalogSource file... 2025/05/06 13:08:36 [INFO] : /registry/ocp417/certified-operators/working-dir/cluster-resources/cs-certified-operator-index-v4-17.yaml file created 2025/05/06 13:08:36 [INFO] : π Generating ClusterCatalog file... 2025/05/06 13:08:36 [INFO] : /registry/ocp417/certified-operators/working-dir/cluster-resources/cc-certified-operator-index-v4-17.yaml file created 2025/05/06 13:08:36 [INFO] : mirror time : 3m16.620018721s 2025/05/06 13:08:36 [INFO] : π Goodbye, thank you for using oc-mirror [root@registry IB]#After the mirroring process, the cluster resources are generated in the following directories:
Red Hat Operators:
/registry/ocp417/rh-operators/working-dir/cluster-resourcesCertified Operators:
/registry/ocp417/certified-operators/working-dir/cluster-resources[root@registry cluster-resources]# ls cc-certified-operator-index-v4-17.yaml cs-certified-operator-index-v4-17.yaml idms-oc-mirror.yaml itms-oc-mirror.yaml [root@registry cluster-resources]# pwd /registry/ocp417/certified-operators/working-dir/cluster-resources [root@registry cluster-resources]#[root@registry cluster-resources]# ls cc-redhat-operator-index-v4-17.yaml cs-redhat-operator-index-v4-17.yaml idms-oc-mirror.yaml itms-oc-mirror.yaml [root@registry cluster-resources]# pwd /registry/ocp417/rh-operators/working-dir/cluster-resources [root@registry cluster-resources]#Log in to the cluster with
cluster-adminprivileges.[root@registry cluster-resources]# oc whoami kube:admin [root@registry cluster-resources]# oc get catalogsources -A No resources found [root@registry cluster-resources]# [root@registry cluster-resources]# oc apply -f . catalogsource.operators.coreos.com/cs-redhat-operator-index-v4-17 created imagedigestmirrorset.config.openshift.io/idms-operator-0 configured imagetagmirrorset.config.openshift.io/itms-generic-0 configured [root@registry cluster-resources]#
Note
When applying cluster resources, you may encounter an error as outlined below. If you are not utilizing the OpenShift Update Service (OSUS), this error can be safely disregarded. For further details on OSUS and its usage in a disconnected environment. Please refer to the documentation below on Updating a Cluster in a Disconnected Environment Using OpenShift Update Service:
- Refer to this Documentation on Updating a Cluster in a Disconnected Environment Using OpenShift Update Service
error: resource mapping not found for name: "cc-redhat-operator-index-v4-17" namespace: "" from "cc-redhat-operator-index-v4-17.yaml": no matches for kind "ClusterCatalog" in version "olm.operatorframework.io/v1"
ensure CRDs are installed firstYou have now defined and configured your operators and created the proper YAML file. Let's move on to validating your operators in the next lesson.
