FBC Template Demo Design

--- tags: fbc  --- # FBC Template Demo Design [< previously: how we got to veneers](https://hackmd.io/ay3yn4UMTUSPM93KUdToKg) ## Background and Goals Leveraging [these basic veneer concepts](https://hackmd.io/J6PQYDnLTfqYGLWpOs44aQ), we apply github automation actions to facilitate composition of catalogs-of-catalogs from individual operator author catalogs to keep things as simple and transparent as possible. This reduces the bar to entry as well as re-approachability of the catalog later for maintenance purposes. We presume that the reader is already familiar with [operators](https://docs.okd.io/4.10/operators/understanding/olm-what-operators-are.html), [bundle format and bundle manifests](https://docs.okd.io/4.10/operators/understanding/olm-packaging-format.html), and [creating a catalog of operators](https://olm.operatorframework.io/docs/tasks/creating-a-catalog/). This demo is intended to be a basic implementation of the proposed `phase 2` workflows to process a single operator catalog template and submit it to a collection of operator catalogs. ## Terms - [`File-Based Catalog`](https://olm.operatorframework.io/docs/reference/file-based-catalogs/) (FBC) is the declarative expression of operators and their relationships with other operators, other versions of themselves. - [`Catalog Templates`](https://olm.operatorframework.io/docs/reference/catalog-templates/) are a general class of objects which can provide a simplified interaction with FBC. Examples of `opm`-supported templates are [`basic`](https://olm.operatorframework.io/docs/reference/catalog-templates/#basic-veneer) and [`semver`](https://olm.operatorframework.io/docs/reference/catalog-templates/#semver-veneer) - `Operator Author` is the role related to expressing an individual operator versions, channels, properties, etc. in a destination catalog. - `Catalog` is the destination FBC-based catalog composed of the FBC contributions of one or more operators, capable of serving as a Catalog Source - `Catalog Owner` is the role related to integrating Operator Authors' catalog contributions. - `Catalog Contribution` is the FBC that an Operator Author needs to convey to the Catalog Owner. The format needs to be negotiated with the Catalog Owner. For this example, the Catalog Owner receives contributions of a single, unversioned directory named after the operator which contain all FBC files ## Ecosystem high-level use-cases #### Each use-case is modeled by a ready-to-fork GitHub repository. 1 - Operator Author generating a Catalog Contribution [repository link](https://github.com/operator-framework/example-operator-index) 2 - Catalog Owner integrating a Catalog Contribution [repository link](https://github.com/operator-framework/cool-catalog/) ### Operator Author generating a Catalog Contribution: ##### ```mermaid %%{init: {'securityLevel': 'strict', 'theme':'forest'}}%% sequenceDiagram autonumber participant User participant LocalRepo participant RemoteRepo participant GHAction participant CatalogRepo activate User activate RemoteRepo User-->RemoteRepo: fork and clone repository activate LocalRepo User->>LocalRepo: update CI destination LocalRepo->>RemoteRepo: push CI changes to remote activate RemoteRepo User->>LocalRepo: update 'catalog' target LocalRepo->>RemoteRepo: push changes to remote deactivate LocalRepo deactivate User RemoteRepo--xGHAction: <<push trigger> deactivate RemoteRepo activate GHAction GHAction->>GHAction: Generate FBC from 'catalog' target GHAction->>GHAction: validate FBC activate CatalogRepo GHAction->>CatalogRepo: Open PR in catalog destination deactivate GHAction deactivate CatalogRepo ``` ### Catalog Owner integrating a Catalog Contribution: ##### ```mermaid %%{init: {'securityLevel': 'strict', 'theme':'forest'}}%% sequenceDiagram autonumber participant CatalogOwner participant Catalog participant GHAction participant ImageRepo CatalogOwner--xCatalog: fork repo CatalogOwner--xCatalog: adjust CI CatalogOwner--xCatalog: push updates to remote CatalogOwner->>+Catalog: Approves PR, merges (auto-merge trivial case) activate CatalogOwner activate Catalog Catalog->>+GHAction: Integrate contribution to catalog activate GHAction GHAction->>GHAction: validate contribution's Operator Author GHAction->>GHAction: generate image contiaining updated catalog GHAction->>GHAction: validate catalog in image GHAction->>+ ImageRepo: push catalog image to repo activate ImageRepo deactivate ImageRepo deactivate GHAction deactivate Catalog deactivate CatalogOwner ```  ## Role in the Pipeline Ecosystem These interactions are also reflected in the pipeline ecosystem document [here](https://miro.com/app/board/uXjVOKt-AZY=/?moveToWidget=3458764531007885900&cot=14) as a contributor to the overall flow.