Search

Chapter 7. OLM 1.0 (Technology Preview)

download PDF

7.1. About Operator Lifecycle Manager 1.0 (Technology Preview)

Operator Lifecycle Manager (OLM) has been included with OpenShift Container Platform 4 since its initial release. OpenShift Container Platform 4.16 includes components for a next-generation iteration of OLM as a Technology Preview feature, known during this phase as OLM 1.0. This updated framework evolves many of the concepts that have been part of previous versions of OLM and adds new capabilities.

Important

OLM 1.0 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.

7.1.1. Highlights

During this Technology Preview phase of OLM 1.0 in OpenShift Container Platform 4.16, administrators can explore the following highlights:

Fully declarative model that supports GitOps workflows

OLM 1.0 simplifies extension management through two key APIs:

  • A new ClusterExtension API streamlines management of installed extensions, which includes Operators via the registry+v1 bundle format, by consolidating user-facing APIs into a single object. This API, provided as clusterextension.olm.operatorframework.io by the new Operator Controller component, empowers administrators and SREs to automate processes and define desired states by using GitOps principles.

    Note

    Earlier Technology Preview phases of OLM 1.0 introduced a new Operator API; this API is renamed ClusterExtension in OpenShift Container Platform 4.16 to address the following:

    • More accurately reflects the simplified functionality of extending a cluster’s capabilities
    • Better represents a more flexible packaging format
    • Cluster prefix clearly indicates that ClusterExtension objects are cluster-scoped, a change from legacy OLM where Operators could be either namespace-scoped or cluster-scoped
  • The Catalog API, provided by the new catalogd component, serves as the foundation for OLM 1.0, unpacking catalogs for on-cluster clients so that users can discover installable content, such as Kubernetes extensions and Operators. This provides increased visibility into all available Operator bundle versions, including their details, channels, and update edges.

For more information, see Operator Controller and Catalogd.

Improved control over extension updates
With improved insight into catalog content, administrators can specify target versions for installation and updates. This grants administrators more control over the target version of extension updates. For more information, see Updating an cluster extension.
Flexible extension packaging format

Administrators can use file-based catalogs to install and manage extensions, such as OLM-based Operators, similar to the legacy OLM experience.

In addition, bundle size is no longer constrained by the etcd value size limit. For more information, see Installing an Operator from a catalog.

7.1.2. Purpose

The mission of Operator Lifecycle Manager (OLM) has been to manage the lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose has always been to make installing, running, and updating functional extensions to the cluster easy, safe, and reproducible for cluster and platform-as-a-service (PaaS) administrators throughout the lifecycle of the underlying cluster.

The initial version of OLM, which launched with OpenShift Container Platform 4 and is included by default, focused on providing unique support for these specific needs for a particular type of cluster extension, known as Operators. Operators are classified as one or more Kubernetes controllers, shipping with one or more API extensions, as CustomResourceDefinition (CRD) objects, to provide additional functionality to the cluster.

After running in production clusters for many releases, the next-generation of OLM aims to encompass lifecycles for cluster extensions that are not just Operators.

7.2. Components and architecture

7.2.1. OLM 1.0 components overview (Technology Preview)

Important

OLM 1.0 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.

Operator Lifecycle Manager (OLM) 1.0 comprises the following component projects:

Operator Controller
Operator Controller is the central component of OLM 1.0 that extends Kubernetes with an API through which users can install and manage the lifecycle of Operators and extensions. It consumes information from catalogd.
RukPak
RukPak is a pluggable solution for packaging and distributing cloud-native content. It supports advanced strategies for installation, updates, and policy.
Catalogd
Catalogd is a Kubernetes extension that unpacks file-based catalog (FBC) content packaged and shipped in container images for consumption by on-cluster clients. As a component of the OLM 1.0 microservices architecture, catalogd hosts metadata for Kubernetes extensions packaged by the authors of the extensions, and as a result helps users discover installable content.

7.2.2. Operator Controller (Technology Preview)

Operator Controller is the central component of Operator Lifecycle Manager (OLM) 1.0 and consumes the other OLM 1.0 component, catalogd. It extends Kubernetes with an API through which users can install Operators and extensions.

Important

OLM 1.0 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.

7.2.2.1. ClusterExtension API

Operator Controller provides a new ClusterExtension API object that is a single resource representing an instance of an installed extension, which includes Operators via the registry+v1 bundle format. This clusterextension.olm.operatorframework.io API streamlines management of installed extensions by consolidating user-facing APIs into a single object.

Important

In OLM 1.0, ClusterExtension objects are cluster-scoped. This differs from legacy OLM where Operators could be either namespace-scoped or cluster-scoped, depending on the configuration of their related Subscription and OperatorGroup objects.

For more information about the earlier behavior, see Multitenancy and Operator colocation.

Example ClusterExtension object

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: <operator_name>
spec:
  packageName: <package_name>
  installNamespace: <namespace_name>
  channel: <channel_name>
  version: <version_number>

7.2.2.1.1. Example custom resources (CRs) that specify a target version

In Operator Lifecycle Manager (OLM) 1.0, cluster administrators can declaratively set the target version of an Operator or extension in the custom resource (CR).

You can define a target version by specifying any of the following fields:

  • Channel
  • Version number
  • Version range

If you specify a channel in the CR, OLM 1.0 installs the latest version of the Operator or extension that can be resolved within the specified channel. When updates are published to the specified channel, OLM 1.0 automatically updates to the latest release that can be resolved from the channel.

Example CR with a specified channel

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  channel: latest 1

1
Installs the latest release that can be resolved from the specified channel. Updates to the channel are automatically installed.

If you specify the Operator or extension’s target version in the CR, OLM 1.0 installs the specified version. When the target version is specified in the CR, OLM 1.0 does not change the target version when updates are published to the catalog.

If you want to update the version of the Operator that is installed on the cluster, you must manually edit the Operator’s CR. Specifying an Operator’s target version pins the Operator’s version to the specified release.

Example CR with the target version specified

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: "1.11.1" 1

1
Specifies the target version. If you want to update the version of the Operator or extension that is installed, you must manually update this field the CR to the desired target version.

If you want to define a range of acceptable versions for an Operator or extension, you can specify a version range by using a comparison string. When you specify a version range, OLM 1.0 installs the latest version of an Operator or extension that can be resolved by the Operator Controller.

Example CR with a version range specified

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: ">1.11.1" 1

1
Specifies that the desired version range is greater than version 1.11.1. For more information, see "Support for version ranges".

After you create or update a CR, apply the configuration file by running the following command:

Command syntax

$ oc apply -f <extension_name>.yaml

7.2.3. Rukpak (Technology Preview)

Operator Lifecycle Manager (OLM) 1.0 uses the RukPak component and its resources to manage cloud-native content.

Important

OLM 1.0 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.

7.2.3.1. About RukPak

RukPak is a pluggable solution for packaging and distributing cloud-native content. It supports advanced strategies for installation, updates, and policy.

RukPak provides a content ecosystem for installing artifacts on a Kubernetes cluster. In OpenShift Container Platform 4.16, RukPak supports legacy Operator Lifecycle Manager (OLM) bundles as artifacts. RukPak can then manage, scale, and upgrade these artifacts in a safe way to enable powerful cluster extensions.

Warning

RukPak, a Technology Preview component, does not support FIPS. In OpenShift Container Platform 4.16, Operator Lifecycle Manager (OLM) 1.0 depends on RukPak. As a result, RukPak and OLM 1.0 do not run on clusters with FIPS mode enabled.

At its core, RukPak is a set of controllers and the BundleDeployment API. The API is packaged as a custom resource definition (CRD) that expresses what content to install on a cluster and how to create a running deployment of the content. The controllers watch for the API.

Common terminology

Bundle
A collection of Kubernetes manifests that define content to be deployed to a cluster
Bundle image
A container image that contains a bundle within its filesystem
Bundle Git repository
A Git repository that contains a bundle within a directory
Provisioner
Controllers that install and manage content on a Kubernetes cluster
Bundle deployment
Generates deployed instances of a bundle

7.2.3.2. About provisioners

RukPak consists of a series of controllers, known as provisioners, that install and manage content on a Kubernetes cluster. A provisioner works together with a BundleDeployment object to bring content onto the cluster and install it, generating resources within the cluster.

Currently, the registry provisioner is implemented and included with RukPak. A registry bundle, or registry+v1 bundle, contains a set of static Kubernetes YAML manifests organized in the legacy Operator Lifecycle Manager (OLM) bundle format. The registry provisioner sources and unpacks registry bundles.

A provisioner is assigned a unique ID and is responsible for reconciling bundles and BundleDeployment objects with a spec.provisionerClassName field that matches that particular ID. For example, the registry provisioner is able to unpack a given registry+v1 bundle onto a cluster and then instantiate it, making the content of the bundle available in the cluster.

A provisioner places a watch on BundleDeployment resources that refer to the provisioner explicitly. For a given bundle, the provisioner unpacks the contents of the bundle onto the cluster. Then, given a BundleDeployment resource referring to that bundle, the provisioner installs the bundle contents and is responsible for managing the lifecycle of those resources.

Additional resources

7.2.3.3. BundleDeployment

In OpenShift Container Platform 4.16, the RukPak BundleDeployment indicates when a bundle should be active. This includes pivoting from older versions of an active bundle.

Warning

A BundleDeployment object changes the state of a Kubernetes cluster by installing and removing objects. It is important to verify and trust the content that is being installed and limit access, by using RBAC, to the BundleDeployment API to only those who require those permissions.

Much like pods generate instances of container images, a bundle deployment generates a deployed version of a bundle. A bundle deployment can be seen as a generalization of the pod concept.

The specifics of how a bundle deployment makes changes to a cluster based on a referenced bundle is defined by the provisioner that is configured to watch that bundle deployment.

7.2.4. Catalogd (Technology Preview)

Operator Lifecycle Manager (OLM) 1.0 uses the catalogd component and its resources to manage Operator and extension catalogs.

Important

OLM 1.0 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.

7.2.4.1. About catalogs in OLM 1.0

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) 1.0 suite of microservices. Currently, catalogd unpacks catalog content that is packaged and distributed as container images.

Important

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) 1.0 does not include a mechanism to specify a catalog when you install an Operator or extension.
  • OLM 1.0 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

7.2.4.1.1. Red Hat-provided Operator catalogs in OLM 1.0

Operator Lifecycle Manager (OLM) 1.0 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 1.0.

Important

If you want to use a catalog that is hosted on a secure 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: Catalog
metadata:
  name: redhat-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/redhat-operator-index:v4.16
      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: Catalog
metadata:
  name: certified-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/certified-operator-index:v4.16
      pullSecret: <pull_secret_name>
      pollInterval: 24h

Example Community Operators catalog

apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Catalog
metadata:
  name: community-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/community-operator-index:v4.16
      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.

7.3. Installing an Operator from a catalog in OLM 1.0 (Technology Preview)

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.

In the current Technology Preview release of Operator Lifecycle Manager (OLM) 1.0, you manage catalogs and Operators declaratively from the CLI using custom resources (CRs).

Important

OLM 1.0 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.

7.3.1. Prerequisites

  • Access to an OpenShift Container Platform cluster using an account with cluster-admin permissions

    Note

    For OpenShift Container Platform 4.16, documented procedures for OLM 1.0 are CLI-based only. Alternatively, administrators can create and view related objects in the web console by using normal methods, such as the Import YAML and Search pages. However, the existing OperatorHub and Installed Operators pages do not yet display OLM 1.0 components.

  • The TechPreviewNoUpgrade feature set enabled on the cluster

    Warning

    Enabling the TechPreviewNoUpgrade feature set cannot be undone and prevents minor version updates. These feature sets are not recommended on production clusters.

  • The OpenShift CLI (oc) installed on your workstation

7.3.2. About catalogs in OLM 1.0

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) 1.0 suite of microservices. Currently, catalogd unpacks catalog content that is packaged and distributed as container images.

Important

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) 1.0 does not include a mechanism to specify a catalog when you install an Operator or extension.
  • OLM 1.0 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

7.3.3. Red Hat-provided Operator catalogs in OLM 1.0

Operator Lifecycle Manager (OLM) 1.0 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 1.0.

Important

If you want to use a catalog that is hosted on a secure 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: Catalog
metadata:
  name: redhat-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/redhat-operator-index:v4.16
      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: Catalog
metadata:
  name: certified-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/certified-operator-index:v4.16
      pullSecret: <pull_secret_name>
      pollInterval: 24h

Example Community Operators catalog

apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Catalog
metadata:
  name: community-operators
spec:
  source:
    type: image
    image:
      ref: registry.redhat.io/redhat/community-operator-index:v4.16
      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.

7.3.4. Creating a pull secret for catalogs hosted on a secure registry

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

Note

Currently, catalogd cannot read global pull secrets from OpenShift Container Platform clusters. Catalogd can read references to secrets only in the namespace where it is deployed.

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 7.1. 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 7.2. 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 7.3. 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

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

Prerequisites

  • If you want to use a catalog that is hosted on a secure 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".

Procedure

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

    Example redhat-operators.yaml

    apiVersion: catalogd.operatorframework.io/v1alpha1
    kind: Catalog
    metadata:
      name: redhat-operators
    spec:
      source:
        type: image
        image:
          ref: registry.redhat.io/redhat/redhat-operator-index:v4.16 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 catalog

      Example output

      NAME                  AGE
      redhat-operators      20s

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

      $ oc describe catalog

      Example output

      Name:         redhat-operators
      Namespace:
      Labels:       <none>
      Annotations:  <none>
      API Version:  catalogd.operatorframework.io/v1alpha1
      Kind:         Catalog
      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.16
          Type:           image
      Status: 1
        Conditions:
          Last Transition Time:  2024-06-10T17:35:15Z
          Message:
          Reason:                UnpackSuccessful 2
          Status:                True
          Type:                  Unpacked
        Content URL:             http://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.16
            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.

7.3.6. Finding Operators to install from a catalog

After you add a catalog to your cluster, you can query the catalog to find Operators and extensions to install. Before you can query catalogs, you must port forward the catalog server service.

Prerequisite

  • You have added a catalog to your cluster.
  • You have installed the jq CLI tool.

Procedure

  1. Port forward the catalog server service in the openshift-catalogd namespace by running the following command:

    $ oc -n openshift-catalogd port-forward svc/catalogd-catalogserver 8080:80
  2. Download the catalog’s JSON file locally by running the following command:

    $ curl -L http://localhost:8080/catalogs/<catalog_name>/all.json \
      -C - -o /<path>/<catalog_name>.json

    Example 7.4. Example command

    $ curl -L http://localhost:8080/catalogs/redhat-operators/all.json \
      -C - -o /home/username/catalogs/rhoc.json
  3. Run one of the following commands to return a list of Operators and extensions in a catalog.

    include:snippets/olmv1-tp-extension-support.adoc[]

    • Get a list of all the Operators and extensions from the local catalog file by running the following command:

      $ jq -s '.[] | select(.schema == "olm.package") | .name' \
        /<path>/<filename>.json

      Example 7.5. Example command

      $ jq -s '.[] | select(.schema == "olm.package") | .name' \
        /home/username/catalogs/rhoc.json

      Example 7.6. Example output

      NAME                                                        AGE
      "3scale-operator"
      "advanced-cluster-management"
      "amq-broker-rhel8"
      "amq-online"
      "amq-streams"
      "amq7-interconnect-operator"
      "ansible-automation-platform-operator"
      "ansible-cloud-addons-operator"
      "apicast-operator"
      "aws-efs-csi-driver-operator"
      "aws-load-balancer-operator"
      "bamoe-businessautomation-operator"
      "bamoe-kogito-operator"
      "bare-metal-event-relay"
      "businessautomation-operator"
      ...
    • Get list of packages that support AllNamespaces install mode and do not use webhooks from the local catalog file by running the following command:

      $ jq -c 'select(.schema == "olm.bundle") | \
        {"package":.package, "version":.properties[] | \
        select(.type == "olm.bundle.object").value.data | @base64d | fromjson | \
        select(.kind == "ClusterServiceVersion" and (.spec.installModes[] | \
        select(.type == "AllNamespaces" and .supported == true) != null) \
        and .spec.webhookdefinitions == null).spec.version}' \
        /<path>/<catalog_name>.json

      Example 7.7. Example output

      {"package":"3scale-operator","version":"0.10.0-mas"}
      {"package":"3scale-operator","version":"0.10.5"}
      {"package":"3scale-operator","version":"0.11.0-mas"}
      {"package":"3scale-operator","version":"0.11.1-mas"}
      {"package":"3scale-operator","version":"0.11.2-mas"}
      {"package":"3scale-operator","version":"0.11.3-mas"}
      {"package":"3scale-operator","version":"0.11.5-mas"}
      {"package":"3scale-operator","version":"0.11.6-mas"}
      {"package":"3scale-operator","version":"0.11.7-mas"}
      {"package":"3scale-operator","version":"0.11.8-mas"}
      {"package":"amq-broker-rhel8","version":"7.10.0-opr-1"}
      {"package":"amq-broker-rhel8","version":"7.10.0-opr-2"}
      {"package":"amq-broker-rhel8","version":"7.10.0-opr-3"}
      {"package":"amq-broker-rhel8","version":"7.10.0-opr-4"}
      {"package":"amq-broker-rhel8","version":"7.10.1-opr-1"}
      {"package":"amq-broker-rhel8","version":"7.10.1-opr-2"}
      {"package":"amq-broker-rhel8","version":"7.10.2-opr-1"}
      {"package":"amq-broker-rhel8","version":"7.10.2-opr-2"}
      ...
  4. Inspect the contents of an Operator or extension’s metadata by running the following command:

    $ jq -s '.[] | select( .schema == "olm.package") | \
      select( .name == "<package_name>")' /<path>/<catalog_name>.json

    Example 7.8. Example command

    $ jq -s '.[] | select( .schema == "olm.package") | \
      select( .name == "openshift-pipelines-operator-rh")' \
      /home/username/rhoc.json

    Example 7.9. Example output

    {
      "defaultChannel": "stable",
      "icon": {
        "base64data": "PHN2ZyB4bWxu..."
        "mediatype": "image/png"
      },
      "name": "openshift-pipelines-operator-rh",
      "schema": "olm.package"
    }

7.3.6.1. Common catalog queries

You can query catalogs by using the jq CLI tool.

Table 7.1. Common package queries
QueryRequest

Available packages in a catalog

$ jq -s '.[] | select( .schema == "olm.package") | \
  .name' <catalog_name>.json

Packages that support AllNamespaces install mode and do not use webhooks

$ jq -c 'select(.schema == "olm.bundle") | \
  {"package":.package, "version":.properties[] | \
  select(.type == "olm.bundle.object").value.data | \
  @base64d | fromjson | \
  select(.kind == "ClusterServiceVersion" and (.spec.installModes[] | \
  select(.type == "AllNamespaces" and .supported == true) != null) \
  and .spec.webhookdefinitions == null).spec.version}' \
  <catalog_name>.json

Package metadata

$ jq -s '.[] | select( .schema == "olm.package") | \
  select( .name == "<package_name>")' <catalog_name>.json

Catalog blobs in a package

$ jq -s '.[] | select( .package == "<package_name>")' \
  <catalog_name>.json
Table 7.2. Common channel queries
QueryRequest

Channels in a package

$ jq -s '.[] | select( .schema == "olm.channel" ) | \
  select( .package == "<package_name>") | .name' \
  <catalog_name>.json

Versions in a channel

$ jq -s '.[] | select( .package == "<package_name>" ) | \
  select( .schema == "olm.channel" ) | \
  select( .name == "<channel_name>" ) | \
  .entries | .[] | .name' <catalog_name>.json
  • Latest version in a channel
  • Upgrade path
$ jq -s '.[] | select( .schema == "olm.channel" ) | \
  select ( .name == "<channel>") | \
  select( .package == "<package_name>")' \
  <catalog_name>.json
Table 7.3. Common bundle queries
QueryRequest

Bundles in a package

$ jq -s '.[] | select( .schema == "olm.bundle" ) | \
  select( .package == "<package_name>") | .name' \
  <catalog_name>.json
  • Bundle dependencies
  • Available APIs
$ jq -s '.[] | select( .schema == "olm.bundle" ) | \
  select ( .name == "<bundle_name>") | \
  select( .package == "<package_name>")' \
  <catalog_name>.json

7.3.7. Installing a cluster extension from a catalog

Operator Lifecycle Manager (OLM) 1.0 supports installing cluster extensions, including legacy OLM Operators via the registry+v1 bundle format, that are scoped to the cluster. You can install an extension from a catalog by creating a custom resource (CR) and applying it to the cluster.

Important

OLM 1.0 does not support dependency resolution. If an extension declares dependencies for other APIs or packages, the dependencies must be present on the cluster before you attempt to install the extension.

Currently, OLM 1.0 supports the installation of extensions that meet the following criteria:

  • The extension must use the AllNamespaces install mode.
  • The extension must not use webhooks.

Cluster extensions that use webhooks or that target a single or specified set of namespaces cannot be installed.

Prerequisite

  • You have added a catalog to your cluster.
  • You have downloaded a local copy of the catalog file.
  • You have installed the jq CLI tool.

Procedure

  1. Inspect a package for channel and version information from a local copy of your catalog file by completing the following steps:

    1. Get a list of channels from a selected package by running the following command:

      $ jq -s '.[] | select( .schema == "olm.channel" ) | \
        select( .package == "<package_name>") | \
        .name' /<path>/<catalog_name>.json

      Example 7.10. Example command

      $ jq -s '.[] | select( .schema == "olm.channel" ) | \
        select( .package == "openshift-pipelines-operator-rh") | \
        .name' /home/username/rhoc.json

      Example 7.11. Example output

      "latest"
      "pipelines-1.11"
      "pipelines-1.12"
      "pipelines-1.13"
      "pipelines-1.14"
    2. Get a list of the versions published in a channel by running the following command:

      $ jq -s '.[] | select( .package == "<package_name>" ) | \
        select( .schema == "olm.channel" ) | \
        select( .name == "<channel_name>" ) | .entries | \
        .[] | .name' /<path>/<catalog_name>.json

      Example 7.12. Example command

      $ jq -s '.[] | select( .package == "openshift-pipelines-operator-rh" ) | \
      select( .schema == "olm.channel" ) | select( .name == "latest" ) | \
      .entries | .[] | .name' /home/username/rhoc.json

      Example 7.13. Example output

      "openshift-pipelines-operator-rh.v1.12.0"
      "openshift-pipelines-operator-rh.v1.12.1"
      "openshift-pipelines-operator-rh.v1.12.2"
      "openshift-pipelines-operator-rh.v1.13.0"
      "openshift-pipelines-operator-rh.v1.13.1"
      "openshift-pipelines-operator-rh.v1.11.1"
      "openshift-pipelines-operator-rh.v1.12.0"
      "openshift-pipelines-operator-rh.v1.12.1"
      "openshift-pipelines-operator-rh.v1.12.2"
      "openshift-pipelines-operator-rh.v1.13.0"
      "openshift-pipelines-operator-rh.v1.14.1"
      "openshift-pipelines-operator-rh.v1.14.2"
      "openshift-pipelines-operator-rh.v1.14.3"
      "openshift-pipelines-operator-rh.v1.14.4"
  2. If you want to install your extension into a new namespace, run the following command:

    $ oc adm new-project <new_namespace>
  3. Create a CR, similar to the following example:

    Example pipelines-operator.yaml CR

    apiVersion: olm.operatorframework.io/v1alpha1
    kind: ClusterExtension
    metadata:
      name: pipelines-operator
    spec:
      packageName: openshift-pipelines-operator-rh
      installNamespace: <namespace>
      channel: <channel>
      version: "<version>"

    where:

    <namespace>
    Specifies the namespace where you want the bundle installed, such as openshift-operators or my-extension. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces.
    <channel>
    Optional: Specifies the channel, such as pipelines-1.11 or latest, for the package you want to install or update.
    <version>

    Optional: Specifies the version or version range, such as 1.11.1, 1.12.x, or >=1.12.1, of the package you want to install or update. For more information, see "Example custom resources (CRs) that specify a target version" and "Support for version ranges".

    Important

    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) 1.0 does not include a mechanism to specify a catalog when you install an Operator or extension.
    • OLM 1.0 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.
  4. Apply the CR to the cluster by running the following command:

    $ oc apply -f pipeline-operator.yaml

    Example output

    clusterextension.olm.operatorframework.io/pipelines-operator created

Verification

  1. View the Operator or extension’s CR in the YAML format by running the following command:

    $ oc get clusterextension pipelines-operator -o yaml

    Example 7.14. Example output

    apiVersion: v1
    items:
    - apiVersion: olm.operatorframework.io/v1alpha1
      kind: ClusterExtension
      metadata:
        annotations:
          kubectl.kubernetes.io/last-applied-configuration: |
            {"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","installNamespace":"openshift-operators","packageName":"openshift-pipelines-operator-rh","pollInterval":"30m"}}
        creationTimestamp: "2024-06-10T17:50:51Z"
        generation: 1
        name: pipelines-operator
        resourceVersion: "53324"
        uid: c54237be-cde4-46d4-9b31-d0ec6acc19bf
      spec:
        channel: latest
        installNamespace: openshift-operators
        packageName: openshift-pipelines-operator-rh
        upgradeConstraintPolicy: Enforce
      status:
        conditions:
        - lastTransitionTime: "2024-06-10T17:50:58Z"
          message: resolved to "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:dd3d18367da2be42539e5dde8e484dac3df33ba3ce1d5bcf896838954f3864ec"
          observedGeneration: 1
          reason: Success
          status: "True"
          type: Resolved
        - lastTransitionTime: "2024-06-10T17:51:11Z"
          message: installed from "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:dd3d18367da2be42539e5dde8e484dac3df33ba3ce1d5bcf896838954f3864ec"
          observedGeneration: 1
          reason: Success
          status: "True"
          type: Installed
        - lastTransitionTime: "2024-06-10T17:50:58Z"
          message: ""
          observedGeneration: 1
          reason: Deprecated
          status: "False"
          type: Deprecated
        - lastTransitionTime: "2024-06-10T17:50:58Z"
          message: ""
          observedGeneration: 1
          reason: Deprecated
          status: "False"
          type: PackageDeprecated
        - lastTransitionTime: "2024-06-10T17:50:58Z"
          message: ""
          observedGeneration: 1
          reason: Deprecated
          status: "False"
          type: ChannelDeprecated
        - lastTransitionTime: "2024-06-10T17:50:58Z"
          message: ""
          observedGeneration: 1
          reason: Deprecated
          status: "False"
          type: BundleDeprecated
        installedBundle:
          name: openshift-pipelines-operator-rh.v1.14.4
          version: 1.14.4
        resolvedBundle:
          name: openshift-pipelines-operator-rh.v1.14.4
          version: 1.14.4
    kind: List
    metadata:
      resourceVersion: ""

    where:

    spec.channel
    Displays the channel defined in the CR of the extension.
    spec.version
    Displays the version or version range defined in the CR of the extension.
    status.conditions
    Displays information about the status and health of the extension.
    type: Deprecated

    Displays whether one or more of following are deprecated:

    type: PackageDeprecated
    Displays whether the resolved package is deprecated.
    type: ChannelDeprecated
    Displays whether the resolved channel is deprecated.
    type: BundleDeprecated
    Displays whether the resolved bundle is deprecated.

    The value of False in the status field indicates that the reason: Deprecated condition is not deprecated. The value of True in the status field indicates that the reason: Deprecated condition is deprecated.

    installedBundle.name
    Displays the name of the bundle installed.
    installedBundle.version
    Displays the version of the bundle installed.
    resolvedBundle.name
    Displays the name of the resolved bundle.
    resolvedBundle.version
    Displays the verson of the resolved bundle.
  2. Get information about your bundle deployment by running the following command:

    $ oc get bundleDeployment pipelines-operator -o yaml

    Example 7.15. Example output

    apiVersion: core.rukpak.io/v1alpha2
    kind: BundleDeployment
    metadata:
      creationTimestamp: "2024-06-10T17:50:58Z"
      finalizers:
      - core.rukpak.io/delete-cached-bundle
      generation: 1
      name: pipelines-operator
      ownerReferences:
      - apiVersion: olm.operatorframework.io/v1alpha1
        blockOwnerDeletion: true
        controller: true
        kind: ClusterExtension
        name: pipelines-operator
        uid: c54237be-cde4-46d4-9b31-d0ec6acc19bf
      resourceVersion: "53414"
      uid: 74367cfc-578e-4da0-815f-fe40f3ca5d1c
    spec:
      installNamespace: openshift-operators
      provisionerClassName: core-rukpak-io-registry
      source:
        image:
          ref: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:dd3d18367da2be42539e5dde8e484dac3df33ba3ce1d5bcf896838954f3864ec
        type: image
    status:
      conditions:
      - lastTransitionTime: "2024-06-10T17:51:09Z"
        message: Successfully unpacked the image Bundle
        reason: UnpackSuccessful
        status: "True"
        type: Unpacked
      - lastTransitionTime: "2024-06-10T17:51:10Z"
        message: Instantiated bundle pipelines-operator successfully
        reason: InstallationSucceeded
        status: "True"
        type: Installed
      - lastTransitionTime: "2024-06-10T17:51:19Z"
        message: BundleDeployment is healthy
        reason: Healthy
        status: "True"
        type: Healthy
      contentURL: https://core.openshift-rukpak.svc/bundles/pipelines-operator.tgz
      observedGeneration: 1
      resolvedSource:
        image:
          ref: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:dd3d18367da2be42539e5dde8e484dac3df33ba3ce1d5bcf896838954f3864ec
        type: image

7.3.8. Updating a cluster extension

You can update your cluster extension or Operator by manually editing the custom resource (CR) and applying the changes.

Prerequisites

  • You have a catalog installed.
  • You have downloaded a local copy of the catalog file.
  • You have an Operator or extension installed.
  • You have installed the jq CLI tool.

Procedure

  1. Inspect a package for channel and version information from a local copy of your catalog file by completing the following steps:

    1. Get a list of channels from a selected package by running the following command:

      $ jq -s '.[] | select( .schema == "olm.channel" ) | \
        select( .package == "<package_name>") | \
        .name' /<path>/<catalog_name>.json

      Example 7.16. Example command

      $ jq -s '.[] | select( .schema == "olm.channel" ) | \
        select( .package == "openshift-pipelines-operator-rh") | \
        .name' /home/username/rhoc.json

      Example 7.17. Example output

      "latest"
      "pipelines-1.11"
      "pipelines-1.12"
      "pipelines-1.13"
      "pipelines-1.14"
    2. Get a list of the versions published in a channel by running the following command:

      $ jq -s '.[] | select( .package == "<package_name>" ) | \
        select( .schema == "olm.channel" ) | \
        select( .name == "<channel_name>" ) | .entries | \
        .[] | .name' /<path>/<catalog_name>.json

      Example 7.18. Example command

      $ jq -s '.[] | select( .package == "openshift-pipelines-operator-rh" ) | \
      select( .schema == "olm.channel" ) | select( .name == "latest" ) | \
      .entries | .[] | .name' /home/username/rhoc.json

      Example 7.19. Example output

      "openshift-pipelines-operator-rh.v1.11.1"
      "openshift-pipelines-operator-rh.v1.12.0"
      "openshift-pipelines-operator-rh.v1.12.1"
      "openshift-pipelines-operator-rh.v1.12.2"
      "openshift-pipelines-operator-rh.v1.13.0"
      "openshift-pipelines-operator-rh.v1.14.1"
      "openshift-pipelines-operator-rh.v1.14.2"
      "openshift-pipelines-operator-rh.v1.14.3"
      "openshift-pipelines-operator-rh.v1.14.4"
  2. Find out what version or channel is specified in your Operator or extension’s CR by running the following command:

    $ oc get clusterextension <operator_name> -o yaml

    Example command

    $ oc get clusterextension pipelines-operator -o yaml

    Example 7.20. Example output

    apiVersion: olm.operatorframework.io/v1alpha1
    kind: ClusterExtension
    metadata:
      annotations:
        kubectl.kubernetes.io/last-applied-configuration: |
          {"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","installNamespace":"openshift-operators","packageName":"openshift-pipelines-operator-rh","pollInterval":"30m","version":"\u003c1.12"}}
      creationTimestamp: "2024-06-11T15:55:37Z"
      generation: 1
      name: pipelines-operator
      resourceVersion: "69776"
      uid: 6a11dff3-bfa3-42b8-9e5f-d8babbd6486f
    spec:
      channel: latest
      installNamespace: openshift-operators
      packageName: openshift-pipelines-operator-rh
      upgradeConstraintPolicy: Enforce
      version: <1.12
    status:
      conditions:
      - lastTransitionTime: "2024-06-11T15:56:09Z"
        message: installed from "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280"
        observedGeneration: 1
        reason: Success
        status: "True"
        type: Installed
      - lastTransitionTime: "2024-06-11T15:55:50Z"
        message: resolved to "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280"
        observedGeneration: 1
        reason: Success
        status: "True"
        type: Resolved
      - lastTransitionTime: "2024-06-11T15:55:50Z"
        message: ""
        observedGeneration: 1
        reason: Deprecated
        status: "False"
        type: Deprecated
      - lastTransitionTime: "2024-06-11T15:55:50Z"
        message: ""
        observedGeneration: 1
        reason: Deprecated
        status: "False"
        type: PackageDeprecated
      - lastTransitionTime: "2024-06-11T15:55:50Z"
        message: ""
        observedGeneration: 1
        reason: Deprecated
        status: "False"
        type: ChannelDeprecated
      - lastTransitionTime: "2024-06-11T15:55:50Z"
        message: ""
        observedGeneration: 1
        reason: Deprecated
        status: "False"
        type: BundleDeprecated
      installedBundle:
        name: openshift-pipelines-operator-rh.v1.11.1
        version: 1.11.1
      resolvedBundle:
        name: openshift-pipelines-operator-rh.v1.11.1
        version: 1.11.1
  3. Edit your CR by using one of the following methods:

    • If you want to pin your Operator or extension to specific version, such as 1.12.1, edit your CR similar to the following example:

      Example pipelines-operator.yaml CR

      apiVersion: olm.operatorframework.io/v1alpha1
      kind: ClusterExtension
      metadata:
        name: pipelines-operator
      spec:
        packageName: openshift-pipelines-operator-rh
        installNamespace: <namespace>
        version: "1.12.1" 1

      1
      Update the version from 1.11.1 to 1.12.1
    • If you want to define a range of acceptable update versions, edit your CR similar to the following example:

      Example CR with a version range specified

      apiVersion: olm.operatorframework.io/v1alpha1
      kind: ClusterExtension
      metadata:
        name: pipelines-operator
      spec:
        packageName: openshift-pipelines-operator-rh
        installNamespace: <namespace>
        version: ">1.11.1, <1.13" 1

      1
      Specifies that the desired version range is greater than version 1.11.1 and less than 1.13. For more information, see "Support for version ranges" and "Version comparison strings".
    • If you want to update to the latest version that can be resolved from a channel, edit your CR similar to the following example:

      Example CR with a specified channel

      apiVersion: olm.operatorframework.io/v1alpha1
      kind: ClusterExtension
      metadata:
        name: pipelines-operator
      spec:
        packageName: openshift-pipelines-operator-rh
        installNamespace: <namespace>
        channel: pipelines-1.13 1

      1
      Installs the latest release that can be resolved from the specified channel. Updates to the channel are automatically installed.
    • If you want to specify a channel and version or version range, edit your CR similar to the following example:

      Example CR with a specified channel and version range

      apiVersion: olm.operatorframework.io/v1alpha1
      kind: ClusterExtension
      metadata:
        name: pipelines-operator
      spec:
        packageName: openshift-pipelines-operator-rh
        installNamespace: <namespace>
        channel: latest
        version: "<1.13"

      For more information, see "Example custom resources (CRs) that specify a target version".

  4. Apply the update to the cluster by running the following command:

    $ oc apply -f pipelines-operator.yaml

    Example output

    clusterextension.olm.operatorframework.io/pipelines-operator configured

    Tip

    You can patch and apply the changes to your CR from the CLI by running the following command:

    $ oc patch clusterextension/pipelines-operator -p \
      '{"spec":{"version":"<1.13"}}' \
      --type=merge

    Example output

    clusterextension.olm.operatorframework.io/pipelines-operator patched

Verification

  • Verify that the channel and version updates have been applied by running the following command:

    $ oc get clusterextension pipelines-operator -o yaml

    Example 7.21. Example output

    apiVersion: olm.operatorframework.io/v1alpha1
    kind: ClusterExtension
    metadata:
      annotations:
        kubectl.kubernetes.io/last-applied-configuration: |
          {"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","installNamespace":"openshift-operators","packageName":"openshift-pipelines-operator-rh","pollInterval":"30m","version":"\u003c1.13"}}
      creationTimestamp: "2024-06-11T18:23:26Z"
      generation: 2
      name: pipelines-operator
      resourceVersion: "66310"
      uid: ce0416ba-13ea-4069-a6c8-e5efcbc47537
    spec:
      channel: latest
      installNamespace: openshift-operators
      packageName: openshift-pipelines-operator-rh
      upgradeConstraintPolicy: Enforce
      version: <1.13
    status:
      conditions:
      - lastTransitionTime: "2024-06-11T18:23:33Z"
        message: resolved to "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:814742c8a7cc7e2662598e114c35c13993a7b423cfe92548124e43ea5d469f82"
        observedGeneration: 2
        reason: Success
        status: "True"
        type: Resolved
      - lastTransitionTime: "2024-06-11T18:23:52Z"
        message: installed from "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:814742c8a7cc7e2662598e114c35c13993a7b423cfe92548124e43ea5d469f82"
        observedGeneration: 2
        reason: Success
        status: "True"
        type: Installed
      - lastTransitionTime: "2024-06-11T18:23:33Z"
        message: ""
        observedGeneration: 2
        reason: Deprecated
        status: "False"
        type: Deprecated
      - lastTransitionTime: "2024-06-11T18:23:33Z"
        message: ""
        observedGeneration: 2
        reason: Deprecated
        status: "False"
        type: PackageDeprecated
      - lastTransitionTime: "2024-06-11T18:23:33Z"
        message: ""
        observedGeneration: 2
        reason: Deprecated
        status: "False"
        type: ChannelDeprecated
      - lastTransitionTime: "2024-06-11T18:23:33Z"
        message: ""
        observedGeneration: 2
        reason: Deprecated
        status: "False"
        type: BundleDeprecated
      installedBundle:
        name: openshift-pipelines-operator-rh.v1.12.2
        version: 1.12.2
      resolvedBundle:
        name: openshift-pipelines-operator-rh.v1.12.2
        version: 1.12.2

Troubleshooting

  • If you specify a target version or channel that is deprecated or does not exist, you can run the following command to check the status of your extension:

    $ oc get clusterextension <operator_name> -o yaml

    Example 7.22. Example output for a version that does not exist

    apiVersion: olm.operatorframework.io/v1alpha1
    kind: ClusterExtension
    metadata:
      annotations:
        kubectl.kubernetes.io/last-applied-configuration: |
          {"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","installNamespace":"openshift-operators","packageName":"openshift-pipelines-operator-rh","pollInterval":"30m","version":"3.0"}}
      creationTimestamp: "2024-06-11T18:23:26Z"
      generation: 3
      name: pipelines-operator
      resourceVersion: "71852"
      uid: ce0416ba-13ea-4069-a6c8-e5efcbc47537
    spec:
      channel: latest
      installNamespace: openshift-operators
      packageName: openshift-pipelines-operator-rh
      upgradeConstraintPolicy: Enforce
      version: "3.0"
    status:
      conditions:
      - lastTransitionTime: "2024-06-11T18:29:02Z"
        message: 'error upgrading from currently installed version "1.12.2": no package
          "openshift-pipelines-operator-rh" matching version "3.0" found in channel "latest"'
        observedGeneration: 3
        reason: ResolutionFailed
        status: "False"
        type: Resolved
      - lastTransitionTime: "2024-06-11T18:29:02Z"
        message: installation has not been attempted as resolution failed
        observedGeneration: 3
        reason: InstallationStatusUnknown
        status: Unknown
        type: Installed
      - lastTransitionTime: "2024-06-11T18:29:02Z"
        message: deprecation checks have not been attempted as resolution failed
        observedGeneration: 3
        reason: Deprecated
        status: Unknown
        type: Deprecated
      - lastTransitionTime: "2024-06-11T18:29:02Z"
        message: deprecation checks have not been attempted as resolution failed
        observedGeneration: 3
        reason: Deprecated
        status: Unknown
        type: PackageDeprecated
      - lastTransitionTime: "2024-06-11T18:29:02Z"
        message: deprecation checks have not been attempted as resolution failed
        observedGeneration: 3
        reason: Deprecated
        status: Unknown
        type: ChannelDeprecated
      - lastTransitionTime: "2024-06-11T18:29:02Z"
        message: deprecation checks have not been attempted as resolution failed
        observedGeneration: 3
        reason: Deprecated
        status: Unknown
        type: BundleDeprecated

7.3.9. Upgrade constraint semantics

When determining upgrade edges for an installed cluster extension, Operator Lifecycle Manager (OLM) 1.0 supports legacy OLM semantics starting in OpenShift Container Platform 4.16. This support follows the behavior from legacy OLM, including replaces, skips, and skipRange directives, with a few noted differences.

By supporting legacy OLM semantics, OLM 1.0 now honors the upgrade graph from catalogs accurately.

Differences from original legacy OLM implementation

  • If there are multiple possible successors, OLM 1.0 behavior differs in the following ways:

    • In legacy OLM, the successor closest to the channel head is chosen.
    • In OLM 1.0, the successor with the highest semantic version (semver) is chosen.
  • Consider the following set of file-based catalog (FBC) channel entries:

    # ...
    - name: example.v3.0.0
      skips: ["example.v2.0.0"]
    - name: example.v2.0.0
      skipRange: >=1.0.0 <2.0.0

    If 1.0.0 is installed, OLM 1.0 behavior differs in the following ways:

    • Legacy OLM will not see an upgrade edge to v2.0.0 because v2.0.0 is skipped and not on the replaces chain.
    • OLM 1.0 will see the upgrade edge because OLM 1.0 does not have a concept of a replaces chain. OLM 1.0 finds all entries that have a replace, skip, or skipRange value that covers the currently installed version.
Note

Support for semantic versioning (semver) upgrade constraints was introduced in OpenShift Container Platform 4.15 but disabled in 4.16 in favor of legacy OLM semantics during this Technology Preview phase.

Additional resources

7.3.9.1. Support for version ranges

In Operator Lifecycle Manager (OLM) 1.0, you can specify a version range by using a comparison string in an Operator or extension’s custom resource (CR). If you specify a version range in the CR, OLM 1.0 installs or updates to the latest version of the Operator that can be resolved within the version range.

Resolved version workflow

  • The resolved version is the latest version of the Operator that satisfies the constraints of the Operator and the environment.
  • An Operator update within the specified range is automatically installed if it is resolved successfully.
  • An update is not installed if it is outside of the specified range or if it cannot be resolved successfully.

7.3.9.2. Version comparison strings

You can define a version range by adding a comparison string to the spec.version field in an Operator or extension’s custom resource (CR). A comparison string is a list of space- or comma-separated values and one or more comparison operators enclosed in double quotation marks ("). You can add another comparison string by including an OR, or double vertical bar (||), comparison operator between the strings.

Table 7.4. Basic comparisons
Comparison operatorDefinition

=

Equal to

!=

Not equal to

>

Greater than

<

Less than

>=

Greater than or equal to

<=

Less than or equal to

You can specify a version range in an Operator or extension’s CR by using a range comparison similar to the following example:

Example version range comparison

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: ">=1.11, <1.13"

You can use wildcard characters in all types of comparison strings. OLM 1.0 accepts x, X, and asterisks (*) as wildcard characters. When you use a wildcard character with the equal sign (=) comparison operator, you define a comparison at the patch or minor version level.

Table 7.5. Example wildcard characters in comparison strings
Wildcard comparisonMatching string

1.11.x

>=1.11.0, <1.12.0

>=1.12.X

>=1.12.0

<=2.x

<3

*

>=0.0.0

You can make patch release comparisons by using the tilde (~) comparison operator. Patch release comparisons specify a minor version up to the next major version.

Table 7.6. Example patch release comparisons
Patch release comparisonMatching string

~1.11.0

>=1.11.0, <1.12.0

~1

>=1, <2

~1.12

>=1.12, <1.13

~1.12.x

>=1.12.0, <1.13.0

~1.x

>=1, <2

You can use the caret (^) comparison operator to make a comparison for a major release. If you make a major release comparison before the first stable release is published, the minor versions define the API’s level of stability. In the semantic versioning (semver) specification, the first stable release is published as the 1.0.0 version.

Table 7.7. Example major release comparisons
Major release comparisonMatching string

^0

>=0.0.0, <1.0.0

^0.0

>=0.0.0, <0.1.0

^0.0.3

>=0.0.3, <0.0.4

^0.2

>=0.2.0, <0.3.0

^0.2.3

>=0.2.3, <0.3.0

^1.2.x

>= 1.2.0, < 2.0.0

^1.2.3

>= 1.2.3, < 2.0.0

^2.x

>= 2.0.0, < 3

^2.3

>= 2.3, < 3

7.3.9.3. Example custom resources (CRs) that specify a target version

In Operator Lifecycle Manager (OLM) 1.0, cluster administrators can declaratively set the target version of an Operator or extension in the custom resource (CR).

You can define a target version by specifying any of the following fields:

  • Channel
  • Version number
  • Version range

If you specify a channel in the CR, OLM 1.0 installs the latest version of the Operator or extension that can be resolved within the specified channel. When updates are published to the specified channel, OLM 1.0 automatically updates to the latest release that can be resolved from the channel.

Example CR with a specified channel

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  channel: latest 1

1
Installs the latest release that can be resolved from the specified channel. Updates to the channel are automatically installed.

If you specify the Operator or extension’s target version in the CR, OLM 1.0 installs the specified version. When the target version is specified in the CR, OLM 1.0 does not change the target version when updates are published to the catalog.

If you want to update the version of the Operator that is installed on the cluster, you must manually edit the Operator’s CR. Specifying an Operator’s target version pins the Operator’s version to the specified release.

Example CR with the target version specified

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: "1.11.1" 1

1
Specifies the target version. If you want to update the version of the Operator or extension that is installed, you must manually update this field the CR to the desired target version.

If you want to define a range of acceptable versions for an Operator or extension, you can specify a version range by using a comparison string. When you specify a version range, OLM 1.0 installs the latest version of an Operator or extension that can be resolved by the Operator Controller.

Example CR with a version range specified

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: ">1.11.1" 1

1
Specifies that the desired version range is greater than version 1.11.1. For more information, see "Support for version ranges".

After you create or update a CR, apply the configuration file by running the following command:

Command syntax

$ oc apply -f <extension_name>.yaml

7.3.9.4. Forcing an update or rollback

OLM 1.0 does not support automatic updates to the next major version or rollbacks to an earlier version. If you want to perform a major version update or rollback, you must verify and force the update manually.

Warning

You must verify the consequences of forcing a manual update or rollback. Failure to verify a forced update or rollback might have catastrophic consequences such as data loss.

Prerequisites

  • You have a catalog installed.
  • You have an Operator or extension installed.

Procedure

  1. Edit the custom resource (CR) of your Operator or extension as shown in the following example:

    Example CR

    apiVersion: olm.operatorframework.io/v1alpha1
    kind: Operator
    metadata:
      name: <operator_name> 1
    spec:
      packageName: <package_name> 2
      installNamespace: <namespace_name>
      version: <version> 3
      upgradeConstraintPolicy: Ignore 4

    1
    Specifies the name of the Operator or extension, such as pipelines-operator
    2
    Specifies the package name, such as openshift-pipelines-operator-rh.
    3
    Specifies the blocked update or rollback version.
    4
    Optional: Specifies the upgrade constraint policy. To force an update or rollback, set the field to Ignore. If unspecified, the default setting is Enforce.
  2. Apply the changes to your Operator or extensions CR by running the following command:

    $ oc apply -f <extension_name>.yaml

Additional resources

7.3.10. Deleting an Operator

You can delete an Operator and its custom resource definitions (CRDs) by deleting the ClusterExtension custom resource (CR).

Prerequisites

  • You have a catalog installed.
  • You have an Operator installed.

Procedure

  • Delete an Operator and its CRDs by running the following command:

    $ oc delete clusterextension <operator_name>

    Example output

    clusterextension.olm.operatorframework.io "<operator_name>" deleted

Verification

  • Run the following commands to verify that your Operator and its resources were deleted:

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

      $ oc get clusterextensions

      Example output

      No resources found

    • Verify that the Operator’s system namespace is deleted by running the following command:

      $ oc get ns <operator_name>-system

      Example output

      Error from server (NotFound): namespaces "<operator_name>-system" not found

7.3.11. 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 catalog <catalog_name>

    Example output

    catalog.catalogd.operatorframework.io "my-catalog" deleted

Verification

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

    $ oc get catalog
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.

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.

© 2024 Red Hat, Inc.