Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Managing catalogs

Operator Lifecycle Manager (OLM) v1 is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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 OKD that uses the Kubernetes version that removed the API.

If your cluster is using custom catalogs, see Controlling Operator compatibility with OKD 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.

If you try to install an Operator or extension that does not have unique name, the installation might fail or lead to an unpredictable result. This occurs for the following reasons:

  • If mulitple catalogs are installed on a cluster, Operator Lifecycle Manager (OLM) v1 does not include a mechanism to specify a catalog when you install an Operator or extension.

  • OLM v1 requires that all of the Operators and extensions that are available to install on a cluster use a unique name for their bundles and packages.
Additional resources

Red Hat-provided Operator catalogs in OLM v1

Operator Lifecycle Manager (OLM) v1 does not include Red Hat-provided Operator catalogs by default. If you want to add a Red Hat-provided 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 how to create a catalog resources for OLM v1.

  • Currently, Operator Lifecycle Manager (OLM) v1 cannot authenticate private registries, such as the Red Hat-provided Operator catalogs. This is a known issue. As a result, the OLM v1 procedures that rely on having the Red Hat Operators catalog installed do not work. (OCPBUGS-36364)

  • If you want to use a catalog that is hosted on a private registry, such as Red Hat-provided Operator catalogs from registry.redhat.io, you must have a pull secret scoped to the openshift-catalogd namespace.

    For more information, see "Creating a pull secret for catalogs hosted on a secure registry".
Example Red Hat Operators catalog
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: ClusterCatalog
metadata:
  name: redhat-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/redhat-operator-index:v4
      pullSecret: <pull_secret_name>
      pollInterval: <poll_interval_duration> (1)
1 Specify the interval for polling the remote registry for newer image digests. The default value is 24h. Valid units include seconds (s), minutes (m), and hours (h). To disable polling, set a zero value, such as 0s.
Example Certified Operators catalog
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: ClusterCatalog
metadata:
  name: certified-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/certified-operator-index:v4
      pullSecret: <pull_secret_name>
      pollInterval: 24h
Example Community Operators catalog
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: ClusterCatalog
metadata:
  name: community-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/community-operator-index:v4
      pullSecret: <pull_secret_name>
      pollInterval: 24h

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 redhat-operators.yaml.

Creating a pull secret for catalogs hosted on a private registry

If you want to use a catalog that is hosted on a private registry, such as Red Hat-provided Operator catalogs from registry.redhat.io, you must have a pull secret scoped to the openshift-catalogd namespace.

Catalogd cannot read global pull secrets from OKD clusters. Catalogd can read references to secrets only in the namespace where it is deployed.

Currently, Operator Lifecycle Manager (OLM) v1 cannot authenticate private registries, such as the Red Hat-provided Operator catalogs. This is a known issue. As a result, the OLM v1 procedures that rely on having the Red Hat Operators catalog installed do not work. (OCPBUGS-36364)
Prerequisites

  • Login credentials for the secure registry

  • Docker or Podman installed on your workstation

Procedure

  • If you already have a .dockercfg file with login credentials for the secure registry, create a pull secret by running the following command:

    $ oc create secret generic <pull_secret_name> \
    --from-file=.dockercfg=<file_path>/.dockercfg \
    --type=kubernetes.io/dockercfg \
    --namespace=openshift-catalogd
    Example command 
    $ oc create secret generic redhat-cred \
    --from-file=.dockercfg=/home/<username>/.dockercfg \
    --type=kubernetes.io/dockercfg \
    --namespace=openshift-catalogd

  • If you already have a $HOME/.docker/config.json file with login credentials for the secured registry, create a pull secret by running the following command:

    $ oc create secret generic <pull_secret_name> \
    --from-file=.dockerconfigjson=<file_path>/.docker/config.json \
    --type=kubernetes.io/dockerconfigjson \
    --namespace=openshift-catalogd
    Example command 
    $ oc create secret generic redhat-cred \
    --from-file=.dockerconfigjson=/home/<username>/.docker/config.json \
    --type=kubernetes.io/dockerconfigjson \
    --namespace=openshift-catalogd

  • If you do not have a Docker configuration file with login credentials for the secure registry, create a pull secret by running the following command:

    $ oc create secret docker-registry <pull_secret_name> \
    --docker-server=<registry_server> \
    --docker-username=<username> \
    --docker-password=<password> \
    --docker-email=<email> \
    --namespace=openshift-catalogd
    Example command 
    $ oc create secret docker-registry redhat-cred \
    --docker-server=registry.redhat.io \
    --docker-username=username \
    --docker-password=password \
    --docker-email=user@example.com \
    --namespace=openshift-catalogd

Adding a catalog to a cluster

To add a catalog to a cluster, create a catalog custom resource (CR) and apply it to the cluster.

Currently, Operator Lifecycle Manager (OLM) v1 cannot authenticate private registries, such as the Red Hat-provided Operator catalogs. This is a known issue. As a result, the OLM v1 procedures that rely on having the Red Hat Operators catalog installed do not work. (OCPBUGS-36364)
Prerequisites

  • If you want to use a catalog that is hosted on a private registry, such as Red Hat-provided Operator catalogs from registry.redhat.io, you must have a pull secret scoped to the openshift-catalogd namespace.

    Catalogd cannot read global pull secrets from OKD clusters. Catalogd can read references to secrets only in the namespace where it is deployed.

Procedure

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

    Example redhat-operators.yaml
    apiVersion: catalogd.operatorframework.io/v1alpha1
kind: ClusterCatalog
metadata:
  name: redhat-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/redhat-operator-index:v4 (1)
      pullSecret: <pull_secret_name> (2)
      pollInterval: <poll_interval_duration> (3)
    1 Specify the catalog’s image in the spec.source.image field.
    2 If your catalog is hosted on a secure registry, such as registry.redhat.io, you must create a pull secret scoped to the openshift-catalog namespace.
    3 Specify the interval for polling the remote registry for newer image digests. The default value is 24h. Valid units include seconds (s), minutes (m), and hours (h). To disable polling, set a zero value, such as 0s.

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

    $ oc apply -f redhat-operators.yaml
    Example output
    catalog.catalogd.operatorframework.io/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                  AGE
redhat-operators      20s

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

      $ oc describe clustercatalog
      Example output
      Name:         redhat-operators
Namespace:
Labels:       <none>
Annotations:  <none>
API Version:  catalogd.operatorframework.io/v1alpha1
Kind:         ClusterCatalog
Metadata:
  Creation Timestamp:  2024-06-10T17:34:53Z
  Finalizers:
    catalogd.operatorframework.io/delete-server-cache
  Generation:        1
  Resource Version:  46075
  UID:               83c0db3c-a553-41da-b279-9b3cddaa117d
Spec:
  Source:
    Image:
      Pull Secret:  redhat-cred
      Ref:          registry.redhat.io/redhat/redhat-operator-index:v4.17
    Type:           image
Status: (1)
  Conditions:
    Last Transition Time:  2024-06-10T17:35:15Z
    Message:
    Reason:                UnpackSuccessful (2)
    Status:                True
    Type:                  Unpacked
  Content URL:             https://catalogd-catalogserver.openshift-catalogd.svc/catalogs/redhat-operators/all.json
  Observed Generation:     1
  Phase:                   Unpacked (3)
  Resolved Source:
    Image:
      Last Poll Attempt:  2024-06-10T17:35:10Z
      Ref:                registry.redhat.io/redhat/redhat-operator-index:v4.17
      Resolved Ref:       registry.redhat.io/redhat/redhat-operator-index@sha256:f2ccc079b5e490a50db532d1dc38fd659322594dcf3e653d650ead0e862029d9 (4)
    Type:                 image
Events:                   <none>
      1 Describes the status of the catalog.
      2 Displays the reason the catalog is in the current state.
      3 Displays the phase of the installation process.
      4 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
    catalog.catalogd.operatorframework.io "my-catalog" deleted
Verification

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

    $ oc get clustercatalog