Migrate to a new basic template schema

A opm introduced a new breaking change and changed a basic template
schema. The schema produced by the fbc migration tool was no longer
supported and required a change.

This commit adapts to a new opm version and produce new basic template
schema. It also updates a onboarding doc to reflect a changes and does
couple of user improvements.

JIRA: ISV-5164

Signed-off-by: Ales Raszka <[email protected]>

Author: Allda

docs/img/release-info.png

@@ -30,7 +30,7 @@ wget https://raw.githubusercontent.com/redhat-openshift-ecosystem/operator-pipel
 Now we can convert existing operator into FBC. The initial run takes a while because
 a local cache is generated during a run.
 
-> [!NOTE]
+> **Note**
 > A user executing the conversion script needs to be authenticated to registries used by OLM catalog.
 > Use `podman login` to log in into all registries.
 
@@ -50,6 +50,7 @@ $ make fbc-onboarding
 > variable in the `Makefile` and include only versions supported by an operator.
 
 The Makefile will execute following steps:
+
  - Download dependencies needed for the migration (opm, fbc-onboarding CLI)
  - Fetch a list of currently supported OCP catalogs (this might take a while when doing it for the first time)
  - Transform existing catalogs into a basic template
@@ -97,7 +98,7 @@ catalogs
 Artifacts generated in the previous step need to be added to a git and submitted via pull request. The operator pipeline validates the content of the catalogs and releases changes into ocp catalogs.
 
 ```bash
-$ git add operators/aqua/{catalog-templates,ci.yaml}
+$ git add operators/aqua/{catalog-templates,ci.yaml,Makefile}
 
 $ git add catalogs/{v4.12,v4.13,v4.14,v4.15,v4.16}/aqua
 

docs/users/fbc_onboarding.md

@@ -15,7 +15,7 @@ fbc:
 
 ## FBC templates
 File-based catalog templates serve as a simplified view of a catalog that can be updated
-by the user. The OPM currently supports 3 types of templates and it is up to the user which
+by the user. The OPM currently supports 2 types of templates and it is up to the user which
 template the operator will be using.
 
 * Basic template
@@ -90,6 +90,8 @@ in the catalog yet. To add the bundle to the catalog you need to update catalog
 and add a bundle pullspec given by pull request comment and open a new pull request with catalog
 changes.
 
+![Release info](../img/release-info.png)
+
 #### SemVer
 For example if I want to add `v1.1.0` bundle into `Fast` channel of a specific catalog I'll
 add it as mentioned in the example below:
@@ -123,7 +125,7 @@ Stable:
   Bundles:
   - Image: quay.io/foo/olm:testoperator.v1.0.0
 ```
-Also see [opm doc](https://olm.operatorframework.io/docs/advanced-tasks/catalog-update-formulary/#fbc)
+Also see [opm doc](https://olm.operatorframework.io/docs/advanced-tasks/catalog-update-formulary/#semver)
 for automate-able step.
 
 #### Basic
@@ -135,29 +137,28 @@ add it as mentioned in the example below.
 
 ```yaml
 ---
-schema: olm.package
-name: example-operator
-defaultChannel: stable
-
----
-schema: olm.channel
-package: example-operator
-name: stable
+schema: olm.template.basic
 entries:
-- name: example-operator.v0.1.0
-- name: example-operator.v0.2.0 # <-- Add bundle into channel
-  replaces: example-operator.v0.1.0
-
----
-schema: olm.bundle
-image: docker.io/example/example-operator-bundle:0.1.0
-
----
-schema: olm.bundle # <-- Add new bundle entry
-image: docker.io/example-operator-bundle:0.2.0
+  - schema: olm.package
+    name: example-operator
+    defaultChannel: stable
+
+  - schema: olm.channel
+    package: example-operator
+    name: stable
+    entries:
+      - name: example-operator.v0.1.0
+      - name: example-operator.v0.2.0 # <-- Add bundle into channel
+        replaces: example-operator.v0.1.0
+
+  - schema: olm.bundle
+    image: docker.io/example/example-operator-bundle:0.1.0
+
+  - schema: olm.bundle # <-- Add new bundle entry
+    image: docker.io/example-operator-bundle:0.2.0
 ```
 
-Also see [opm doc](https://olm.operatorframework.io/docs/advanced-tasks/catalog-update-formulary/#semver)
+Also see [opm doc](https://olm.operatorframework.io/docs/advanced-tasks/catalog-update-formulary/#fbc)
 for automate-able step.
 
 ### Updating existing catalogs

docs/users/fbc_workflow.md

@@ -4,7 +4,7 @@
 import logging
 import os
 import sys
-from typing import Any, List
+from typing import Any, Dict, Optional
 
 import requests
 import yaml
@@ -118,7 +118,9 @@ def build_cache(version: str, image: str, cache_dir: str) -> None:
         f.write(catalog)
 
 
-def get_base_template_from_catalog(operator_name: str, catalog: Any) -> List[Any]:
+def get_base_template_from_catalog(
+    operator_name: str, catalog: Any
+) -> Optional[Dict[str, Any]]:
     """
     Generate a basic template from file based catalog. The function filters
     out operator from a catalog and removes unnecessary fields and
@@ -129,33 +131,30 @@ def get_base_template_from_catalog(operator_name: str, catalog: Any) -> List[Any
         catalog (Any): A file based catalog with all operators
 
     Returns:
-        List[Any]: List of basic template items for a given operator
+        Optional[Dict[str, Any]]: A basic template for the operator.
+        In case an operator is not present in a catalog, None is returned
     """
     # Filter out the operator items from the catalog
     # Items can be identified by the name or package field
-    operator_items = list(
-        filter(
-            lambda x: x.get("name") == operator_name
-            or x.get("package") == operator_name,
-            catalog,
-        )
-    )
-
-    # Keep only the non-bundle items - packages, channels, etc.
-    non_bundles = list(
-        filter(lambda x: x.get("schema") != "olm.bundle", operator_items)
+    operator_items = (
+        item
+        for item in catalog
+        if item.get("name") == operator_name or item.get("package") == operator_name
     )
 
-    bundles = list(filter(lambda x: x.get("schema") == "olm.bundle", operator_items))
+    entries = []
 
-    # Keep only image and schema fields - rest can be extracted from the image
-    # when rendering the template
-    bundles = [
-        {"schema": bundle.get("schema"), "image": bundle.get("image")}
-        for bundle in bundles
-    ]
-
-    return non_bundles + bundles
+    for item in operator_items:
+        if item.get("schema") == "olm.bundle":
+            # Keep only image and schema fields - rest can be extracted from the image
+            # when rendering the template
+            entries.append({"schema": item["schema"], "image": item["image"]})
+        else:
+            # Keep only the non-bundle items - packages, channels, etc.
+            entries.append(item)
+    if not entries:
+        return None
+    return {"schema": "olm.template.basic", "entries": entries}
 
 
 def create_catalog_template_dir_if_not_exists(operator: Any) -> str:
@@ -182,7 +181,7 @@ def create_catalog_template_dir_if_not_exists(operator: Any) -> str:
 
 def generate_and_save_base_templates(
     version: str, operator_name: str, cache_dir: str, template_dir: str
-) -> List[Any]:
+) -> Optional[Dict[str, Any]]:
     """
     Generate and save basic templates for a given operator and version
 
@@ -193,7 +192,8 @@ def generate_and_save_base_templates(
         template_dir (str): A directory where the templates will be stored
 
     Returns:
-        List[Any]: List of basic template items for a given operator
+        Optional[Dict[str, Any]]: A basic template for the operator.
+        In case an operator is not present in a catalog, None is returned
     """
     with open(os.path.join(cache_dir, f"{version}.yaml"), "r", encoding="utf8") as f:
         catalog = yaml.safe_load_all(f)
@@ -206,7 +206,7 @@ def generate_and_save_base_templates(
 
     template_path = os.path.join(template_dir, f"v{version}.yaml")
     with open(template_path, "w", encoding="utf8") as f:
-        yaml.safe_dump_all(basic_template, f, explicit_start=True, indent=2)
+        yaml.safe_dump(basic_template, f, explicit_start=True, indent=2)
 
     LOGGER.info("Template for %s saved to %s", version, template_path)
     return basic_template
@@ -282,8 +282,9 @@ def onboard_operator_to_fbc(
     """
     organization = repository.config.get("organization")
     supported_catalogs = get_supported_catalogs(organization, stage)
-    supported_versions = [catalog.get("ocp_version") for catalog in supported_catalogs]
-
+    supported_versions = sorted(
+        [catalog.get("ocp_version") for catalog in supported_catalogs]
+    )
     LOGGER.info(
         "Generating FBC templates for following versions: %s", supported_versions
     )

operator-pipeline-images/operatorcert/entrypoints/fbc_onboarding.py

@@ -100,10 +100,16 @@ def test_get_base_template_from_catalog() -> None:
 
     result = fbc_onboarding.get_base_template_from_catalog("pkg1", catalog)
 
-    assert result == [
-        {"package": "pkg1", "schema": "olm.channel"},
-        {"schema": "olm.bundle", "image": "img1"},
-    ]
+    assert result == {
+        "schema": "olm.template.basic",
+        "entries": [
+            {"schema": "olm.bundle", "image": "img1"},
+            {"package": "pkg1", "schema": "olm.channel"},
+        ],
+    }
+
+    result = fbc_onboarding.get_base_template_from_catalog("pkg3", catalog)
+    assert result is None
 
 
 @patch("builtins.input")
@@ -128,13 +134,13 @@ def test_create_catalog_template_dir_if_not_exists(
 
 
 @patch("operatorcert.entrypoints.fbc_onboarding.get_base_template_from_catalog")
-@patch("operatorcert.entrypoints.fbc_onboarding.yaml.safe_dump_all")
+@patch("operatorcert.entrypoints.fbc_onboarding.yaml.safe_dump")
 @patch("operatorcert.entrypoints.fbc_onboarding.yaml.safe_load_all")
 def test_generate_and_save_base_templates(
     mock_yaml_load: MagicMock, mock_yaml_dump: MagicMock, mock_template: MagicMock
 ) -> None:
     mock_yaml_load.return_value = []
-    mock_template.return_value = [{}]
+    mock_template.return_value = {"schema": "olm.template.basic"}
 
     with mock.patch("builtins.open", mock.mock_open()) as mock_open:
         resp = fbc_onboarding.generate_and_save_base_templates(
@@ -146,7 +152,7 @@ def test_generate_and_save_base_templates(
 
 
 @patch("operatorcert.entrypoints.fbc_onboarding.get_base_template_from_catalog")
-@patch("operatorcert.entrypoints.fbc_onboarding.yaml.safe_dump_all")
+@patch("operatorcert.entrypoints.fbc_onboarding.yaml.safe_dump")
 @patch("operatorcert.entrypoints.fbc_onboarding.yaml.safe_load_all")
 def test_generate_and_save_base_templates_no_content(
     mock_yaml_load: MagicMock, mock_yaml_dump: MagicMock, mock_template: MagicMock