Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 8. Operators

8.1. Using Operators with MicroShift
Copy link

You can use Operators with MicroShift to create applications that monitor the running services in your node. As customized software running inside your node, you can use Operators to implement and automate common operations.

You can use Operators to manage applications and their resources, such as deploying a database or message bus.

Operators offer a more localized configuration experience and integrate with Kubernetes APIs and CLI tools such as kubectl and oc. You can design or use Operators that are specifically for your applications. By using Operators, you can configure components instead of modifying a global configuration file.

MicroShift applications are generally expected to be deployed in static environments. However, Operators are available if helpful in your use case. To discover whether an Operator is compatible with MicroShift, check the Operator documentation.

8.1.2. How to use Operators with a MicroShift node
Copy link

There are two ways to install and manage Operators for your MicroShift node. You can use manifests or Operator Lifecycle Manager (OLM).

8.1.2.1. Manifests for Operators
Copy link

You can install and manage Operators directly by using manifests. You can use the kustomize configuration management tool with MicroShift to deploy an application. Use the same steps to install Operators with manifests. For more information, see the following links:

8.1.2.2. Operator Lifecycle Manager for Operators
Copy link

You can also install add-on Operators to a MicroShift node by using Operator Lifecycle Manager (OLM). OLM can be used to manage both custom Operators and Operators that are widely available. Building catalogs is required to use OLM with MicroShift. For more information, see the following link:

You can use Operator Lifecycle Manager (OLM) with MicroShift to install and run optional add-on Operators.

You must consider the application of Operators and steps to use them when planning which ones you want to use with your MicroShift platform.

  • Cluster Operators as applied in OpenShift Container Platform are not used in MicroShift.

  • You must create your own catalogs for the add-on Operators you want to use with your applications. Catalogs are not provided by default.

    • Each catalog must have an accessible CatalogSource added to a node, so that the OLM catalog Operator can use the catalog for content.

You must use the CLI to conduct OLM activities with MicroShift. The console and OperatorHub GUIs are not available.

  • Use the Operator Package Manager (opm) CLI with a network-connected node, or for building catalogs for custom Operators that use an internal registry. See the following link for more information:

  • To mirror your catalogs and Operators for disconnected or offline nodes, install the oc-mirror tool. See the following link for more information:

Important

Before using an Operator, verify with the provider that the Operator is supported on MicroShift.

8.2.2. Determining your OLM installation type
Copy link

You can install Operator Lifecycle Manager (OLM) for use with MicroShift 4.16 or newer versions. There are different ways to install OLM for a MicroShift node, depending on your use case.

8.2.3. Namespace use in MicroShift
Copy link

The microshift-olm RPM creates the three default namespaces: one for running Operator Lifecycle Manager (OLM), and two for catalog and Operator installation. You can create additional namespaces as needed for your use case.

8.2.3.1. Default namespaces
Copy link

The following table lists the default namespaces and a brief description of how each namespace works.

Expand
Table 8.1. Default namespaces created by OLM for MicroShift

Default Namespace

Details

openshift-operator-lifecycle-manager

The OLM package manager runs in this namespace.

openshift-marketplace

The global namespace. Empty by default. To make the catalog source to be available globally to users in all namespaces, set the openshift-marketplace namespace in the catalog-source YAML.

openshift-operators

The default namespace where Operators run in MicroShift. Operators that reference catalogs in the openshift-operators namespace must have the AllNamespaces watch scope.

8.2.3.2. Custom namespaces
Copy link

If you want to use a catalog and Operator together in a single namespace, then you must create a custom namespace. After you create the namespace, you must create the catalog in that namespace. All Operators running in the custom namespace must have the same single-namespace watch scope.

8.2.4. About building Operator catalogs
Copy link

To use Operator Lifecycle Manager (OLM) with MicroShift, you must build custom Operator catalogs that you can then manage with OLM. The standard catalogs that are included with OpenShift Container Platform are not included with MicroShift.

8.2.4.1. File-based Operator catalogs
Copy link

You can create catalogs for your custom Operators or filter catalogs of widely available Operators. You can combine both methods to create the catalogs needed for your specific use case. To run MicroShift with your own Operators and OLM, make a catalog by using the file-based catalog structure.

Important

When adding a catalog source to a cluster, set the securityContextConfig value to restricted in the catalogSource.yaml file. Ensure that your catalog can run with restricted permissions. For more information, see:

8.2.5. How to deploy Operators using OLM
Copy link

After you create and deploy your custom catalog, you must create a Subscription custom resource (CR) that can access the catalog and install the Operators you choose. Where Operators run depends on the namespace in which you create the Subscription CR.

Important

Operators that you are managing with Operator Lifecycle Manager (OLM) have a watch scope. For example, some Operators only support watching their own namespace, while others support watching every namespace in the node. All Operators installed in a given namespace must have the same watch scope.

8.2.5.1. Connectivity and OLM Operator deployment
Copy link

You can deploy Operators anywhere a catalog is running. For example:

  • For a node that is connected to the internet, mirroring images is not required. Images can be pulled over the network.
  • For restricted networks in which MicroShift has access to an internal network only, images must be mirrored to an internal registry.
  • For use cases in which a MicroShift node is completely offline, all images must be embedded into an osbuild blueprint.

To deploy different Operators to different namespaces, follow the basic steps to use configuration files to install an Operator that uses the global namespace.

For a MicroShift node that has network connectivity, Operator Lifecycle Manager (OLM) can access sources hosted on remote registries.

Note

To use an Operator installed in a different namespace, or in more than one namespace, make sure that both the catalog source and the Subscription CR that references the Operator are running in the openshift-marketplace namespace.

Prerequisites

  • The OpenShift CLI (oc) is installed.
  • Operator Lifecycle Manager (OLM) is installed.
  • You created a custom catalog in the global namespace.

Procedure

  1. Confirm that OLM is running by using the following command: 

    $ oc -n openshift-operator-lifecycle-manager get pod -l app=olm-operator

    Example output

    NAME                            READY   STATUS    RESTARTS   AGE
olm-operator-85b5c6786-n6kbc    1/1     Running   0          2m24s

  2. Confirm that the OLM catalog Operator is running by using the following command: 

    $ oc -n openshift-operator-lifecycle-manager get pod -l app=catalog-operator

    Example output

    NAME                                READY   STATUS    RESTARTS   AGE
catalog-operator-5fc7f857b6-tj8cf   1/1     Running   0          2m33s

    Note

    The following steps assume you are using the global namespace, openshift-marketplace. The catalog must run in the same namespace as the Operator. The Operator must support the AllNamespaces mode.

  3. Create the CatalogSource object by using the following example YAML:

    Example catalog source YAML

    apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: operatorhubio-catalog
  namespace: openshift-marketplace
    1 
    
spec:
  sourceType: grpc
  image: quay.io/operatorhubio/catalog:latest
  displayName: Community Operators
    2 
    
  publisher: OperatorHub.io
  grpcPodConfig:
    securityContextConfig: restricted
    3 
    
  updateStrategy:
    registryPoll:
      interval: 60m

    1
    The global namespace. Setting the metadata.namespace to openshift-marketplace enables the catalog to run in all namespaces. Subscriptions in any namespace can reference catalogs created in the openshift-marketplace namespace.
    2
    Community Operators are not installed by default with OLM for MicroShift. Listed here for example only.
    3
    The value of securityContextConfig must be set to restricted for MicroShift.

  4. Apply the CatalogSource configuration by running the following command: 

    $ oc apply -f <my-catalog-source.yaml>
    1
    1
    Replace <my-catalog-source.yaml> with your catalog source configuration file name. In this example, catalogsource.yaml is used.

    Example output

    catalogsource.operators.coreos.com/operatorhubio-catalog created

  5. To verify that the catalog source is applied, check for the READY state by using the following command: 

    $ oc describe catalogsources.operators.coreos.com -n openshift-marketplace operatorhubio-catalog

    Example output

    Name:         operatorhubio-catalog
Namespace:    openshift-marketplace
Labels:       <none>
Annotations:  <none>
API Version:  operators.coreos.com/v1alpha1
Kind:         CatalogSource
Metadata:
  Creation Timestamp:  2024-01-31T09:55:31Z
  Generation:          1
  Resource Version:    1212
  UID:                 4edc1a96-83cd-4de9-ac8c-c269ca895f3e
Spec:
  Display Name:  Community Operators
  Grpc Pod Config:
    Security Context Config:  restricted
  Image:                      quay.io/operatorhubio/catalog:latest
  Publisher:                  OperatorHub.io
  Source Type:                grpc
  Update Strategy:
    Registry Poll:
      Interval:  60m
Status:
  Connection State:
    Address:              operatorhubio-catalog.openshift-marketplace.svc:50051
    Last Connect:         2024-01-31T09:55:57Z
    Last Observed State:  READY
    1 
    
  Registry Service:
    Created At:         2024-01-31T09:55:31Z
    Port:               50051
    Protocol:           grpc
    Service Name:       operatorhubio-catalog
    Service Namespace:  openshift-marketplace
Events:                 <none>

    1
    The status is reported as READY.

  6. Confirm that the catalog source is running by using the following command: 

    $ oc get pods -n openshift-marketplace -l olm.catalogSource=operatorhubio-catalog

    Example output

    NAME                          READY   STATUS    RESTARTS   AGE
operatorhubio-catalog-x24nh   1/1     Running   0          59s

  7. Create a Subscription CR configuration file by using the following example YAML:

    Example Subscription custom resource YAML

    apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: my-cert-manager
  namespace: openshift-operators
spec:
  channel: stable
  name: cert-manager
  source: operatorhubio-catalog
  sourceNamespace: openshift-marketplace
    1

    1
    The global namespace. Setting the sourceNamespace value to openshift-marketplace enables Operators to run in multiple namespaces if the catalog also runs in the openshift-marketplace namespace.

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

    $ oc apply -f <my-subscription-cr.yaml>
    1
    1
    Replace <my-subscription-cr.yaml> with your Subscription CR filename. In this example, sub.yaml is used.

    Example output

    subscription.operators.coreos.com/my-cert-manager created

  9. You can create a configuration file for the specific Operand you want to use and apply it now.

Verification

  • Verify that your Operator is running by using the following command: 

    $ oc get pods -n openshift-operators
    1
    1
    The namespace from the Subscription CR is used.
    Note

    Allow a minute or two for the Operator start.

    Example output

    NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-7df8994ddb-4vrkr              1/1     Running   0          19s
cert-manager-cainjector-5746db8fd7-69442   1/1     Running   0          18s
cert-manager-webhook-f858bf58b-748nt       1/1     Running   0          18s

You can specify a namespace for an Operator for a variety of reasons, such as security and resource isolation. For example, you can specify the namespace olm-microshift.

In the following example, the catalog is scoped and available in the global openshift-marketplace namespace. The Operator uses content from the global namespace, but runs only in the olm-microshift namespace. For a MicroShift node that has network connectivity, Operator Lifecycle Manager (OLM) can access sources hosted on remote registries.

Important

All of the Operators installed in a specific namespace must have the same watch scope. In this case, the watch scope is OwnNamespace.

Prerequisites

  • The OpenShift CLI (oc) is installed.
  • Operator Lifecycle Manager (OLM) is installed.
  • You created a custom catalog that is running in the global namespace.

Procedure

  1. Confirm that OLM is running by using the following command: 

    $ oc -n openshift-operator-lifecycle-manager get pod -l app=olm-operator

    Example output

    NAME                           READY   STATUS    RESTARTS   AGE
olm-operator-85b5c6786-n6kbc   1/1     Running   0          16m

  2. Confirm that the OLM catalog Operator is running by using the following command: 

    $ oc -n openshift-operator-lifecycle-manager get pod -l app=catalog-operator

    Example output

    NAME                                READY   STATUS    RESTARTS   AGE
catalog-operator-5fc7f857b6-tj8cf   1/1     Running   0          16m

  3. Create a namespace by using the following example YAML:

    Example namespace YAML

    apiVersion: v1
kind: Namespace
metadata:
  name: olm-microshift

  4. Apply the namespace configuration using the following command: 

    $ oc apply -f <ns.yaml>
    1
    1
    Replace <ns.yaml> with the name of your namespace configuration file. In this example, olm-microshift is used.

    Example output

    namespace/olm-microshift created

  5. Create the Operator group YAML by using the following example YAML:

    Example Operator group YAML

    kind: OperatorGroup
apiVersion: operators.coreos.com/v1
metadata:
  name: og
  namespace: olm-microshift
spec:
    1 
    
  targetNamespaces:
  - olm-microshift

    1
    For Operators using the global namespace, omit the spec.targetNamespaces field and values.

  6. Apply the Operator group configuration by running the following command: 

    $ oc apply -f <og.yaml>
    1
    1
    Replace <og.yaml> with the name of your operator group configuration file.

    Example output

    operatorgroup.operators.coreos.com/og created

  7. Create the CatalogSource object by using the following example YAML:

    Example catalog source YAML

    apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: operatorhubio-catalog
  namespace: openshift-marketplace
    1 
    
spec:
  sourceType: grpc
  image: quay.io/operatorhubio/catalog:latest
  displayName: Community Operators
    2 
    
  publisher: OperatorHub.io
  grpcPodConfig:
    securityContextConfig: restricted
    3 
    
  updateStrategy:
    registryPoll:
      interval: 60m

    1
    The global namespace. Setting the metadata.namespace to openshift-marketplace enables the catalog to run in all namespaces. Subscriptions CRs in any namespace can reference catalogs created in the openshift-marketplace namespace.
    2
    Community Operators are not installed by default with OLM for MicroShift. Listed here for example only.
    3
    The value of securityContextConfig must be set to restricted for MicroShift.

  8. Apply the CatalogSource configuration by running the following command: 

    $ oc apply -f <my-catalog-source.yaml>
    1
    1
    Replace <my-catalog-source.yaml> with your catalog source configuration file name.

  9. To verify that the catalog source is applied, check for the READY state by using the following command: 

    $ oc describe catalogsources.operators.coreos.com -n openshift-marketplace operatorhubio-catalog

    Example output

    Name:         operatorhubio-catalog
Namespace:    openshift-marketplace
Labels:       <none>
Annotations:  <none>
API Version:  operators.coreos.com/v1alpha1
Kind:         CatalogSource
Metadata:
  Creation Timestamp:  2024-01-31T10:09:46Z
  Generation:          1
  Resource Version:    2811
  UID:                 60ce4a36-86d3-4921-b9fc-84d67c28df48
Spec:
  Display Name:  Community Operators
  Grpc Pod Config:
    Security Context Config:  restricted
  Image:                      quay.io/operatorhubio/catalog:latest
  Publisher:                  OperatorHub.io
  Source Type:                grpc
  Update Strategy:
    Registry Poll:
      Interval:  60m
Status:
  Connection State:
    Address:              operatorhubio-catalog.openshift-marketplace.svc:50051
    Last Connect:         2024-01-31T10:10:04Z
    Last Observed State:  READY
    1 
    
  Registry Service:
    Created At:         2024-01-31T10:09:46Z
    Port:               50051
    Protocol:           grpc
    Service Name:       operatorhubio-catalog
    Service Namespace:  openshift-marketplace
Events:                 <none>

    1
    The status is reported as READY.

  10. Confirm that the catalog source is running by using the following command: 

    $ oc get pods -n openshift-marketplace -l olm.catalogSource=operatorhubio-catalog

    Example output

    NAME                          READY   STATUS    RESTARTS   AGE
operatorhubio-catalog-j7sc8   1/1     Running   0          43s

  11. Create a Subscription CR configuration file by using the following example YAML:

    Example Subscription custom resource YAML

    apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: my-gitlab-operator-kubernetes
  namespace: olm-microshift
    1 
    
spec:
  channel: stable
  name: gitlab-operator-kubernetes
  source: operatorhubio-catalog
  sourceNamespace: openshift-marketplace
    2

    1
    The specific namespace. Operators reference the global namespace for content, but run in the olm-microshift namespace.
    2
    The global namespace. Subscriptions CRs in any namespace can reference catalogs created in the openshift-marketplace namespace.

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

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

    Example output

    subscription.operators.coreos.com/my-gitlab-operator-kubernetes

  13. You can create a configuration file for the specific Operand you want to use and apply it now.

Verification

  • Verify that your Operator is running by using the following command: 

    $ oc get pods -n olm-microshift
    1
    1
    The namespace from the Subscription CR is used.
    Note

    Allow a minute or two for the Operator start.

    Example output

    NAME                                         READY   STATUS    RESTARTS   AGE
gitlab-controller-manager-69bb6df7d6-g7ntx   2/2     Running   0          3m24s

You can create custom catalogs with widely available Operators and mirror them by using the oc-mirror OpenShift CLI (oc) plugin. Custom catalogs give you the tool so that you can host Operators locally, or control a variety of factors, such as versions and access.

You can use the oc-mirror OpenShift CLI (oc) plugin with MicroShift to filter and prune Operator catalogs. You can also use Operators in disconnected settings or embedded in Red Hat Enterprise Linux for Edge (RHEL for Edge) images.

You can then mirror the filtered catalog contents to a mirror registry or use the container images in disconnected or offline deployments with RHEL for Edge.

Note

MicroShift uses the generally available version, v1, of the oc-mirror plugin. Do not use the following procedures with the Technical Preview versio, v2, of oc-mirror plugin.

You can mirror the container images required by the desired Operators locally or to a container mirror registry that supports Docker v2-2, such as {quay}. The procedure to mirror content from Red Hat-hosted registries connected to the internet to a disconnected image registry is the same, independent of the registry you choose. After you mirror the contents of your catalog, configure each cluster to retrieve this content from your mirror registry.

When you populate your registry, you can use one of following connectivity scenarios:

Connected mirroring
If you have a host that can access both the internet and your mirror registry, but not your cluster node, you can directly mirror the content from that machine.
Disconnected mirroring

If you do not have a host that can access both the internet and your mirror registry, you must mirror the images to a file system and then bring that host or removable media into your disconnected environment.

Important

A container registry must be reachable by every machine in the clusters that you provision. Installing, updating, and other operations, such as relocating workloads, might fail if the registry is unreachable.

To avoid problems caused by an unreachable registry, use the following standard practices:

  • Run mirror registries in a highly available way.
  • Ensure that the mirror registry at least matches the production availability of your clusters.

The procedure to mirror content from Red Hat-hosted registries connected to the internet to a disconnected image registry is the same, independent of the registry you select. After you mirror the contents of your catalog, configure each node to retrieve this content from your mirror registry.

Use the following example procedure to select a catalog and list Operators from available OpenShift Container Platform content to add to your oc-mirror plugin image set configuration file.

Note

If you use your own catalogs and Operators, you can push the images directly to your internal registry.

Prerequisites

  • The OpenShift CLI (oc) is installed.
  • Operator Lifecycle Manager (OLM) is installed.
  • The oc-mirror OpenShift CLI (oc) plugin is installed.

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.16 --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.16 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.16 --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.16 --package=amq-broker-rhel8 --channel=7.11.x

Next steps

  • Create and edit an image set configuration file using the information gathered in this procedure.
  • Mirror the images from the transformed image set configuration file to a mirror registry or disk.

8.3.1.3. Creating an image set configuration file
Copy link

You must create an image set configuration file to mirror catalog contents with the oc-mirror plugin. The image set configuration file defines which Operators to mirror along with other configuration settings for the oc-mirror plugin.

After generating a default image set file, you must edit the contents so that remaining entries are compatible with both MicroShift and the Operator you plan to use.

You must specify a storage backend in the image set configuration file. This storage backend can be a local directory or a registry that supports Docker v2-2. The oc-mirror plugin stores metadata in this storage backend during image set creation.

Important

Do not delete or modify the metadata that is generated by the oc-mirror plugin. You must use the same storage backend every time you run the oc-mirror plugin for the same mirror registry.

Prerequisites

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.16
      type: ocp
  operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.16
    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.16
    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.

Next steps

  • Use the oc-mirror plugin to mirror an image set directly to a target mirror registry.
  • Configure CRI-O.
  • Apply the catalog sources to your node.

8.3.1.4. Image set configuration parameters
Copy link

The oc-mirror plugin requires an image set configuration file that defines what images to mirror. The following table lists the available parameters for the ImageSetConfiguration resource.

Expand
Table 8.2. ImageSetConfiguration parameters
ParameterDescriptionValues

apiVersion

The API version for the ImageSetConfiguration content.

String. For example: mirror.openshift.io/v1alpha2.

mirror

The configuration of the image set.

Object

mirror.additionalImages

The additional images configuration of the image set.

Array of objects. For example: 

additionalImages:
  - name: registry.redhat.io/ubi8/ubi:latest

mirror.additionalImages.name

The tag or digest of the image to mirror.

String. For example: registry.redhat.io/ubi8/ubi:latest

mirror.blockedImages

The full tag, digest, or pattern of images to block from mirroring.

Array of strings. For example: docker.io/library/alpine

mirror.operators

The Operators configuration of the image set.

Array of objects. For example: 

operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.16
    packages:
      - name: elasticsearch-operator
        minVersion: '2.4.0'

mirror.operators.catalog

The Operator catalog to include in the image set.

String. For example: registry.redhat.io/redhat/redhat-operator-index:v4.16.

mirror.operators.full

When true, downloads the full catalog, Operator package, or Operator channel.

Boolean. The default value is false.

mirror.operators.packages

The Operator packages configuration.

Array of objects. For example: 

operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.16
    packages:
      - name: elasticsearch-operator
        minVersion: '5.2.3-31'

mirror.operators.packages.name

The Operator package name to include in the image set

String. For example: elasticsearch-operator.

mirror.operators.packages.channels

The Operator package channel configuration.

Object

mirror.operators.packages.channels.name

The Operator channel name, unique within a package, to include in the image set.

String. For example: fast or stable-v4.16.

mirror.operators.packages.channels.maxVersion

The highest version of the Operator mirror across all channels in which it exists. See the following note for further information.

String. For example: 5.2.3-31

mirror.operators.packages.channels.minBundle

The name of the minimum bundle to include, plus all bundles in the update graph to the channel head. Set this field only if the named bundle has no semantic version metadata.

String. For example: bundleName

mirror.operators.packages.channels.minVersion

The lowest version of the Operator to mirror across all channels in which it exists. See the following note for further information.

String. For example: 5.2.3-31

mirror.operators.packages.maxVersion

The highest version of the Operator to mirror across all channels in which it exists. See the following note for further information.

String. For example: 5.2.3-31.

mirror.operators.packages.minVersion

The lowest version of the Operator to mirror across all channels in which it exists. See the following note for further information.

String. For example: 5.2.3-31.

mirror.operators.skipDependencies

If true, dependencies of bundles are not included.

Boolean. The default value is false.

mirror.operators.targetCatalog

An alternative name and optional namespace hierarchy to mirror the referenced catalog as.

String. For example: my-namespace/my-operator-catalog

mirror.operators.targetName

An alternative name to mirror the referenced catalog as.

The targetName parameter is deprecated. Use the targetCatalog parameter instead.

String. For example: my-operator-catalog

mirror.operators.targetTag

An alternative tag to append to the targetName or targetCatalog.

String. For example: v1

storageConfig

The back-end configuration of the image set.

Object

storageConfig.local

The local back-end configuration of the image set.

Object

storageConfig.local.path

The path of the directory to contain the image set metadata.

String. For example: ./path/to/dir/.

storageConfig.registry

The registry back-end configuration of the image set.

Object

storageConfig.registry.imageURL

The back-end registry URI. Can optionally include a namespace reference in the URI.

String. For example: quay.io/myuser/imageset:metadata.

storageConfig.registry.skipTLS

Optionally skip TLS verification of the referenced back-end registry.

Boolean. The default value is false.

Note

Using the minVersion and maxVersion properties to filter for a specific Operator version range can result in a multiple channel heads error. The error message states that there are multiple channel heads. This is because when the filter is applied, the update graph of the Operator is truncated.

Operator Lifecycle Manager requires that every Operator channel contains versions that form an update graph with exactly one end point, that is, the latest version of the Operator. When the filter range is applied, that graph can turn into two or more separate graphs or a graph that has more than one end point.

To avoid this error, do not filter out the latest version of an Operator. If you still run into the error, depending on the Operator, either the maxVersion property must be increased or the minVersion property must be decreased. Because every Operator graph can be different, you might need to adjust these values until the error resolves.

8.3.1.5. Mirroring from mirror to mirror
Copy link

You can use the oc-mirror plugin to mirror an image set directly to a target mirror registry that is accessible during image set creation.

You must specify a storage backend in the image set configuration file. This storage backend can be a local directory or a Docker v2 registry. The oc-mirror plugin stores metadata in this storage backend during image set creation.

Important

Do not delete or modify the metadata that is generated by the oc-mirror plugin. You must use the same storage backend every time you run the oc-mirror plugin for the same mirror registry.

Prerequisites

  • You have access to the internet to get the necessary container images.
  • You have installed the OpenShift CLI (oc).
  • You have installed the oc-mirror CLI plugin.
  • You have created the image set configuration file.

Procedure

  • Run the oc mirror command to mirror the images from the specified image set configuration to a specified registry: 

    $ oc mirror --config=./<imageset-config.yaml> \
    1 
    
  docker://registry.example:5000
    2
    1
    Specify the image set configuration file that you created. For example, imageset-config.yaml.
    2
    Specify the registry to mirror the image set file to. The registry must start with docker://. If you specify a top-level namespace for the mirror registry, you must also use this same namespace on subsequent executions.

Example output

Rendering catalog image "registry.example.com/redhat/redhat-operator-index:v{ocp-version}" with file-based catalog

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.
Important

The ImageContentSourcePolicy YAML file is used as reference content for manual configuration of CRI-O in MicroShift. You cannot apply the resource directly into a MicroShift cluster.

Next steps

  • Convert the ImageContentSourcePolicy YAML content for use in manually configuring CRI-O.
  • If required, mirror the images from mirror to disk for disconnected or offline use.
  • Configure your cluster to use the resources generated by oc-mirror.

Troubleshooting

You must transform the imageContentSourcePolicy.yaml file created with the oc-mirror plugin into a format that is compatible with the CRI-O container runtime configuration used by MicroShift.

Prerequisites

  • The OpenShift CLI (oc) is installed.
  • Operator Lifecycle Manager (OLM) is installed.
  • The oc-mirror oc plugin is installed.
  • The yq binary is installed.
  • ImageContentSourcePolicy and CatalogSource YAML files are available in the oc-mirror-workspace/results-* directory.

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

After you mirror your image set to the mirror registry, you must apply the generated CatalogSource custom resource (CR) into the node.

Operator Lifecycle Manager (OLM) uses the CatalogSource CR to retrieve information about the available Operators in the mirror registry. You must then create and apply a subscription CR to subscribe to your custom catalog.

Prerequisites

  • You mirrored the image set to your registry mirror.
  • You added image reference information to the CRI-O container runtime configuration.

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.16
  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 ./<subscription-cr.yaml>
    1
    1
    Specify the name of your subscription, such as <subscription-cr.yaml>.

    Example output

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

You can use Operators managed by Operator Lifecycle Manager (OLM) for various tasks in disconnected situations by embedding them in a Red Hat Enterprise Linux for Edge (RHEL for Edge) image.

For Operators that are installed on disconnected nodes, Operator Lifecycle Manager (OLM) by default cannot access sources hosted on remote registries because those remote sources require full internet connectivity. Therefore, you must mirror the remote registries to a highly available container registry.

The following steps are required to use OLM-based Operators in disconnected situations:

  • Include OLM in the container image list for your mirror registry.
  • Configure the system to use your mirror registry by updating your CRI-O configuration directly. ImageContentSourcePolicy is not supported in MicroShift.
  • Add a CatalogSource object to the node so that the OLM catalog Operator can use the local catalog on the mirror registry.
  • Ensure that MicroShift is installed to run in a disconnected capacity.
  • Ensure that the network settings are configured to run in disconnected mode.

After enabling OLM in a disconnected node, you can continue to use your internet-connected workstation to keep your local catalog sources updated as newer versions of Operators are released.

8.4.1.1. Performing a dry run
Copy link

You can use oc-mirror to perform a dry run, without actually mirroring any images. This allows you to review the list of images that would be mirrored, as well as any images that would be pruned from the mirror registry. A dry run also allows you to catch any errors with your image set configuration early or use the generated list of images with other tools to carry out the mirroring operation.

Prerequisites

  • You have access to the internet to obtain the necessary container images.
  • You have installed the OpenShift CLI (oc).
  • You have installed the oc-mirror CLI plugin.
  • You have created the image set configuration file.

Procedure

  1. Run the oc mirror command with the --dry-run flag to perform a dry run: 

    $ oc mirror --config=./imageset-config.yaml \
    1 
    
  docker://registry.example:5000            \
    2 
    
  --dry-run
    3
    1
    Pass in the image set configuration file that was created. This procedure assumes that it is named imageset-config.yaml.
    2
    Specify the mirror registry. Nothing is mirrored to this registry as long as you use the --dry-run flag.
    3
    Use the --dry-run flag to generate the dry run artifacts and not an actual image set file.

    Example output

    Checking push permissions for registry.example:5000
Creating directory: oc-mirror-workspace/src/publish
Creating directory: oc-mirror-workspace/src/v2
Creating directory: oc-mirror-workspace/src/charts
Creating directory: oc-mirror-workspace/src/release-signatures
No metadata detected, creating new workspace
wrote mirroring manifests to oc-mirror-workspace/operators.1658342351/manifests-redhat-operator-index

...

info: Planning completed in 31.48s
info: Dry run complete
Writing image mapping to oc-mirror-workspace/mapping.txt

  2. Navigate into the workspace directory that was generated: 

    $ cd oc-mirror-workspace/

  3. Review the mapping.txt file that was generated.

    This file contains a list of all images that would be mirrored.

  4. Review the pruning-plan.json file that was generated.

    This file contains a list of all images that would be pruned from the mirror registry when the image set is published.

    Note

    The pruning-plan.json file is only generated if your oc-mirror command points to your mirror registry and there are images to be pruned.

After performing a dry run with the oc-mirror plugin to review the list of images that you want to mirror, you must get all of the container image references, then format the output for adding to an Image Builder blueprint.

Note

For catalogs made for proprietary Operators, you can format image references for the Image Builder blueprint without using the following procedure.

Prerequisites

  • You have a catalog index for the Operators you want to use.
  • You have installed the jq CLI tool.
  • You are familiar with Image Builder blueprint files.
  • You have an Image Builder blueprint TOML file.

Procedure

  1. Parse the catalog index.json file to get the image references that you need to include in the Image Builder blueprint. You can use either the unfiltered catalog or you can filter out images that cannot be mirrored:

    1. Parse the unfiltered catalog index.json file to get the image references by running the following command: 

      jq -r --slurp '.[] | select(.relatedImages != null) | "[[containers]]\nsource = \"" + .relatedImages[].image + "\"\n"'   ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v4.16/index/index.json

    2. If you want to filter out images that cannot be mirrored, filter and parse the catalog index.json file by running the following command: 

      $ jq -r --slurp '.[] | select(.relatedImages != null) | .relatedImages[] | select(.name |  contains("ppc") or contains("s390x") | not) | "[[containers]]\\nsource = \\"" + .image + "\\"\\n"' ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v4.16/index/index.json
      Note

      This step uses the AMQ Broker Operator as an example. You can add other criteria to the jq command for further filtering as required by your use case.

      Example image-reference output

      [[containers]]
source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0b2126cfb6054fdf428c1f43b69e36e93a09a49ce15350e9273c98cc08c6598b"

[[containers]]
source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f"
...
...

[[containers]]
source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15"

[[containers]]
source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1"
…
EOF

      Important

      For mirrored and disconnected use cases, ensure that all of the sources filtered from your catalog index.json file are digests. If any of the sources use tags instead of digests, the Operator installation fails. Tags require an internet connection.

  2. View the imageset-config.yaml to get the catalog image reference for the CatalogSource custom resource (CR) by running the following command: 

    $ cat imageset-config.yaml

    Example output

    kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v1alpha2
storageConfig:
  registry:
    imageURL: registry.example.com/microshift-mirror
mirror:
  operators:
  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.16
    1 
    
    packages:
    - name: amq-broker-rhel8
      channels:
      - name: 7.11.x

    1
    Use the value in the mirror.catalog catalog image reference for the follwing jq command to get the image digest. In this example, <registry.redhat.io/redhat/redhat-operator-index:v4.16>.

  3. Get the SHA of the catalog index image by running the following command: 

    $ skopeo inspect docker://<registry.redhat.io/redhat/redhat-operator-index:v4.16> | jq `.Digest`
    1
    1
    Use the value in the mirror.catalog catalog image reference for the jq command to get the image digest. In this example, <registry.redhat.io/redhat/redhat-operator-index:v4.16>.

    Example output

    "sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6"

  4. To get ready to add the image references to your Image Builder blueprint file, format the catalog image reference by using the following example: 

    [[containers]]
source = "registry.redhat.io/redhat/redhat-operator-index@sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6"

  5. Add the image references from all the previous steps to the Image Builder blueprint.

    Generated Image Builder blueprint example snippet

    name = "microshift_blueprint"
description = "MicroShift 4.16.1 on x86_64 platform"
version = "0.0.1"
modules = []
groups = []

[[packages]]
    1 
    
name = "microshift"
version = "4.16.1"
...
...

[customizations.services]
    2 
    
enabled = ["microshift"]

[customizations.firewall]
ports = ["22:tcp", "80:tcp", "443:tcp", "5353:udp", "6443:tcp", "30000-32767:tcp", "30000-32767:udp"]
...
...

[[containers]]
    3 
    
source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:f41e79c17e8b41f1b0a5a32c3e2dd7cd15b8274554d3f1ba12b2598a347475f4"

[[containers]]
source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:dbc65f1fba7d92b36cf7514cd130fe83a9bd211005ddb23a8dc479e0eea645fd"
...
...

[[containers]]
    4 
    
source = "registry.redhat.io/redhat/redhat-operator-index@sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6"
...
...

[[containers]]
source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f"
...
...

[[containers]]
source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15"

[[containers]]
source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1"
…
EOF

    1
    References for all non-optional MicroShift RPM packages using the same version compatible with the microshift-release-info RPM.
    2
    References for automatically enabling MicroShift on system startup and applying default networking settings.
    3
    References for all non-optional MicroShift container images necessary for a disconnected deployment.
    4
    References for the catalog index.

After you have created a RHEL for Edge image for a disconnected environment and configured MicroShift networking settings for disconnected use, you can configure the namespace and create catalog and Operator custom resources (CR) for running your Operators.

Prerequisites

  • You have a RHEL for Edge image.
  • Networking is configured for disconnected use.
  • You completed the oc-mirror plugin dry run procedure.

Procedure

  1. Create a CatalogSource custom resource (CR), similar to the following example:

    Example my-catalog-source-cr.yaml file

    apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: cs-redhat-operator-index
  namespace: openshift-marketplace
    1 
    
spec:
  image: registry.example.com/redhat/redhat-operator-index:v4.16
  sourceType: grpc
  displayName:
  publisher:
  updateStrategy:
    registryPoll:
      interval: 60m

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

    The default pod security admission definition for openshift-marketplace is baseline, therefore a catalog source custom resource (CR) created in that namespace does not require a spec.grpcPodConfig.securityContextConfig value to be set. You can set a legacy or restricted value if required for the namespace and Operators you want to use.

  2. Add the SHA of the catalog index commit to the Catalog Source (CR), similar to the following example:

    Example namespace spec.image configuration

    apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: cs-redhat-operator-index
  namespace: openshift-marketplace
spec:
  image: registry.example.com/redhat/redhat-operator-index@sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6
    1 
    
  sourceType: grpc
  displayName:
  publisher:
  updateStrategy:
    registryPoll:
      interval: 60m

    1
    The SHA of the image commit. Use the same SHA you added to the image builder blueprint.
    Important

    You must use the SHA instead of a tag in your catalog CR or the pod fails to start.

  3. Apply the YAML file from the oc-mirror plugin dry run results directory to the node by running the following command: 

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

    Example output

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

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

    $ oc get catalogsource --all-namespaces

  5. 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

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

    Example my-subscription-cr.yaml file

    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

  7. Apply the Subscription CR by running the following command: 

    $ oc apply -f ./<my-subscription-cr.yaml>
    1
    1
    Specify the name of your Subscription CR, such as my-subscription-cr.yaml.

    Example output

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

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top