Chapter 22. Running the certification suite with Red Hat hosted pipeline

Find your operator folder in the operators directory. Place the contents of your operator bundle in this directory.

If the newly certifying operator does not have a subdirectory already under the operator’s parent directory then you have to create one.

Create a new directory under operators. The name of this directory should match your operator’s package name. For example, my-operator.

Recommended directory structure

The following example illustrates the recommended directory structure.

├── config.yaml
├── operators
    └── my-operator
        ├── v1.4.8
        │   ├── manifests
        │   │   ├── cache.example.com_my-operators.yaml
        │   │   ├── my-operator-controller-manager-metrics-service_v1_service.yaml
        │   │   ├── my-operator-manager-config_v1_configmap.yaml
        │   │   ├── my-operator-metrics-reader_rbac.authorization.k8s.io_v1_clusterrole.yaml
        │   │   └── my-operator.clusterserviceversion.yaml
        │   └── metadata
        │       └── annotations.yaml
        └── ci.yaml

You should convert your operator to the FBC format before submitting it through the certification workflow. The onboarding process uses automation to simplify the conversion from a bundle-based format to FBC.

cd <operator-repo>/operators/<operator-name>

Operator directory:

$ tree .

operators/aqua
├── 0.0.1
...
├── catalog-templates
│   ├── v4.12.yaml
│   ├── v4.13.yaml
│   ├── v4.14.yaml
│   ├── v4.15.yaml
│   └── v4.16.yaml
├── ci.yaml

FBC catalog directory:

To view the catalog directory structure created by the FBC onboarding process, first navigate to the root of your forked repository:

$ cd ../..

Then run:

$ tree (repository root)/catalogs

This will display the structure under the catalogs/ directory. For example:

catalogs
├── v4.12
│   └── aqua
│       └── catalog.yaml
├── v4.13
│   └── aqua
│       └── catalog.yaml
├── v4.14
│   └── aqua
│       └── catalog.yaml
├── v4.15
│   └── aqua
│       └── catalog.yaml
└── v4.16
    └── aqua
        └── catalog.yaml

After completing the onboarding and validation, add the generated resources to your Git repository and submit them through a pull request.

$ git add operators/aqua/{catalog-templates,ci.yaml,Makefile}

$ git add catalogs/{v4.12,v4.13,v4.14,v4.15,v4.16}/aqua

$ git commit --signoff -m "Add FBC resources for aqua operator"

When you merge the pull request, the operator pipeline will validate and publish the FBC content to the appropriate OpenShift catalogs.

To use the FBC workflow, update the ci.yaml file in your operator repository by adding the following field:

fbc:
  enabled: true

This tells the certification pipeline to use the FBC workflow to generate and update catalogs.

File-Based catalog templates provide a simplified, user-editable view of an OpenShift catalog. The Operator Package Manager (OPM) currently supports two types of templates. You can select the template that best fits your operator’s release strategy:

Red Hat recommends using olm.semver for improved automation.

For details about the template schema, see Operator Framework documentation.

To generate catalogs from templates, you need to provide a mapping between the template and the catalog in the ci.yaml file. Depending on your needs, you can map a template either with 1:N mapping or 1:1 mapping

1:N mapping example

---
fbc:
  enabled: true
  catalog_mapping:
    - template_name: my-custom-semver-template.yaml # The name of the file inside ./catalog-templates directory
      catalogs_names: # a list of catalogs within the /catalogs directory
        - "v4.15"
        - "v4.16"
        - "v4.17"
      type: olm.semver
    - template_name: my-custom-basic-template.yaml # The name of the file inside catalog-templates directory
      catalogs_names:
        - "v4.12"
        - "v4.13"
      type: olm.template.basic

1:1 mapping example

---
fbc:
  enabled: true
  catalog_mapping:
  - template_name: v4.14.yaml
    catalog_names: ["v4.14"]
    type: olm.template.basic
  - template_name: v4.15.yaml
    catalog_names: ["v4.15"]
    type: olm.template.basic
  - template_name: v4.16.yaml
    catalog_names: ["v4.16"]
    type: olm.template.basic
  - template_name: v4.17.yaml
    catalog_names: ["v4.17"]
    type: olm.template.basic

Use the provided Makefile to simplify catalog generation from templates. It automates the process by running the appropriate opm commands for each template type.

If you followed the onboarding process for a new or converted operator, your operator repository should already include the Makefile.

Make sure it is available in the root directory of your operator component:

.
├── 0.0.1/
│   ├── release-config.yaml
│   ├── manifests/
│   └── metadata/
├── catalog-templates/
├── ci.yaml
└── Makefile

Run the following command to generate FBC catalog files for each supported OpenShift version:

make catalogs

This command processes your catalog templates and creates structured catalog files in the catalogs/ directory. After generation, submit the updated catalog files through a pull request. When you merge the changes, the operator pipeline publishes the updates to the OpenShift Container Platform index.

Example output structure:

catalogs/
├── v4.12/
│   └── aqua/
│       └── catalog.yaml
├── v4.13/
│   └── aqua/
│       └── catalog.yaml
├── v4.14/
│   └── aqua/
│       └── catalog.yaml
├── v4.15/
│   └── aqua/
│       └── catalog.yaml
└── v4.16/
    └── aqua/
        └── catalog.yaml

Add a new operator bundle to the catalog by using two methods:

One of the key advantages of the File-Based Catalog format is that it allows you to modify an operator’s update graph after releasing the bundle. This flexibility enables you to:

After updating the catalog templates, run make catalogs to generate the updated catalog. Then, submit the generated files through the standard pull request workflow.

The standard FBC release workflow includes two steps:

You can now automate the second step by using the auto-release feature. Enable the auto-release feature to automatically update the catalog.

After you submit a pull request that includes both the new bundle and the release-config.yaml file, the release pipeline takes care of the rest. It creates and merges a follow-up pull request that contains the necessary catalog changes. Here’s an example of an auto-generated catalog PR.".

To enable the automatic release of your operator bundle to OpenShift Container Platform (OCP) catalogs in FBC mode, add a release-config.yaml file in the corresponding bundle version directory. For example, operators/aqua/0.0.2/release-config.yaml.

tree operators/aqua
.
├── 0.0.2
│   ├── release-config.yaml # This is the file
│   ├── manifests
│   └── metadata
├── catalog-templates
├── ci.yaml
└── Makefile

The release-config.yaml file defines where the new bundle will be released—specifically, which catalog templates to update and how the bundle fits into the update graph.

Example

---
catalog_templates:
  - template_name: basic.yaml
    channels: [my-channel]
    replaces: aqua.0.0.1
  - template_name: semver.yaml
    channels: [Fast, Stable]

In this example:

The structure of the release-config.yaml file is validated automatically during the pipeline run. If the file does not conform to the schema, the pull request will fail with a detailed error message.

The file must use the following structure:

For more information, see release-config.yaml schema documentation.