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

   1

   Specify the catalog’s image in the spec.source.image field.

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. Get a list of the Operators and extensions in the catalog by running the following command:

   $ oc get packages

   Example 7.1. Example output

   NAME                                                        AGE
   redhat-operators-3scale-operator                            5m27s
   redhat-operators-advanced-cluster-management                5m27s
   redhat-operators-amq-broker-rhel8                           5m27s
   redhat-operators-amq-online                                 5m27s
   redhat-operators-amq-streams                                5m27s
   redhat-operators-amq7-interconnect-operator                 5m27s
   redhat-operators-ansible-automation-platform-operator       5m27s
   redhat-operators-ansible-cloud-addons-operator              5m27s
   redhat-operators-apicast-operator                           5m27s
   redhat-operators-aws-efs-csi-driver-operator                5m27s
   redhat-operators-aws-load-balancer-operator                 5m27s
   ...

2. Inspect the contents of an Operator or extension’s custom resource (CR) by running the following command:

   $ oc get package <catalog_name>-<package_name> -o yaml

   Example command

   $ oc get package redhat-operators-quay-operator -o yaml

   Example 7.2. Example output

   apiVersion: catalogd.operatorframework.io/v1alpha1
   kind: Package
   metadata:
     creationTimestamp: "2023-10-06T01:14:04Z"
     generation: 1
     labels:
       catalog: redhat-operators
     name: redhat-operators-quay-operator
     ownerReferences:
     - apiVersion: catalogd.operatorframework.io/v1alpha1
       blockOwnerDeletion: true
       controller: true
       kind: Catalog
       name: redhat-operators
       uid: 403004b6-54a3-4471-8c90-63419f6a2c3e
     resourceVersion: "45196"
     uid: 252cfe74-936d-44fc-be5d-09a7be7e36f5
   spec:
     catalog:
       name: redhat-operators
     channels:
     - entries:
       - name: quay-operator.v3.4.7
         skips:
         - red-hat-quay.v3.3.4
         - quay-operator.v3.4.6
         - quay-operator.v3.4.5
         - quay-operator.v3.4.4
         - quay-operator.v3.4.3
         - quay-operator.v3.4.2
         - quay-operator.v3.4.1
         - quay-operator.v3.4.0
       name: quay-v3.4
     - entries:
       - name: quay-operator.v3.5.7
         replaces: quay-operator.v3.5.6
         skipRange: '>=3.4.x <3.5.7'
       name: quay-v3.5
     - entries:
       - name: quay-operator.v3.6.0
         skipRange: '>=3.3.x <3.6.0'
       - name: quay-operator.v3.6.1
         replaces: quay-operator.v3.6.0
         skipRange: '>=3.3.x <3.6.1'
       - name: quay-operator.v3.6.10
         replaces: quay-operator.v3.6.9
         skipRange: '>=3.3.x <3.6.10'
       - name: quay-operator.v3.6.2
         replaces: quay-operator.v3.6.1
         skipRange: '>=3.3.x <3.6.2'
       - name: quay-operator.v3.6.4
         replaces: quay-operator.v3.6.2
         skipRange: '>=3.3.x <3.6.4'
       - name: quay-operator.v3.6.5
         replaces: quay-operator.v3.6.4
         skipRange: '>=3.3.x <3.6.5'
       - name: quay-operator.v3.6.6
         replaces: quay-operator.v3.6.5
         skipRange: '>=3.3.x <3.6.6'
       - name: quay-operator.v3.6.7
         replaces: quay-operator.v3.6.6
         skipRange: '>=3.3.x <3.6.7'
       - name: quay-operator.v3.6.8
         replaces: quay-operator.v3.6.7
         skipRange: '>=3.3.x <3.6.8'
       - name: quay-operator.v3.6.9
         replaces: quay-operator.v3.6.8
         skipRange: '>=3.3.x <3.6.9'
       name: stable-3.6
     - entries:
       - name: quay-operator.v3.7.10
         replaces: quay-operator.v3.7.9
         skipRange: '>=3.4.x <3.7.10'
       - name: quay-operator.v3.7.11
         replaces: quay-operator.v3.7.10
         skipRange: '>=3.4.x <3.7.11'
       - name: quay-operator.v3.7.12
         replaces: quay-operator.v3.7.11
         skipRange: '>=3.4.x <3.7.12'
       - name: quay-operator.v3.7.13
         replaces: quay-operator.v3.7.12
         skipRange: '>=3.4.x <3.7.13'
       - name: quay-operator.v3.7.14
         replaces: quay-operator.v3.7.13
         skipRange: '>=3.4.x <3.7.14'
       name: stable-3.7
     - entries:
       - name: quay-operator.v3.8.0
         skipRange: '>=3.5.x <3.8.0'
       - name: quay-operator.v3.8.1
         replaces: quay-operator.v3.8.0
         skipRange: '>=3.5.x <3.8.1'
       - name: quay-operator.v3.8.10
         replaces: quay-operator.v3.8.9
         skipRange: '>=3.5.x <3.8.10'
       - name: quay-operator.v3.8.11
         replaces: quay-operator.v3.8.10
         skipRange: '>=3.5.x <3.8.11'
       - name: quay-operator.v3.8.12
         replaces: quay-operator.v3.8.11
         skipRange: '>=3.5.x <3.8.12'
       - name: quay-operator.v3.8.2
         replaces: quay-operator.v3.8.1
         skipRange: '>=3.5.x <3.8.2'
       - name: quay-operator.v3.8.3
         replaces: quay-operator.v3.8.2
         skipRange: '>=3.5.x <3.8.3'
       - name: quay-operator.v3.8.4
         replaces: quay-operator.v3.8.3
         skipRange: '>=3.5.x <3.8.4'
       - name: quay-operator.v3.8.5
         replaces: quay-operator.v3.8.4
         skipRange: '>=3.5.x <3.8.5'
       - name: quay-operator.v3.8.6
         replaces: quay-operator.v3.8.5
         skipRange: '>=3.5.x <3.8.6'
       - name: quay-operator.v3.8.7
         replaces: quay-operator.v3.8.6
         skipRange: '>=3.5.x <3.8.7'
       - name: quay-operator.v3.8.8
         replaces: quay-operator.v3.8.7
         skipRange: '>=3.5.x <3.8.8'
       - name: quay-operator.v3.8.9
         replaces: quay-operator.v3.8.8
         skipRange: '>=3.5.x <3.8.9'
       name: stable-3.8
     - entries:
       - name: quay-operator.v3.9.0
         skipRange: '>=3.6.x <3.9.0'
       - name: quay-operator.v3.9.1
         replaces: quay-operator.v3.9.0
         skipRange: '>=3.6.x <3.9.1'
       - name: quay-operator.v3.9.2
         replaces: quay-operator.v3.9.1
         skipRange: '>=3.6.x <3.9.2'
       name: stable-3.9
     defaultChannel: stable-3.9
     description: ""
     icon:
       data: PD94bWwgdmVyc2lvbj ...
       mediatype: image/svg+xml
     packageName: quay-operator
   status: {}

Procedure

1. Create an Operator CR, similar to the following example:

   Example test-operator.yaml CR

   apiVersion: operators.operatorframework.io/v1alpha1
   kind: Operator
   metadata:
     name: quay-example
   spec:
     packageName: quay-operator
     version: 3.8.12

2. Apply the Operator CR to the cluster by running the following command:

   $ oc apply -f test-operator.yaml

   Example output

   operator.operators.operatorframework.io/quay-example created

Verification

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

   $ oc get operator.operators.operatorframework.io/quay-example -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":"quay-example"},"spec":{"packageName":"quay-operator","version":"3.8.12"}}
     creationTimestamp: "2023-10-19T18:39:37Z"
     generation: 1
     name: quay-example
     resourceVersion: "45663"
     uid: 2558623b-8689-421c-8ed5-7b14234af166
   spec:
     packageName: quay-operator
     version: 3.8.12
   status:
     conditions:
     - lastTransitionTime: "2023-10-19T18:39:37Z"
       message: resolved to "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
       observedGeneration: 1
       reason: Success
       status: "True"
       type: Resolved
     - lastTransitionTime: "2023-10-19T18:39:46Z"
       message: installed from "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
       observedGeneration: 1
       reason: Success
       status: "True"
       type: Installed
     installedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7
     resolvedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7

2. Get information about your Operator’s controller manager pod by running the following command:

   $ oc get pod -n quay-operator-system

   Example output

   NAME                                     READY   STATUS    RESTARTS   AGE
   quay-operator.v3.8.12-6677b5c98f-2kdtb   1/1     Running   0          2m28s

Procedure

1. Inspect your Operator’s package contents to find which channels and versions are available for updating by running the following command:

   $ oc get package <catalog_name>-<package_name> -o yaml

   Example command

   $ oc get package redhat-operators-quay-operator -o yaml

2. Edit your Operator’s CR to update the version to 3.9.1, as shown in the following example:

   Example test-operator.yaml CR

   apiVersion: operators.operatorframework.io/v1alpha1
   kind: Operator
   metadata:
     name: quay-example
   spec:
     packageName: quay-operator
     version: 3.9.1 1

   1

   Update the version to 3.9.1

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

   $ oc apply -f test-operator.yaml

   Example output

   operator.operators.operatorframework.io/quay-example configured

   Tip

   You can patch and apply the changes to your Operator’s version from the CLI by running the following command:

   $ oc patch operator.operators.operatorframework.io/quay-example -p \
     '{"spec":{"version":"3.9.1"}}' \
     --type=merge

   Example output

   operator.operators.operatorframework.io/quay-example patched

Procedure

1. At the root of your project, create a Dockerfile that can build a bundle image:

   Example plainbundle.Dockerfile

   FROM scratch 1
   ADD manifests /manifests

   1

   Use the FROM scratch directive to make the size of the image smaller. No other files or directories are required in the bundle image.

2. Build an Open Container Initiative (OCI)-compliant image by using your preferred build tool, similar to the following example:

   $ podman build -f plainbundle.Dockerfile -t \
       quay.io/<organization_name>/<repository_name>:<image_tag> . 1

   1

   Use an image tag that references a repository where you have push access privileges.

3. Push the image to your remote registry by running the following command:

   $ podman push quay.io/<organization_name>/<repository_name>:<image_tag>

Procedure

1. Create a directory for the catalog by running the following command:

   $ mkdir <catalog_dir>

2. Generate a Dockerfile that can build a catalog image by running the opm generate dockerfile command in the same directory level as the previous step:

   $ opm generate dockerfile <catalog_dir> \
       -i registry.redhat.io/openshift4/ose-operator-registry:v4.14 1

   1

   Specify the official Red Hat base image by using the -i flag, otherwise the Dockerfile uses the default upstream image.

   Note

   The generated Dockerfile must be in the same parent directory as the catalog directory that you created in the previous step:

   Example directory structure

   .
   ├── <catalog_dir>
   └── <catalog_dir>.Dockerfile

3. Populate the catalog with the package definition for your extension by running the opm init command:

   $ opm init <extension_name> \
       --output json \
       > <catalog_dir>/index.json

   This command generates an olm.package declarative config blob in the specified catalog configuration file.

Procedure

1. Verify that the index.json or index.yaml file for your catalog is similar to the following example:

   Example <catalog_dir>/index.json file

   {
       {
        "schema": "olm.package",
        "name": "<extension_name>",
        "defaultChannel": ""
       }
   }

2. To create an olm.bundle blob, edit your index.json or index.yaml file, similar to the following example:

   Example <catalog_dir>/index.json file with olm.bundle blob

   {
      "schema": "olm.bundle",
       "name": "<extension_name>.v<version>",
       "package": "<extension_name>",
       "image": "quay.io/<organization_name>/<repository_name>:<image_tag>",
       "properties": [
           {
               "type": "olm.package",
               "value": {
               "packageName": "<extension_name>",
               "version": "<bundle_version>"
               }
           },
           {
               "type": "olm.bundle.mediatype",
               "value": "plain+v0"
           }
     ]
   }

3. To create an olm.channel blob, edit your index.json or index.yaml file, similar to the following example:

   Example <catalog_dir>/index.json file with olm.channel blob

   {
       "schema": "olm.channel",
       "name": "<desired_channel_name>",
       "package": "<extension_name>",
       "entries": [
           {
               "name": "<extension_name>.v<version>"
           }
       ]
   }

Verification

1. Open your index.json or index.yaml file and ensure it is similar to the following example:

   Example <catalog_dir>/index.json file

   {
       "schema": "olm.package",
       "name": "example-extension",
       "defaultChannel": "preview"
   }
   {
       "schema": "olm.bundle",
       "name": "example-extension.v0.0.1",
       "package": "example-extension",
       "image": "quay.io/example-org/example-extension-bundle:v0.0.1",
       "properties": [
           {
               "type": "olm.package",
               "value": {
               "packageName": "example-extension",
               "version": "0.0.1"
               }
           },
           {
               "type": "olm.bundle.mediatype",
               "value": "plain+v0"
           }
       ]
   }
   {
       "schema": "olm.channel",
       "name": "preview",
       "package": "example-extension",
       "entries": [
           {
               "name": "example-extension.v0.0.1"
           }
       ]
   }

2. Validate your catalog by running the following command:

   $ opm validate <catalog_dir>

Procedure

1. Build your file-based catalog as an image by running the following command:

   $ podman build -f <catalog_dir>.Dockerfile -t \
       quay.io/<organization_name>/<repository_name>:<image_tag> .

2. Push your catalog image by running the following command:

   $ podman push quay.io/<organization_name>/<repository_name>:<image_tag>