OpenShift Data Foundation upgrade in disconnected environment with oc-mirror

Solution Verified - Updated

Environment

  • Openshift 4.16+
  • Openshift Data Foundation (ODF) 4.16+

Issue

During the upgrade or new installation of OpenShift Data Foundation (ODF) in a disconnected environment, if it fails you may check the catalog-operator events and see the following error:
type: 'Warning' reason: 'ResolutionFailed' constraints not satisfiable:

That indicates that you are missing a mirror image.

Resolution

Please refer to this source for oc mirror best practice.
oc mirror : A Comprehensive tool for Image Mirroring

Prepare the Air-Gapped CatalogSource ODF Operator Image Requirements

Ensure to meet ODF Operator pre-requisites for a disconnected environment upgrade:

  1. All ODF Operator bundles need to be included in the mirror configuration file
  2. Both ODF Operator versions,i.e., the current installed and the target upgrade version are required in the same operator catalog index image
  3. Openshift CatalogSource name must be the same during the upgrade procedure

Steps 1-2: Prepare the ImageSetConfiguration file

First of all, check the required packages required by odf-operator for a specific Red Hat operator index image:
NOTE: To install the opm cli, refer to the OpenShift CLI tools documentation

  • For ODF < 4.18, up to 4.17.z:
opm-rhel8 render registry.redhat.io/redhat/redhat-operator-index:v4.18 -o json | jq 'select(.name=="odf-operator.v4.17.6-rhodf") | .properties[] | select(.type=="olm.package.required") | .value.packageName'

"cephcsi-operator"
"mcg-operator"
"ocs-client-operator"
"ocs-operator"
"odf-csi-addons-operator"
"odf-prometheus-operator"
"recipe"
"rook-ceph-operator"
  • For ODF >= 4.18:
opm-rhel9 render registry.redhat.io/redhat/redhat-operator-index:v4.18 -o json | jq 'select(.name=="odf-dependencies.v4.18.1-rhodf") | .properties[] | select(.type=="olm.package.required") | .value.packageName'

"cephcsi-operator"
"mcg-operator"
"ocs-client-operator"
"ocs-operator"
"odf-csi-addons-operator"
"odf-prometheus-operator"
"recipe"
"rook-ceph-operator"
"odf-dependencies"
  • For ODF version >= 4.20, we have the below. And also the documentation as guide.
./opm-rhel8 render registry.redhat.io/redhat/redhat-operator-index:v4.20 -o json | jq 'select(.name=="odf-dependencies.v4.20.1-rhodf") | .properties[] | select(.type=="olm.package.required") | .value.packageName'
"cephcsi-operator"
"mcg-operator"
"ocs-client-operator"
"ocs-operator"
"odf-csi-addons-operator"
"odf-external-snapshotter-operator"
"odf-prometheus-operator"
"recipe"
"rook-ceph-operator"

From the official Red Hat Catalog index image target version, always include the target and the previous ODF installed version of all the previous output required packages. An ODF upgrade from ODF 4.17.9 to 4.18.6 is presented in the following ImageSetConfiguration file, config.yaml:

kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v2alpha1
mirror:
  operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.18
    packages:
    - name: odf-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: cephcsi-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: rook-ceph-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: mcg-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: ocs-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: odf-csi-addons-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: recipe
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: ocs-client-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: odf-prometheus-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: odf-dependencies
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
    - name: odf-multicluster-orchestrator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: odr-cluster-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf
    - name: odr-hub-operator
      channels:
      - name: stable-4.18
        minVersion: 4.18.6-rhodf
        maxVersion: 4.18.6-rhodf
      - name: stable-4.17
        minVersion: 4.17.9-rhodf
        maxVersion: 4.17.9-rhodf

To mirror both operator bundles, execute the following command, where:

  • The official Red Hat operator bundles will be read from config.yaml
  • The images will be pushed to the air-gapped-registry-fqdn
  • An operator index image will be generated at /redhat/redhat-operator-index:v4.18

To edit the registry destination, use targetCatalog and targetName fields.

oc-mirror --v2 --workspace file://workspace/ --config=config.yaml docker://<air-gapped-registry-fqdn>

Step 3: Create the disconnected CatalogSource that contains ODF bundles

NOTE: The CatalogSource name should never change between versions and only 1 is needed.

oc get catalogsource -n openshift-marketplace
NAME                             DISPLAY   TYPE   PUBLISHER   AGE
offline-redhat-operator-index              grpc               21h

oc get catalogsource -n openshift-marketplace offline-redhat-operator-index  -oyaml
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  creationTimestamp: "2025-07-04T16:52:51Z"
  generation: 1
  name: offline-redhat-operator-index 
  namespace: openshift-marketplace
  resourceVersion: "19320"
  uid: ce1050ce-d1e3-4b70-b431-d7154abfa8e2
spec:
  image: <air-gapped-registry-fqdn>/redhat/redhat-operator-index:v4.18
  sourceType: grpc
status:
  connectionState:
    address: offline-redhat-operator-index.openshift-marketplace.svc:50051
    lastConnect: "2025-07-04T17:25:46Z"
    lastObservedState: READY
...
...

Ensure it is READY.

Perform ODF Operator Upgrade

With both ODF Operator versions and all packages mirrored, perform the upgrade by updating the odf-operator Subscription channel. 

$ oc -n openshift-storage patch subs odf-operator --type='json' -p='[{"op": "replace", "path": "/spec/channel", "value": "stable-4.18"}]'

Root Cause

SBR
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.