1. Documentation
    2. history bug_report picture_as_pdf
×

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

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.

Prerequisites

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

    For OpenShift Container Platform 4.15, 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 TechPreviewNoUpgrades feature set enabled on the cluster

    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

Additional resources

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.

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

  • Dependency resolution in Operator Lifecycle Manager (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

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.

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.15
      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.15
      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.15
      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.
Additional resources

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.

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

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.15 (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-01-10T16:18:38Z
  Finalizers:
    catalogd.operatorframework.io/delete-server-cache
  Generation:        1
  Resource Version:  57057
  UID:               128db204-49b3-45ee-bfea-a2e6fc8e34ea
Spec:
  Source:
    Image:
      Pull Secret:  redhat-cred
      Ref:          registry.redhat.io/redhat/redhat-operator-index:v4.15
    Type:           image
Status: (1)
  Conditions:
    Last Transition Time:  2024-01-10T16:18:55Z
    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-01-10T16:18:51Z
      Ref:                registry.redhat.io/redhat/redhat-operator-index:v4.15
      Resolved Ref:       registry.redhat.io/redhat/redhat-operator-index@sha256:7b536ae19b8e9f74bb521c4a61e5818e036ac1865a932f2157c6c9a766b2eea5 (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.
Additional resources

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

    Currently, Operator Lifecycle Manager (OLM) 1.0 supports extensions that do not use webhooks and are configured to use the AllNamespaces install mode. Extensions that use webhooks or that target a single or specified set of namespaces cannot be installed.

    • 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 command 
      $ jq -s '.[] | select(.schema == "olm.package") | .name' \
  /home/username/catalogs/rhoc.json
      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 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 command 
    $ jq -s '.[] | select( .schema == "olm.package") | \
  select( .name == "openshift-pipelines-operator-rh")' \
  /home/username/rhoc.json
    Example output 
    {
  "defaultChannel": "stable",
  "icon": {
    "base64data": "PHN2ZyB4bWxu..."
    "mediatype": "image/png"
  },
  "name": "openshift-pipelines-operator-rh",
  "schema": "olm.package"
}

Common catalog queries

You can query catalogs by using the jq CLI tool.

Table 1. Common package queries
Query Request

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 2. Common channel queries
Query Request

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 3. Common bundle queries
Query Request

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

Installing an Operator from a catalog

Operator Lifecycle Manager (OLM) 1.0 supports installing Operators and extensions scoped to the cluster. You can install an Operator or extension from a catalog by creating a custom resource (CR) and applying it to the cluster.

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

  • The Operator or extension must use the AllNamespaces install mode.

  • The Operator or extension must not use webhooks.

Operators and 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 command 
      $ jq -s '.[] | select( .schema == "olm.channel" ) | \
  select( .package == "openshift-pipelines-operator-rh") | \
  .name' /home/username/rhoc.json
      Example output 
      "latest"
"pipelines-1.11"
"pipelines-1.12"
"pipelines-1.13"

    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 command 
      $ jq -s '.[] | select( .package == "openshift-pipelines-operator-rh" ) | \
select( .schema == "olm.channel" ) | select( .name == "latest" ) | \
.entries | .[] | .name' /home/username/rhoc.json
      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.13.1"

  2. Create a CR, similar to the following example:

    Example pipelines-operator.yaml CR
    apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  channel: <channel>
  version: "<version>"

    where:

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

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

    • Dependency resolution in Operator Lifecycle Manager (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.

  3. Apply the CR to the cluster by running the following command:

    $ oc apply -f pipeline-operator.yaml
    Example output
    operator.operators.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 operator.operators.operatorframework.io pipelines-operator -o yaml

    If you specify a channel or define a version range in your Operator or extension’s CR, OLM 1.0 does not display the resolved version installed on the cluster. Only the version and channel information specified in the CR are displayed.

    If you want to find the specific version that is installed, you must compare the SHA of the image of the spec.source.image.ref field to the image reference in the catalog.
    Example output 
    apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","packageName":"openshift-pipelines-operator-rh","version":"1.11.x"}}
  creationTimestamp: "2024-01-30T20:06:09Z"
  generation: 1
  name: pipelines-operator
  resourceVersion: "44362"
  uid: 4272d228-22e1-419e-b9a7-986f982ee588
spec:
  channel: latest
  packageName: openshift-pipelines-operator-rh
  upgradeConstraintPolicy: Enforce
  version: 1.11.x
status:
  conditions:
  - lastTransitionTime: "2024-01-30T20:06:15Z"
    message: resolved to "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280"
    observedGeneration: 1
    reason: Success
    status: "True"
    type: Resolved
  - lastTransitionTime: "2024-01-30T20:06:31Z"
    message: installed from "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280"
    observedGeneration: 1
    reason: Success
    status: "True"
    type: Installed
  installedBundleResource: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280
  resolvedBundleResource: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280

  2. Get information about your bundle deployment by running the following command:

    $ oc get bundleDeployment pipelines-operator -o yaml
    Example output 
    apiVersion: core.rukpak.io/v1alpha1
kind: BundleDeployment
metadata:
  creationTimestamp: "2024-01-30T20:06:15Z"
  generation: 2
  name: pipelines-operator
  ownerReferences:
  - apiVersion: operators.operatorframework.io/v1alpha1
    blockOwnerDeletion: true
    controller: true
    kind: Operator
    name: pipelines-operator
    uid: 4272d228-22e1-419e-b9a7-986f982ee588
  resourceVersion: "44464"
  uid: 0a0c3525-27e2-4c93-bf57-55920a7707c0
spec:
  provisionerClassName: core-rukpak-io-plain
  template:
    metadata: {}
    spec:
      provisionerClassName: core-rukpak-io-registry
      source:
        image:
          ref: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280
        type: image
status:
  activeBundle: pipelines-operator-29x720cjzx8yiowf13a3j75fil2zs3mfw
  conditions:
  - lastTransitionTime: "2024-01-30T20:06:15Z"
    message: Successfully unpacked the pipelines-operator-29x720cjzx8yiowf13a3j75fil2zs3mfw
      Bundle
    reason: UnpackSuccessful
    status: "True"
    type: HasValidBundle
  - lastTransitionTime: "2024-01-30T20:06:28Z"
    message: Instantiated bundle pipelines-operator-29x720cjzx8yiowf13a3j75fil2zs3mfw
      successfully
    reason: InstallationSucceeded
    status: "True"
    type: Installed
  - lastTransitionTime: "2024-01-30T20:06:40Z"
    message: BundleDeployment is healthy
    reason: Healthy
    status: "True"
    type: Healthy
  observedGeneration: 2
Additional resources

Updating an Operator

You can update your Operator or extension 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 command 
      $ jq -s '.[] | select( .schema == "olm.channel" ) | \
  select( .package == "openshift-pipelines-operator-rh") | \
  .name' /home/username/rhoc.json
      Example output 
      "latest"
"pipelines-1.11"
"pipelines-1.12"
"pipelines-1.13"

    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 command 
      $ jq -s '.[] | select( .package == "openshift-pipelines-operator-rh" ) | \
select( .schema == "olm.channel" ) | select( .name == "latest" ) | \
.entries | .[] | .name' /home/username/rhoc.json
      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.13.1"

  2. Find out what version or channel is specified in your Operator or extension’s CR by running the following command:

    $ oc get operator.operators.operatorframework.io <operator_name> -o yaml
    Example command
    $ oc get operator.operators.operatorframework.io pipelines-operator -o yaml
    Example output 
    apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |  {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","packageName":"openshift-pipelines-operator-rh","version":"1.11.1"}}
  creationTimestamp: "2024-02-06T17:47:15Z"
  generation: 2
  name: pipelines-operator
  resourceVersion: "84528"
  uid: dffe2c89-b9c4-427e-b694-ada0b37fc0a9
spec:
  channel: latest (1)
  packageName: openshift-pipelines-operator-rh
  upgradeConstraintPolicy: Enforce
  version: 1.11.1 (2)
status:
  conditions:
  - lastTransitionTime: "2024-02-06T17:47:21Z"
    message: bundledeployment status is unknown
    observedGeneration: 2
    reason: InstallationStatusUnknown
    status: Unknown
    type: Installed
  - lastTransitionTime: "2024-02-06T17:50:58Z"
    message: resolved to "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280"
    observedGeneration: 2
    reason: Success
    status: "True"
    type: Resolved
  resolvedBundleResource: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:e09d37bb1e754db42324fd18c1cb3e7ce77e7b7fcbf4932d0535391579938280
    1 Specifies the channel for your Operator or extension.
    2 Specifies the version or version range for your Operator or extension.

    If you specify a channel or define a version range in your Operator or extension’s CR, OLM 1.0 does not display the resolved version installed on the cluster. Only the version and channel information specified in the CR are displayed.

    If you want to find the specific version that is installed, you must compare the SHA of the image of the spec.source.image.ref field to the image reference in the catalog.

  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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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
    operator.operators.operatorframework.io/pipelines-operator configured

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

    $ oc patch operator.operators.operatorframework.io/pipelines-operator -p \
  '{"spec":{"version":"1.12.1"}}' \
  --type=merge
    Example output
    operator.operators.operatorframework.io/pipelines-operator patched
Verification

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

    $ oc get operator.operators.operatorframework.io pipelines-operator -o yaml
    Example output 
    apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","packageName":"openshift-pipelines-operator-rh","version":"1.12.1"}}
  creationTimestamp: "2024-02-06T19:16:12Z"
  generation: 4
  name: pipelines-operator
  resourceVersion: "58122"
  uid: 886bbf73-604f-4484-9f87-af6ce0f86914
spec:
  channel: latest
  packageName: openshift-pipelines-operator-rh
  upgradeConstraintPolicy: Enforce
  version: 1.12.1 (1)
status:
  conditions:
  - lastTransitionTime: "2024-02-06T19:30:57Z"
    message: installed from "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:2f1b8ef0fd741d1d686489475423dabc07c55633a4dfebc45e1d533183179f6a"
    observedGeneration: 3
    reason: Success
    status: "True"
    type: Installed
  - lastTransitionTime: "2024-02-06T19:30:57Z"
    message: resolved to "registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:2f1b8ef0fd741d1d686489475423dabc07c55633a4dfebc45e1d533183179f6a"
    observedGeneration: 3
    reason: Success
    status: "True"
    type: Resolved
  installedBundleResource: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:2f1b8ef0fd741d1d686489475423dabc07c55633a4dfebc45e1d533183179f6a
  resolvedBundleResource: registry.redhat.io/openshift-pipelines/pipelines-operator-bundle@sha256:2f1b8ef0fd741d1d686489475423dabc07c55633a4dfebc45e1d533183179f6a
    1 Verify that the version is updated to 1.12.1.
Troubleshooting

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

    $ oc get operator.operators.operatorframework.io <operator_name> -o yaml
    Example output 
    oc get operator.operators.operatorframework.io pipelines-operator -o yaml
apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"pipelines-operator"},"spec":{"channel":"latest","packageName":"openshift-pipelines-operator-rh","version":"2.0.0"}}
  creationTimestamp: "2024-02-06T17:47:15Z"
  generation: 1
  name: pipelines-operator
  resourceVersion: "82667"
  uid: dffe2c89-b9c4-427e-b694-ada0b37fc0a9
spec:
  channel: latest
  packageName: openshift-pipelines-operator-rh
  upgradeConstraintPolicy: Enforce
  version: 2.0.0
status:
  conditions:
  - lastTransitionTime: "2024-02-06T17:47:21Z"
    message: installation has not been attempted due to failure to gather data for
      resolution
    observedGeneration: 1
    reason: InstallationStatusUnknown
    status: Unknown
    type: Installed
  - lastTransitionTime: "2024-02-06T17:47:21Z"
    message: no package "openshift-pipelines-operator-rh" matching version "2.0.0"
      found in channel "latest"
    observedGeneration: 1
    reason: ResolutionFailed
    status: "False"
    type: Resolved
Additional resources

Support for semantic versioning

Support for semantic versioning (semver) is enabled in OLM 1.0 by default. Operator and extension authors can use the semver standard to define compatible updates.

Operator Lifecycle Manager (OLM) 1.0 can use an Operator or extension’s version number to determine if an update can be resolved successfully.

Cluster administrators can define a range of acceptable versions to install and automtically update. For Operators and extensions that follow the semver standard, you can use comparison strings to define to specify a desired version range.

OLM 1.0 does not support automatic updates to the next major version. If you want to perform a major version update, you must verify and apply the update manually. For more information, see "Forcing an update or rollback".

Major version zero releases

The semver standard specifies that major version zero releases (O.y.z) are reserved for initial development. During the initial development stage, the API is not stable and breaking changes might be introduced in any published version. As a result, major version zero releases apply a special set of update conditions.

Update conditions for major version zero releases

  • You cannot apply automatic updates when the major and minor versions are both zero, such as 0.0.*. For example, automatic updates with the version range of >=0.0.1 <0.1.0 are not allowed.

  • You cannot apply automatic updates from one minor version to another within a major version zero release. For example, OLM 1.0 does not automatically apply an update from 0.1.0 to 0.2.0.

  • You can apply automatic updates from patch versions, such as >=0.1.0 <0.2.0 or >=0.2.0 <0.3.0.

When an automatic update is blocked by OLM 1.0, you must manually verify and force the update by editing the Operator or extension’s custom resource (CR).

Additional resources

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 dependencies and 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.

For more information about dependency and constraint resolution in OLM 1.0, see "Dependency resolution in OLM 1.0".

Additional resources

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 4. Basic comparisons
Comparison operator Definition

=

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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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 5. Example wildcard characters in comparison strings
Wildcard comparison Matching 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 6. Example patch release comparisons
Patch release comparison Matching 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 use 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. Example major release comparisons
Major release comparison Matching 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

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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  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

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.

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

Deleting an Operator

You can delete an Operator and its custom resource definitions (CRDs) by deleting the Operator’s 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 operator.operators.operatorframework.io <operator_name>
    Example output
    operator.operators.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 operator.operators.operatorframework.io
      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

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