Make FBC method a default in documentation

The documentation is updated to reflect FBC changes and suggest using FBC for all operators. Hopefully this will increase an adoption of the FBC method. JIRA: ISV-5377 Signed-off-by: Ales Raszka <[email protected]>
redhat-openshift-ecosystem · Nov 12, 2024 · 8d6e1f9 · 8d6e1f9
1 parent 5d522eb
commit 8d6e1f9
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 15 deletions.
diff --git a/docs/users/contributing-via-pr.md b/docs/users/contributing-via-pr.md
@@ -8,8 +8,8 @@ To submit an operator one has to do these steps
     - operators
 1. Configure `ci.yaml` file. [More info](./operator-ci-yaml.md)
     - Setup reviewers
-    - Operator versioning strategy
-1. Make a pull request
+    - Enable FBC mode
+1. Make a pull request with a new operator bundle or catalog changes
 1. Verify tests and fix problems, if possible
 1. Ask for help in the PR in case of problems
 
@@ -33,8 +33,8 @@ In case of failures, please have a look at the logs of specific tests. If an err
 ## Useful commands interacting with the pipeline
 You can post the following comment/command:
 
-Command | Functionality |
---- | --- |
-`/pipeline restart operator-hosted-pipeline` | The hosted pipeline will be re-triggered and PR will be merged if possible. |
-`/pipeline restart operator-release-pipeline` | The release pipeline will be re-triggered.
-`/test skip {test_case_name}` | *test_case_name* test will be skipped. Please consider that only a subset of tests (*currently only pruned graph test*) can be skipped.
+| Command                                       | Functionality                                                                                                                           |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `/pipeline restart operator-hosted-pipeline`  | The hosted pipeline will be re-triggered and PR will be merged if possible. The command only works if a previous pipeline failed.       |
+| `/pipeline restart operator-release-pipeline` | The release pipeline will be re-triggered. The command only works if a previous pipeline failed.                                        |
+| `/test skip {test_case_name}`                 | *test_case_name* test will be skipped. Please consider that only a subset of tests (*currently only pruned graph test*) can be skipped. |
diff --git a/docs/users/contributing-where-to.md b/docs/users/contributing-where-to.md
@@ -18,15 +18,23 @@ Once you have forked the upstream repo, you will require to add your Operator Bu
 │       │   └── tests
 │       │       └── scorecard
 │       │           └── config.yaml
-│       └── ci.yaml
+│       ├── catalog-templates
+│       │   ├── v4.14.yaml
+│       │   ├── v4.15.yaml
+│       │   └── v4.16.yaml
+│       ├── ci.yaml
+│       └── Makefile
 └── README.md
 ```
 
 Follow the `operators` directory in the forked repo. Add your Operator Bundle under this `operators` directory following the example format.
+
 1. Under the `operators` directory, create a new directory with the name of your operator.
-1. Inside of this newly created directory add your `ci.yaml`.
-1. Also, under the new directory create a subdirectory for each version of your Operator.
-1. In each version directory there should be a `manifests/` directory containing your OpenShift yaml files, a `metadata/` directory containing your `annotations.yaml` file, and a `tests/` directory containing the required `config.yaml` file for the preflight tests.
+2. Inside of this newly created directory add your `ci.yaml` and set its content based on [doc](./operator-ci-yaml.md).
+3. Also, under the new directory create a subdirectory for each version of your Operator.
+4. In each version directory there should be a `manifests/` directory containing your OpenShift yaml files, a `metadata/` directory containing your `annotations.yaml` file, and a `tests/` directory containing the required `config.yaml` file for the preflight tests.
+5. Create a `catalog-templates/` directory under the operator directory and add a yaml file for each OpenShift version you want to support. The yaml file should contain the catalog template for the operator. More information on how to create the catalog template can be found [here](./fbc_workflow.md).
+6. Download the template `Makefile` from [here](https://raw.githubusercontent.com/redhat-openshift-ecosystem/operator-pipelines/main/fbc/Makefile) and place it in the root of the operator directory.
 
 >**Note** To learn more about preflight tests please follow this [link](https://github.com/redhat-openshift-ecosystem/openshift-preflight?tab=readme-ov-file#preflight).
 

diff --git a/docs/users/fbc_workflow.md b/docs/users/fbc_workflow.md
@@ -85,13 +85,17 @@ catalogs
 ### Adding new bundle to Catalog
 To add a bundle to the catalog you need to first submit the new version of the operator
 using traditional [PR workflow](./contributing-via-pr.md). The operator pipeline builds,
-tests, and releases the bundle into the registry. At this point, the operator is not available
-in the catalog yet. To add the bundle to the catalog you need to update catalog templates
+tests, and releases the bundle into the registry. **At this point, the operator is not available
+in the catalog yet.** To add the bundle to the catalog you need to update catalog templates
 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)
 
+> [!NOTE]
+> Currently a workflow requires a 2-step process to release a new bundle into the catalog. In the first step, the operator bundle is released and in the second step, the catalog is updated with the new bundle.
+> We are working on a solution to automate this process and make it a single step. However, this will require a usage of `SemVer` catalog template. In case you would like to use this feature once available please consider using `SemVer` template.
+
 #### 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:

diff --git a/docs/users/operator-ci-yaml.md b/docs/users/operator-ci-yaml.md
@@ -1,6 +1,9 @@
 # Operator Publishing / Review settings
 
-Each operator might have `ci.yaml` configuration file to be present in an operator directory (for example `operators/aqua/ci.yaml`). This configuration file is used by [community-operators](https://github.com/redhat-openshift-ecosystem/community-operators-prod) pipeline to setup various features like `reviewers` or `operator versioning`.
+Each operator might have `ci.yaml` configuration file to be present in an operator directory (for example `operators/aqua/ci.yaml`). This configuration file is used by the pipeline automation to control a way how the operator will be published and reviewed.
+
+A content of the file depends on the operator source type. There are a different set of options for community operators and certified operators.
+
 
 > **Note:**
     One can create or modify `ci.yaml` file with a new operator version. This operation can be done in the same PR with other operator changes.
@@ -21,7 +24,7 @@ If you want to accelerate publishing your changes, consider adding yourself and
 For this to work, it is required to setup reviewers in `ci.yaml` file. It can be done by adding `reviewers` tag with a list of GitHub usernames. For example
 
 ### Example
-```
+```yaml
 $ cat <path-to-operator>/ci.yaml
 ---
 reviewers:
@@ -30,7 +33,30 @@ reviewers:
 
 ```
 
+## FBC mode
+
+### `fbc.enabled`
+The `fbc.enabled` flag enables the [File-Based catalog](./fbc_workflow.md) feature. It is highly recommended to use the FBC mode in order to have better control over the operator's catalog.
+
+### `fbc.version_promotion_strategy`
+The `fbc.version_promotion_strategy` option defines the strategy for promoting the operator into a next OCP version. When a new OCP version becomes available an automated process will promote the operator from a version N to a version N+1. The `fbc.version_promotion_strategy` option can have the following values:
+
+- `never` - the operator will not be promoted to the next OCP version automatically (default)
+- `always` - the operator will be promoted to the next OCP version automatically
+- `review-needed` - the operator will be promoted to the next OCP version automatically, but the PR will be created and the reviewers will be asked to review the changes
+
+### Example
+```yaml
+---
+fbc:
+    enabled: true
+    version_promotion_strategy: never
+```
+
+
 ## Operator versioning
+> **_NOTE:_** This option is only available for the non-FBC operators where user doesn't have a direct control over the catalog.
+
 Operators have multiple versions. When a new version is released, OLM can update an operator automatically. There are 2 update strategies possible, which are defined in `ci.yaml` at the operator top level.
 
 ### replaces-mode
@@ -50,6 +76,11 @@ $ cat <path-to-operator>/ci.yaml
 updateGraph: replaces-mode
 ```
 
+## Certification project
+
+### `cert_project_id`
+The `cert_project_id` option is required for certified and marketplace operators. It is used to link the operator to the certification project in Red Hat Connect.
+
 ## Kubernetes max version in CSV
 
 Starting from kubernetes 1.22 some old APIs were deprecated ([Deprecated API Migration Guide from v1.22](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22). Users can set `operatorhub.io/ui-metadata-max-k8s-version: "<version>"` in its CSV file to inform its maximum supported Kubernetes version. The following example will inform that operator can handle `1.21` as maximum Kubernetes version