Chapter 7. OLM 1.0 (Technology Preview)

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

Procedure

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

   $ oc -n openshift-catalogd port-forward svc/catalogd-catalogserver 8080:80

2. Download the catalog’s JSON file locally by running the following command:

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

   Example 7.4. Example command

   $ curl -L http://localhost:8080/catalogs/redhat-operators/all.json \
     -C - -o /home/username/catalogs/rhoc.json

3. Run one of the following commands to return a list of Operators and extensions in a catalog.

   Important

   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 7.5. Example command

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

     Example 7.6. Example output

     NAME                                                        AGE
     "3scale-operator"
     "advanced-cluster-management"
     "amq-broker-rhel8"
     "amq-online"
     "amq-streams"
     "amq7-interconnect-operator"
     "ansible-automation-platform-operator"
     "ansible-cloud-addons-operator"
     "apicast-operator"
     "aws-efs-csi-driver-operator"
     "aws-load-balancer-operator"
     "bamoe-businessautomation-operator"
     "bamoe-kogito-operator"
     "bare-metal-event-relay"
     "businessautomation-operator"
     ...

   • Get list of packages that support AllNamespaces install mode and do not use webhooks from the local catalog file by running the following command:

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

     Example 7.7. Example output

     {"package":"3scale-operator","version":"0.10.0-mas"}
     {"package":"3scale-operator","version":"0.10.5"}
     {"package":"3scale-operator","version":"0.11.0-mas"}
     {"package":"3scale-operator","version":"0.11.1-mas"}
     {"package":"3scale-operator","version":"0.11.2-mas"}
     {"package":"3scale-operator","version":"0.11.3-mas"}
     {"package":"3scale-operator","version":"0.11.5-mas"}
     {"package":"3scale-operator","version":"0.11.6-mas"}
     {"package":"3scale-operator","version":"0.11.7-mas"}
     {"package":"3scale-operator","version":"0.11.8-mas"}
     {"package":"amq-broker-rhel8","version":"7.10.0-opr-1"}
     {"package":"amq-broker-rhel8","version":"7.10.0-opr-2"}
     {"package":"amq-broker-rhel8","version":"7.10.0-opr-3"}
     {"package":"amq-broker-rhel8","version":"7.10.0-opr-4"}
     {"package":"amq-broker-rhel8","version":"7.10.1-opr-1"}
     {"package":"amq-broker-rhel8","version":"7.10.1-opr-2"}
     {"package":"amq-broker-rhel8","version":"7.10.2-opr-1"}
     {"package":"amq-broker-rhel8","version":"7.10.2-opr-2"}
     ...

4. Inspect the contents of an Operator or extension’s metadata by running the following command:

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

   Example 7.8. Example command

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

   Example 7.9. Example output

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

Procedure

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

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

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

      Example 7.10. Example command

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

      Example 7.11. Example output

      "latest"
      "pipelines-1.11"
      "pipelines-1.12"
      "pipelines-1.13"
      "pipelines-1.14"

   2. Get a list of the versions published in a channel by running the following command:

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

      Example 7.12. Example command

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

      Example 7.13. Example output

      "openshift-pipelines-operator-rh.v1.12.0"
      "openshift-pipelines-operator-rh.v1.12.1"
      "openshift-pipelines-operator-rh.v1.12.2"
      "openshift-pipelines-operator-rh.v1.13.0"
      "openshift-pipelines-operator-rh.v1.13.1"
      "openshift-pipelines-operator-rh.v1.11.1"
      "openshift-pipelines-operator-rh.v1.12.0"
      "openshift-pipelines-operator-rh.v1.12.1"
      "openshift-pipelines-operator-rh.v1.12.2"
      "openshift-pipelines-operator-rh.v1.13.0"
      "openshift-pipelines-operator-rh.v1.14.1"
      "openshift-pipelines-operator-rh.v1.14.2"
      "openshift-pipelines-operator-rh.v1.14.3"
      "openshift-pipelines-operator-rh.v1.14.4"

2. If you want to install your extension into a new namespace, run the following command:

   $ oc adm new-project <new_namespace>

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

   Example pipelines-operator.yaml CR

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

   where:

   <namespace>

   Specifies the namespace where you want the bundle installed, such as openshift-operators or my-extension. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces.

   <channel>

   Optional: Specifies the channel, such as pipelines-1.11 or latest, for the package you want to install or update.

   <version>

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

   Important

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

   • If mulitple catalogs are installed on a cluster, 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.

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

   $ oc apply -f pipeline-operator.yaml

   Example output

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

Verification

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

   $ oc get clusterextension pipelines-operator -o yaml

   Example 7.14. Example output

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

   where:

   spec.channel

   Displays the channel defined in the CR of the extension.

   spec.version

   Displays the version or version range defined in the CR of the extension.

   status.conditions

   Displays information about the status and health of the extension.

   type: Deprecated

   Displays whether one or more of following are deprecated:

   type: PackageDeprecated

   Displays whether the resolved package is deprecated.

   type: ChannelDeprecated

   Displays whether the resolved channel is deprecated.

   type: BundleDeprecated

   Displays whether the resolved bundle is deprecated.

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

   installedBundle.name

   Displays the name of the bundle installed.

   installedBundle.version

   Displays the version of the bundle installed.

   resolvedBundle.name

   Displays the name of the resolved bundle.

   resolvedBundle.version

   Displays the verson of the resolved bundle.

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

   $ oc get bundleDeployment pipelines-operator -o yaml

   Example 7.15. Example output

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

Procedure

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

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

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

      Example 7.16. Example command

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

      Example 7.17. Example output

      "latest"
      "pipelines-1.11"
      "pipelines-1.12"
      "pipelines-1.13"
      "pipelines-1.14"

   2. Get a list of the versions published in a channel by running the following command:

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

      Example 7.18. Example command

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

      Example 7.19. Example output

      "openshift-pipelines-operator-rh.v1.11.1"
      "openshift-pipelines-operator-rh.v1.12.0"
      "openshift-pipelines-operator-rh.v1.12.1"
      "openshift-pipelines-operator-rh.v1.12.2"
      "openshift-pipelines-operator-rh.v1.13.0"
      "openshift-pipelines-operator-rh.v1.14.1"
      "openshift-pipelines-operator-rh.v1.14.2"
      "openshift-pipelines-operator-rh.v1.14.3"
      "openshift-pipelines-operator-rh.v1.14.4"

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

   $ oc get clusterextension <operator_name> -o yaml

   Example command

   $ oc get clusterextension pipelines-operator -o yaml

   Example 7.20. Example output

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

3. Edit your CR by using one of the following methods:

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

     Example pipelines-operator.yaml CR

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

     1

     Update the version from 1.11.1 to 1.12.1

   • If you want to define a range of acceptable update versions, edit your CR similar to the following example:

     Example CR with a version range specified

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

     1

     Specifies that the desired version range is greater than version 1.11.1 and less than 1.13. For more information, see "Support for version ranges" and "Version comparison strings".

   • If you want to update to the latest version that can be resolved from a channel, edit your CR similar to the following example:

     Example CR with a specified channel

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

     1

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

   • If you want to specify a channel and version or version range, edit your CR similar to the following example:

     Example CR with a specified channel and version range

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

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

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

   $ oc apply -f pipelines-operator.yaml

   Example output

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

   Tip

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

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

   Example output

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