[ISV-3905] Update user documentation describing the new contribution …

…workflow. (#3724) * [ISV-3905] Add the documentation for new community operator pipeline workflow. * Update the documentation regarding the testing and publishing the operator. * Replace the old data with the updated details in the documentation.
redhat-openshift-ecosystem · Dec 15, 2023 · ce4d7ea · ce4d7ea
1 parent 4e13cf9
commit ce4d7ea
Show file tree

Hide file tree

Showing 17 changed files with 787 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -9,9 +9,24 @@ This repo is the canonical source for Kubernetes Operators that appear on [OpenS
 consumed by Openshift and OKD to create their sources and built their catalog. To know more about how
 Openshift catalog are built see the [documentation](https://docs.openshift.com/container-platform/4.6/operators/understanding/olm-rh-catalogs.html#olm-rh-catalogs_olm-rh-catalogs).
 
-## Documentation
+## Add your Operator
 
-Full documentation is generated via [mkdoc](https://www.mkdocs.org/) and is located at [https://redhat-openshift-ecosystem.github.io/community-operators-prod/](https://redhat-openshift-ecosystem.github.io/community-operators-prod/)
+We would love to see your Operator added to this collection. We currently use automated vetting via continuous integration plus manual review to curate a list of high-quality, well-documented Operators. If you are new to Kubernetes Operators start [here](https://sdk.operatorframework.io/build/).
+
+If you have an existing Operator read our contribution guidelines on how to [package](docs/packaging-operator.md). Then the community operator pipeline will be triggered to test your Operator and merge a Pull Request.
+
+## Contributing Guide
+
+- [Prerequisites](docs/contributing-prerequisites.md)
+- [Where to place operator](docs/contributing-where-to.md)
+- [Creating pull request (PR)](docs/contributing-via-pr.md)
+- [Accepted Bundle Format](docs/accepted_bundle_formats.md)
+- [Operator Publishing / Review settings](docs/operator-ci-yaml.md)
+- [OKD/OpenShift Catalogs criteria and options](docs/packaging-required-criteria-ocp.md)
+
+## Test and release process for the Operator
+
+Refer to the [Community operator pipeline documentation](docs/community-operator-pipeline.md) .
 
 ## IMPORTANT NOTICE
 

diff --git a/docs/accepted_bundle_formats.md b/docs/accepted_bundle_formats.md
diff --git a/docs/best-practices.md b/docs/best-practices.md
@@ -0,0 +1,6 @@
+# Operator Best Practices
+
+Check the sections Best Practices for OLM and SDK projects to know more about its best practices and common recommendations, suggestions and conventions, see:
+
+- [SDK best practices](https://sdk.operatorframework.io/docs/best-practices/)
+- [OLM best practices](https://olm.operatorframework.io/docs/best-practices/)
diff --git a/docs/community-operator-pipeline.md b/docs/community-operator-pipeline.md
@@ -0,0 +1,76 @@
+# community-operator-pipeline
+
+The community operator pipeline provides a platform for openshift community contributors to validate, share, and distribute openshift operators.
+
+The community operator pipeline is divided into two workflows:
+1. The [community-hosted-pipeline](./community-operator-pipeline.md#community-hosted-pipeline) to test and validate the submitted operator bundle in the PR.
+1. The [community-release-pipeline](./community-operator-pipeline.md#community-release-pipeline) to release the operator bundle to the catalog after the PR is merged. 
+
+## community-hosted-pipeline
+
+The community hosted pipeline is used to test the submitted Operator bundles.
+
+It is intended to be triggered upon the creation of an operator bundle pull request and successfully completes with merging it. 
+
+As part of the community hosted pipeline, the operator submitted in the PR will be tested in two different ways:
+
+1. The static tests suite
+1. The dynamic tests (Preflight tests) 
+
+>**Note** To learn more about preflight tests, please follow this [link](https://github.com/redhat-openshift-ecosystem/openshift-preflight?tab=readme-ov-file#preflight).
+
+#### Static tests suite
+
+As part of the static tests suite, set of a check suite will be run against the submitted bundle and will return warnings and failures (if any) in the operator-sdk bundle validate tool's JSON output format. This results will be posted into the PR.
+
+Here is the example how the result will look like in the PR:
+
+![Static test result example](images/static_tests_example.png)
+
+#### Dynamic tests (Preflight tests)
+
+>**Note** The Preflight tests are the replacement of (orange/kiwi/lemon) test suits. 
+
+The preflight tests are designed to test and verify the the operator bundle content and the format of the operator bundle. The result link for the logs of the preflight test runs will be posted to the PR as shown below.
+
+![Preflight test run logs example](images/preflight_run_logs_example.png)
+
+In case of failures, please have a look at the logs of specific tests. If an error is not clear to you, please ask in the PR. Maintainers will be happy to help you with it.  
+
+Once all of the tests will be passed successfully, the PR will be merged automatically based on the conditions are met by community-hosted-pipeline.
+
+The PR will not merge automatically in the following cases:
+1. If the brand-new operator is submitted. 
+1. If the author of the PR is not listed as a reviewer in the `ci.yaml` file for the respective operator or as a repository maintainer. 
+
+If there are any of the above cases, the PR needs to be reviewed by the Repositoy maintainers or authorized reviewers. After the approval, the PR needs to be merged manually. Once the PR will be merged, the community-release-pipeline will be triggered automatically.
+
+>**NOTE:** The community hosted pipeline run results will be posted in the github PR comment.
+
+![community-hosted-pipeline](images/op_test_pr.png)
+
+## community-release-pipeline
+
+The community release pipeline is responsible for releasing a bundle image which has passed the test validations via community-hosted-pipeline.
+It's intended to be triggered automatically by the merge of a bundle pull request by the community hosted pipeline.
+It successfully completes once the bundle has been published to the catalog.
+
+>**NOTE:** The community release pipeline run results will be posted in the github PR comment.
+
+![community-hosted-pipeline](images/op_release.png)
+
+
+### There are new github pull request labels have been introduced for the community operator pipeline.
+
+| Label Name                               | Label Description                                                                           |
+|------------------------------------------|---------------------------------------------------------------------------------------------|
+| community-hosted-pipeline/started        | This label will be added to the PR when the hosted pipeline will be triggered.              |
+| community-hosted-pipeline/passed         | This label will be added to the PR when the hosted pipeline will be passed successfully.    |
+| community-hosted-pipeline/failed         | This label will be added to the PR when the hosted pipeline will be failed.                 |
+| community-release-pipeline/started       | This label will be added to the PR when the release pipeline will be triggered.             |
+| community-release-pipeline/passed        | This label will be added to the PR when the release pipeline will be passed successfully.   |
+| community-release-pipeline/failed        | This label will be added to the PR when the release pipeline will be failed.                |
+| validation-failed                        | This label will be added to the PR when the static tests will be failed in hosted pipeline. |
+
+
+
diff --git a/docs/contributing-prerequisites.md b/docs/contributing-prerequisites.md
@@ -0,0 +1,74 @@
+# Before submitting your Operator
+
+> **Important:** "First off, thanks for taking the time to contribute your Operator!"
+
+## A primer to Openshift Community Operators
+
+This project collects Community Operators that work with OpenShift to be displayed in the embedded OperatorHub. If you are new to Operators, start [here](https://operatorframework.io/).
+
+## Sign Your Work
+
+The contribution process works off standard git _Pull Requests_. Every PR needs to be signed. The sign-off is a simple line at the end of the explanation for a commit. Your signature certifies that you wrote the patch or otherwise have the right to contribute the material. The rules are pretty simple if you can certify the below (from [developercertificate.org](https://developercertificate.org/)):
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+Then you just add a line to every git commit message:
+
+    Signed-off-by: John Doe <[email protected]>
+
+Use your real name (sorry, no pseudonyms or anonymous contributions.)
+
+If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`.
+
+Note: If your git config information is set properly then viewing the `git log` information for your commit will look something like this:
+
+```
+Author: John Doe <[email protected]>
+Date:   Mon Oct 21 12:23:17 2019 -0800
+
+    Update README
+
+    Signed-off-by: John Doe <[email protected]>
+```
+
+Notice the `Author` and `Signed-off-by` lines **must match**.
+
+
diff --git a/docs/contributing-via-pr.md b/docs/contributing-via-pr.md
@@ -0,0 +1,39 @@
+# Submitting your Operator via Pull Requests (PR) in community operators project
+
+## Overview
+To submit an operator one has to do these steps
+
+1. Fork project `https://github.com/redhat-openshift-ecosystem/community-operators-prod`
+1. Make a pull request
+1. Place the operator in the target directory. [More info](./contributing-where-to.md)
+    - operators
+1. Configure `ci.yaml` file. [More info](./operator-ci-yaml.md)
+    - Setup reviewers
+    - Operator versioning strategy
+1. Verify tests and fix problems, if possible
+1. Ask for help in the PR in case of problems
+
+
+## Pull request
+
+When a pull request is created, a number of tests are executed via community hosted pipeline. One can see the results in the comment section of conversation tab.
+
+![PR](images/op_test_pr.png)
+
+## You are done
+User is done when all tests are green. When the PR is merged, the community release pipeline will be triggered.
+
+## Test results failed?
+When operator tests are failing, one can see a following picture
+
+![Summary of test results when failing](images/op_pr_tests_failed.png)
+
+In case of failures, please have a look at the logs of specific tests. If an error is not clear to you, please ask in the PR. Maintainers will be happy to help you with it.
+
+## Useful commands interacting with the pipeline
+You can post the following comment/command:
+
+Command | Functionality |
+--- | --- | 
+`/pipeline restart community-hosted-pipeline` | The hosted pipeline will be re-triggered and PR will be merged if possible. |
+`/pipeline restart community-release-pipeline` | The release pipeline will be re-triggered.
diff --git a/docs/contributing-where-to.md b/docs/contributing-where-to.md
@@ -0,0 +1,33 @@
+# Where to contribute
+
+Once you have forked the upstream repo, you will require to add your Operator Bundle to the forked repo. The forked repo will have directory structure similar to the structure outlined below.
+
+```bash
+├── config.yaml
+├── operators 
+│   └── new-operator
+│       ├── 0.0.102
+│       │   ├── manifests
+│       │   │   ├── new-operator.clusterserviceversion.yaml
+│       │   │   ├── new-operator-controller-manager-metrics-service_v1_service.yaml
+│       │   │   ├── new-operator-manager-config_v1_configmap.yaml
+│       │   │   ├── new-operator-metrics-reader_rbac.authorization.k8s.io_v1_clusterrole.yaml
+│       │   │   └── tools.opdev.io_demoresources.yaml
+│       │   ├── metadata
+│       │   │   └── annotations.yaml
+│       │   └── tests
+│       │       └── scorecard
+│       │           └── config.yaml
+│       └── ci.yaml
+└── 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. 
+
+>**Note** To learn more about preflight tests please follow this [link](https://github.com/redhat-openshift-ecosystem/openshift-preflight?tab=readme-ov-file#preflight).
+
+For partners and ISVs, certified operators can now be submitted via connect.redhat.com. If you have submitted your Operator there already, please ensure your submission here uses a different package name (refer to the README for more details).
diff --git a/docs/images/op_pr_tests_failed.png b/docs/images/op_pr_tests_failed.png
diff --git a/docs/images/op_release.png b/docs/images/op_release.png
diff --git a/docs/images/op_test_pr.png b/docs/images/op_test_pr.png
diff --git a/docs/images/preflight_run_logs_example.png b/docs/images/preflight_run_logs_example.png
diff --git a/docs/images/static_tests_example.png b/docs/images/static_tests_example.png
diff --git a/docs/operator-ci-yaml.md b/docs/operator-ci-yaml.md
@@ -0,0 +1,58 @@
+# 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`.
+
+> **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. 
+
+## Reviewers
+
+If you want to accelerate publishing your changes, consider adding yourself and others you trust to the `reviewers` list. If the author of PR will be in that list, changes she/he made will be taken as authorized changes. This will be the indicator for our pipeline that the PR is ready to merge automatically. 
+
+> **Note:**
+    If an author of PR is not in `reviewers` list or not in `ci.yaml` on `main` branch, PR will not be merged automatically.
+
+> **Note:**
+    If an auhor of PR is not in `reviewers` list and `reviewers` are present in `ci.yaml` file. All `reviewers` will be mentioned in PR comment to check for upcoming changes.
+
+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
+```
+$ cat <path-to-operator>/ci.yaml
+---
+reviewers:
+  - user1 
+  - user2
+
+```
+
+## Operator versioning
+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
+Every next version defines which version will be replaced using `replaces` key in the CSV file. It means, that there is a possibility to omit some versions from the *update graph*. The best practice is to put them in a separate channel then.
+
+### semver-mode
+Every version will be replaced by the next higher version according to semantic versioning.
+
+### Restrictions
+A contributor can decide if `semver-mode` or `replaces-mode` mode will be used for a specific operator. By default, `replaces-mode` is activated, when `ci.yaml` file is present and contains `updateGraph: replaces-mode`. When a contributor decides to switch and use `semver-mode`, it will be specified in `ci.yaml` file or the key `updateGraph` will be missing.
+
+### Example
+```
+$ cat <path-to-operator>/ci.yaml
+---
+# Use `replaces-mode` or `semver-mode`.
+updateGraph: replaces-mode
+```
+
+## 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
+```
+$ cat <path-to-operators>/<name>/<version>/.../my.clusterserviceversion.yaml
+metadata:
+  annotations:
+    operatorhub.io/ui-metadata-max-k8s-version: "1.21"
+```