Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Managing catalogs

Cluster administrators can add catalogs, or curated collections of Operators and Kubernetes extensions, to their clusters. Operator authors publish their products to these catalogs. When you add a catalog to your cluster, you have access to the versions, patches, and over-the-air updates of the Operators and extensions that are published to the catalog.

You can manage catalogs and extensions declaratively from the CLI by using custom resources (CRs).

File-based catalogs are the latest iteration of the catalog format in Operator Lifecycle Manager (OLM). It is a plain text-based (JSON or YAML) and declarative config evolution of the earlier SQLite database format, and it is fully backwards compatible.

Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. As a result, Operators are unable to use removed APIs starting with the version of OpenShift Container Platform that uses the Kubernetes version that removed the API.

If your cluster is using custom catalogs, see Controlling Operator compatibility with OpenShift Container Platform versions for more details about how Operator authors can update their projects to help avoid workload issues and prevent incompatible upgrades.

About catalogs in OLM v1

You can discover installable content by querying a catalog for Kubernetes extensions, such as Operators and controllers, by using the catalogd component. Catalogd is a Kubernetes extension that unpacks catalog content for on-cluster clients and is part of the Operator Lifecycle Manager (OLM) v1 suite of microservices. Currently, catalogd unpacks catalog content that is packaged and distributed as container images.

Additional resources

Red Hat-provided Operator catalogs in OLM v1

Operator Lifecycle Manager (OLM) v1 includes the following Red Hat-provided Operator catalogs on the cluster by default. If you want to add an additional catalog to your cluster, create a custom resource (CR) for the catalog and apply it to the cluster. The following custom resource (CR) examples show the default catalogs installed on the cluster.

Red Hat Operators catalog
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
  name: openshift-redhat-operators
spec:
  priority: -100
  source:
    image:
      pollIntervalMinutes: <poll_interval_duration> (1)
      ref: registry.redhat.io/redhat/redhat-operator-index:v4.18
    type: Image
1 Specify the interval in minutes for polling the remote registry for newer image digests. To disable polling, do not set the field.
Certified Operators catalog
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
  name: openshift-certified-operators
spec:
priority: -200
  source:
    type: image
    image:
      pollIntervalMinutes: 10
      ref: registry.redhat.io/redhat/certified-operator-index:v4.18
    type: Image
Red Hat Marketplace catalog
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
  name: openshift-redhat-marketplace
spec:
  priority: -300
  source:
    image:
      pollIntervalMinutes: 10
      ref: registry.redhat.io/redhat/redhat-marketplace-index:v4.18
    type: Image
Community Operators catalog
apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
  name: openshift-community-operators
spec:
  priority: -400
  source:
    image:
      pollIntervalMinutes: 10
      ref: registry.redhat.io/redhat/community-operator-index:v4.18
    type: Image

The following command adds a catalog to your cluster:

Command syntax
$ oc apply -f <catalog_name>.yaml (1)
1 Specifies the catalog CR, such as my-catalog.yaml.

Adding a catalog to a cluster

To add a catalog to a cluster for Operator Lifecycle Manager (OLM) v1 usage, create a ClusterCatalog custom resource (CR) and apply it to the cluster.

Procedure

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

    Example my-redhat-operators.yaml file
    apiVersion: olm.operatorframework.io/v1
kind: ClusterCatalog
metadata:
  name: my-redhat-operators (1)
spec:
  priority: 1000 (2)
  source:
    image:
      pollIntervalMinutes: 10 (3)
      ref: registry.redhat.io/redhat/community-operator-index:v4.18 (4)
    type: Image
    1 The catalog is automatically labeled with the value of the metadata.name field when it is applied to the cluster. For more information about labels and catalog selection, see "Catalog content resolution".
    2 Optional: Specify the priority of the catalog in relation to the other catalogs on the cluster. For more information, see "Catalog selection by priority".
    3 Specify the interval in minutes for polling the remote registry for newer image digests. To disable polling, do not set the field.
    4 Specify the catalog image in the spec.source.image.ref field.

  2. Add the catalog to your cluster by running the following command:

    $ oc apply -f my-redhat-operators.yaml
    Example output
    clustercatalog.olm.operatorframework.io/my-redhat-operators created
Verification

  • Run the following commands to verify the status of your catalog:

    1. Check if you catalog is available by running the following command:

      $ oc get clustercatalog
      Example output
      NAME                            LASTUNPACKED   SERVING   AGE
my-redhat-operators             55s            True      64s
openshift-certified-operators   83m            True      84m
openshift-community-operators   43m            True      84m
openshift-redhat-marketplace    83m            True      84m
openshift-redhat-operators      54m            True      84m

    2. Check the status of your catalog by running the following command:

      $ oc describe clustercatalog my-redhat-operators
      Example output
      Name:         my-redhat-operators
Namespace:
Labels:       olm.operatorframework.io/metadata.name=my-redhat-operators
Annotations:  <none>
API Version:  olm.operatorframework.io/v1
Kind:         ClusterCatalog
Metadata:
  Creation Timestamp:  2025-02-18T20:28:50Z
  Finalizers:
    olm.operatorframework.io/delete-server-cache
  Generation:        1
  Resource Version:  50248
  UID:               86adf94f-d2a8-4e70-895b-31139f2eeab7
Spec:
  Availability Mode:  Available
  Priority:           1000
  Source:
    Image:
      Poll Interval Minutes:  10
      Ref:                    registry.redhat.io/redhat/community-operator-index:v4.18
    Type:                     Image
Status: (1)
  Conditions:
    Last Transition Time:  2025-02-18T20:29:00Z
    Message:               Successfully unpacked and stored content from resolved source
    Observed Generation:   1
    Reason:                Succeeded (2)
    Status:                True
    Type:                  Progressing
    Last Transition Time:  2025-02-18T20:29:00Z
    Message:               Serving desired content from resolved source
    Observed Generation:   1
    Reason:                Available
    Status:                True
    Type:                  Serving
  Last Unpacked:           2025-02-18T20:28:59Z
  Resolved Source:
    Image:
      Ref:  registry.redhat.io/redhat/community-operator-index@sha256:11627ea6fdd06b8092df815076e03cae9b7cede8b353c0b461328842d02896c5 (3)
    Type:   Image
  Urls:
    Base:  https://catalogd-service.openshift-catalogd.svc/catalogs/my-redhat-operators
Events:    <none>
      1 Describes the status of the catalog.
      2 Displays the reason the catalog is in the current state.
      3 Displays the image reference of the catalog.

Deleting a catalog

You can delete a catalog by deleting its custom resource (CR).

Prerequisites

  • You have a catalog installed.

Procedure

  • Delete a catalog by running the following command:

    $ oc delete clustercatalog <catalog_name>
    Example output
    clustercatalog.olm.operatorframework.io "my-redhat-operators" deleted
Verification

  • Verify the catalog is deleted by running the following command:

    $ oc get clustercatalog

Disabling a default catalog

You can disable the Red Hat-provided catalogs that are included with OpenShift Container Platform by default.

Procedure

  • Disable a default catalog by running the following command:

    $ oc patch clustercatalog openshift-certified-operators -p \
  '{"spec": {"availabilityMode": "Unavailable"}}' --type=merge
    Example output
    clustercatalog.olm.operatorframework.io/openshift-certified-operators patched
Verification

  • Verify the catalog is disabled by running the following command:

    $ oc get clustercatalog openshift-certified-operators
    Example output
    NAME                            LASTUNPACKED   SERVING   AGE
openshift-certified-operators                  False     6h54m