Chapter 4. Catalogs

1. Maintain a single configuration file for the catalog, containing image references for each Operator in the catalog:

   Example catalog configuration file

   name: community-operators
   repo: quay.io/community-operators/catalog
   tag: latest
   references:
   - name: etcd-operator
     image: quay.io/etcd-operator/index@sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
   - name: prometheus-operator
     image: quay.io/prometheus-operator/index@sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317

   Copy to Clipboard Toggle word wrap

2. Run a script that parses the configuration file and creates a new catalog from its references:

   Example script

   name=$(yq eval '.name' catalog.yaml)
   mkdir "$name"
   yq eval '.name + "/" + .references[].name' catalog.yaml | xargs mkdir
   for l in $(yq e '.name as $catalog | .references[] | .image + "|" + $catalog + "/" + .name + "/index.yaml"' catalog.yaml); do
     image=$(echo $l | cut -d'|' -f1)
     file=$(echo $l | cut -d'|' -f2)
     opm render "$image" > "$file"
   done
   opm generate dockerfile "$name"
   indexImage=$(yq eval '.repo + ":" + .tag' catalog.yaml)
   docker build -t "$indexImage" -f "$name.Dockerfile" .
   docker push "$indexImage"

   Copy to Clipboard Toggle word wrap

Procedure

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

   Example my-redhat-operators.yaml file

   apiVersion: olm.operatorframework.io/v1
   kind: ClusterCatalog
   metadata:
     name: my-redhat-operators 

   1

   
   spec:
     priority: 1000 

   2

   
     source:
       image:
         pollIntervalMinutes: 10 

   3

   
         ref: registry.redhat.io/redhat/community-operator-index:v4.18 

   4

   
       type: Image

   Copy to Clipboard Toggle word wrap

   1

   The catalog is automatically labeled with the value of the metadata.name field when it is applied to the cluster. For more information about labels and catalog selection, see "Catalog content resolution".

   2

   Optional: Specify the priority of the catalog in relation to the other catalogs on the cluster. For more information, see "Catalog selection by priority".

   3

   Specify the interval in minutes for polling the remote registry for newer image digests. To disable polling, do not set the field.

   4

   Specify the catalog image in the spec.source.image.ref field.

2. Add the catalog to your cluster by running the following command:

   $ oc apply -f my-redhat-operators.yaml

   Copy to Clipboard Toggle word wrap

   Example output

   clustercatalog.olm.operatorframework.io/my-redhat-operators created

   Copy to Clipboard Toggle word wrap

Procedure

1. Initialize the catalog:

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

      $ mkdir <catalog_dir>

      Copy to Clipboard Toggle word wrap

   2. Generate a Dockerfile that can build a catalog image by running the opm generate dockerfile command:

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

      1

      Copy to Clipboard Toggle word wrap

      1

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

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

      Example directory structure

      . 

      1

      
      ├── <catalog_dir> 

      2

      
      └── <catalog_dir>.Dockerfile 

      3

      Copy to Clipboard Toggle word wrap

      1

      Parent directory

      2

      Catalog directory

      3

      Dockerfile generated by the opm generate dockerfile command

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

      $ opm init <operator_name> \ 

      1

      
          --default-channel=preview \ 

      2

      
          --description=./README.md \ 

      3

      
          --icon=./operator-icon.svg \ 

      4

      
          --output yaml \ 

      5

      
          > <catalog_dir>/index.yaml 

      6

      Copy to Clipboard Toggle word wrap

      1

      Operator, or package, name

      2

      Channel that subscriptions default to if unspecified

      3

      Path to the Operator’s README.md or other documentation

      4

      Path to the Operator’s icon

      5

      Output format: JSON or YAML

      6

      Path for creating the catalog configuration file

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

2. Add a bundle to the catalog by running the opm render command:

   $ opm render <registry>/<namespace>/<bundle_image_name>:<tag> \ 

   1

   
       --output=yaml \
       >> <catalog_dir>/index.yaml 

   2

   Copy to Clipboard Toggle word wrap

   1

   Pull spec for the bundle image

   2

   Path to the catalog configuration file

   Note

   Channels must contain at least one bundle.

3. Add a channel entry for the bundle. For example, modify the following example to your specifications, and add it to your <catalog_dir>/index.yaml file:

   Example channel entry

   ---
   schema: olm.channel
   package: <operator_name>
   name: preview
   entries:
     - name: <operator_name>.v0.1.0 

   1

   Copy to Clipboard Toggle word wrap

   1

   Ensure that you include the period (.) after <operator_name> but before the v in the version. Otherwise, the entry fails to pass the opm validate command.

4. Validate the file-based catalog:

   1. Run the opm validate command against the catalog directory:

      $ opm validate <catalog_dir>

      Copy to Clipboard Toggle word wrap

   2. Check that the error code is 0:

      $ echo $?

      Copy to Clipboard Toggle word wrap

      Example output

      0

      Copy to Clipboard Toggle word wrap

5. Build the catalog image by running the podman build command:

   $ podman build . \
       -f <catalog_dir>.Dockerfile \
       -t <registry>/<namespace>/<catalog_image_name>:<tag>

   Copy to Clipboard Toggle word wrap

6. Push the catalog image to a registry:

   1. If required, authenticate with your target registry by running the podman login command:

      $ podman login <registry>

      Copy to Clipboard Toggle word wrap

   2. Push the catalog image by running the podman push command:

      $ podman push <registry>/<namespace>/<catalog_image_name>:<tag>

      Copy to Clipboard Toggle word wrap

Procedure

1. Extract the contents of the catalog image in YAML format to an index.yaml file in your catalog directory:

   $ opm render <registry>/<namespace>/<catalog_image_name>:<tag> \
       -o yaml > <catalog_dir>/index.yaml

   Copy to Clipboard Toggle word wrap
   Note

   Alternatively, you can use the -o json flag to output in JSON format.

2. Modify the contents of the resulting index.yaml file to your specifications:

   Important

   After a bundle has been published in a catalog, assume that one of your users has installed it. Ensure that all previously published bundles in a catalog have an update path to the current or newer channel head to avoid stranding users that have that version installed.

   • To add an Operator, follow the steps for creating package, bundle, and channel entries in the "Creating a file-based catalog image" procedure.

   • To remove an Operator, delete the set of olm.package, olm.channel, and olm.bundle blobs that relate to the package. The following example shows a set that must be deleted to remove the example-operator package from the catalog:

     Example 4.9. Example removed entries

     ---
     defaultChannel: release-2.7
     icon:
       base64data: <base64_string>
       mediatype: image/svg+xml
     name: example-operator
     schema: olm.package
     ---
     entries:
     - name: example-operator.v2.7.0
       skipRange: '>=2.6.0 <2.7.0'
     - name: example-operator.v2.7.1
       replaces: example-operator.v2.7.0
       skipRange: '>=2.6.0 <2.7.1'
     - name: example-operator.v2.7.2
       replaces: example-operator.v2.7.1
       skipRange: '>=2.6.0 <2.7.2'
     - name: example-operator.v2.7.3
       replaces: example-operator.v2.7.2
       skipRange: '>=2.6.0 <2.7.3'
     - name: example-operator.v2.7.4
       replaces: example-operator.v2.7.3
       skipRange: '>=2.6.0 <2.7.4'
     name: release-2.7
     package: example-operator
     schema: olm.channel
     ---
     image: example.com/example-inc/example-operator-bundle@sha256:<digest>
     name: example-operator.v2.7.0
     package: example-operator
     properties:
     - type: olm.gvk
       value:
         group: example-group.example.io
         kind: MyObject
         version: v1alpha1
     - type: olm.gvk
       value:
         group: example-group.example.io
         kind: MyOtherObject
         version: v1beta1
     - type: olm.package
       value:
         packageName: example-operator
         version: 2.7.0
     - type: olm.bundle.object
       value:
         data: <base64_string>
     - type: olm.bundle.object
       value:
         data: <base64_string>
     relatedImages:
     - image: example.com/example-inc/example-related-image@sha256:<digest>
       name: example-related-image
     schema: olm.bundle
     ---

     Copy to Clipboard Toggle word wrap
   • To add or update deprecation messages for an Operator, ensure there is a deprecations.yaml file in the same directory as the package’s index.yaml file. For information on the deprecations.yaml file format, see "olm.deprecations schema".
3. Save your changes.

4. Validate the catalog:

   $ opm validate <catalog_dir>

   Copy to Clipboard Toggle word wrap

5. Rebuild the catalog:

   $ podman build . \
       -f <catalog_dir>.Dockerfile \
       -t <registry>/<namespace>/<catalog_image_name>:<tag>

   Copy to Clipboard Toggle word wrap

6. Push the updated catalog image to a registry:

   $ podman push <registry>/<namespace>/<catalog_image_name>:<tag>

   Copy to Clipboard Toggle word wrap

Verification

1. In the web console, navigate to the OperatorHub configuration resource in the Administration Cluster Settings Configuration page.

2. Add the catalog source or update the existing catalog source to use the pull spec for your updated catalog image.

   For more information, see "Adding a catalog source to a cluster" in the "Additional resources" of this section.

3. After the catalog source is in a READY state, navigate to the Operators OperatorHub page and check that the changes you made are reflected in the list of Operators.