1. Documentation
×

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 OKD cluster using an account with cluster-admin permissions

    For OKD 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

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

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

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

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

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

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

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

Upgrade constraint semantics

When determining upgrade edges for an installed cluster extension, Operator Lifecycle Manager (OLM) 1.0 supports legacy OLM semantics starting in OKD 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.

Support for semantic versioning (semver) upgrade constraints was introduced in OKD 4.15 but disabled in 4.16 in favor of legacy OLM semantics during this Technology Preview phase.
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 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.

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

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

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

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