diff --git a/docs/accepted_bundle_formats.md b/docs/accepted_bundle_formats.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/docs/community-operator-pipeline.md b/docs/community-operator-pipeline.md index 3c26d426a29..9a762b6c5e0 100644 --- a/docs/community-operator-pipeline.md +++ b/docs/community-operator-pipeline.md @@ -4,18 +4,18 @@ The community operator pipeline provides a platform for openshift community cont 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. +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. +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) +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). @@ -29,19 +29,19 @@ Here is the example how the result will look like in the PR: #### Dynamic tests (Preflight tests) ->**Note** The Preflight tests are the replacement of (orange/kiwi/lemon) test suits. +>**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. +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. +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. @@ -71,6 +71,3 @@ It successfully completes once the bundle has been published to the catalog. | 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-via-pr.md b/docs/contributing-via-pr.md index 5549e7dcecc..b210780eabc 100644 --- a/docs/contributing-via-pr.md +++ b/docs/contributing-via-pr.md @@ -34,6 +34,6 @@ In case of failures, please have a look at the logs of specific tests. If an err 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. \ No newline at end of file diff --git a/docs/contributing-where-to.md b/docs/contributing-where-to.md index d44803636b0..5502060d995 100644 --- a/docs/contributing-where-to.md +++ b/docs/contributing-where-to.md @@ -4,7 +4,7 @@ Once you have forked the upstream repo, you will require to add your Operator Bu ```bash ├── config.yaml -├── operators +├── operators │ └── new-operator │ ├── 0.0.102 │ │ ├── manifests @@ -22,11 +22,11 @@ Once you have forked the upstream repo, you will require to add your Operator Bu └── 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. +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). diff --git a/docs/operator-ci-yaml.md b/docs/operator-ci-yaml.md index 2595d5994a3..81896323354 100644 --- a/docs/operator-ci-yaml.md +++ b/docs/operator-ci-yaml.md @@ -3,11 +3,11 @@ 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. + 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. +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. @@ -22,7 +22,7 @@ For this to work, it is required to setup reviewers in `ci.yaml` file. It can be $ cat /ci.yaml --- reviewers: - - user1 + - user1 - user2 ``` diff --git a/docs/packaging-operator.md b/docs/packaging-operator.md index 2eb027985ab..66253694185 100644 --- a/docs/packaging-operator.md +++ b/docs/packaging-operator.md @@ -4,7 +4,7 @@ This repository makes use of the [Operator Framework](https://github.com/operato ### Packaging format -Your Operator submission can be formatted following the `bundle` or `packagemanifest` format. The `packagemanifest` format is a legacy format that is kept for backward compatibility only and then, it strongly recommended to use `bundle` format. The former allows shipping your entire Operator with all its versions in one single directory. The latter allows shipping individual releases in container images. +Your Operator submission can be formatted following the `bundle` or `packagemanifest` format. The `packagemanifest` format is a legacy format that is kept for backward compatibility only and then, it strongly recommended to use `bundle` format. The former allows shipping your entire Operator with all its versions in one single directory. The latter allows shipping individual releases in container images. In general, a released version of your Operator is described in a `ClusterServiceVersion` manifest alongside the `CustomResourceDefinitions` of your Operator and additional metadata describing your Operator listing. @@ -22,13 +22,13 @@ An Operator's CSV must contain the fields mentioned [here](./packaging-required- There is one CSV per version of your Operator alongside the CRDs. -#### Create a release +#### Create a release The `bundle` format has a top-level directory named after your Operator name in the `ClusterServiceVersion` directory. Inside are sub-directories for the individual bundle, named after the [semantic versioning](https://semver.org) release of your Operator. All metadata is defined within the individual release of the Operator. That is, inside each bundle. This includes the channel definitions. The default channel is also defined within the bundle and overwritten by every new bundle you add (this is a known limitation and is being worked on). -Within each version, you have your `CustomResourceDefinitions`, `ClusterServiceVersion` file (containing the same name and version of your Operator as defined inside the YAML structure) and some metadata about the bundle. You can [learn more about the bundle format here](https://olm.operatorframework.io/docs/tasks/creating-operator-bundle/) and also see an [example](https://github.com/operator-framework/bundle-example). +Within each version, you have your `CustomResourceDefinitions`, `ClusterServiceVersion` file (containing the same name and version of your Operator as defined inside the YAML structure) and some metadata about the bundle. You can [learn more about the bundle format here](https://olm.operatorframework.io/docs/tasks/creating-operator-bundle/) and also see an [example](https://github.com/operator-framework/bundle-example). Note that this community project only requires you to submit your bundle in the form of metadata. The integrated release pipeline of this repository will take care of publishing your bundle as a container image and maintaining it in a public catalog. @@ -117,7 +117,7 @@ operator-sdk bundle validate /tmp/my-operator-2.0.0-bundle/ --select-optional na #### About the Dockerfile A `Dockerfile` is typically part of the bundle metadata used to build the bundle image. For security reasons, our release process is generating an internal `Dockerfile` that is used to build and publish the bundle image. Existing `Dockerfile` or `bundle.Dockerfile` will be ignored. You can leverage the `annotations.yaml` file to control custom labels the resulting image should have. For example: - + ``` annotations: # Core bundle annotations. @@ -170,7 +170,7 @@ The icon is defined in a CSV as `spec.icon`. If you don't have an own icon, you - base64data: "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTguNTEgMjU4LjUxIj48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2QxZDFkMTt9LmNscy0ye2ZpbGw6IzhkOGQ4Zjt9PC9zdHlsZT48L2RlZnM+PHRpdGxlPkFzc2V0IDQ8L3RpdGxlPjxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPjxnIGlkPSJMYXllcl8xLTIiIGRhdGEtbmFtZT0iTGF5ZXIgMSI+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMTI5LjI1LDIwQTEwOS4xLDEwOS4xLDAsMCwxLDIwNi40LDIwNi40LDEwOS4xLDEwOS4xLDAsMSwxLDUyLjExLDUyLjExLDEwOC40NSwxMDguNDUsMCwwLDEsMTI5LjI1LDIwbTAtMjBoMEM1OC4xNiwwLDAsNTguMTYsMCwxMjkuMjVIMGMwLDcxLjA5LDU4LjE2LDEyOS4yNiwxMjkuMjUsMTI5LjI2aDBjNzEuMDksMCwxMjkuMjYtNTguMTcsMTI5LjI2LTEyOS4yNmgwQzI1OC41MSw1OC4xNiwyMDAuMzQsMCwxMjkuMjUsMFoiLz48cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xNzcuNTQsMTAzLjQxSDE0MS42NkwxNTQuOSw2NS43NmMxLjI1LTQuNC0yLjMzLTguNzYtNy4yMS04Ljc2SDEwMi45M2E3LjMyLDcuMzIsMCwwLDAtNy40LDZsLTEwLDY5LjYxYy0uNTksNC4xNywyLjg5LDcuODksNy40LDcuODloMzYuOUwxMTUuNTUsMTk3Yy0xLjEyLDQuNDEsMi40OCw4LjU1LDcuMjQsOC41NWE3LjU4LDcuNTgsMCwwLDAsNi40Ny0zLjQ4TDE4NCwxMTMuODVDMTg2Ljg2LDEwOS4yNCwxODMuMjksMTAzLjQxLDE3Ny41NCwxMDMuNDFaIi8+PC9nPjwvZz48L3N2Zz4=" mediatype: "image/svg+xml" ``` -Supported formats: svg, jpg, png +Supported formats: svg, jpg, png ### Updating your existing Operator @@ -193,36 +193,6 @@ Each Operator bundle not only contains `spec.version` but also points to an olde Regardless of which mode you choose to have OLM create update paths for your Operator, it continuously update your Operator often as new features are added and bugs are fixed. - -#### (Legacy) Create a release using the `packagemanifest` format - -**NOTE** It is recommended to use the `bundle` format instead. This format is still valid for backward compatibility only and at some point will no longer be supported. - -The `packagemanifest` format is a directory structure in which the top-level directory represents your Operator as a `package`. Below that top-level directory is versioned sub-directories, one for each released version of your Operator. The sub-directory names follow [a semantic version](https://semver.org) of your Operator and contain the `CustomResourceDefinition`s and `ClusterServiceVersion`. - -The exact version is the one of your Operator as defined in `spec.version` inside the CSV. The version should also be reflected in the CSV file name for ease of use. It is required that the `spec.name` field in the CSV is also the same as the package name. Follow the example below, assuming your Operator package is called `my-operator`: - -```sh -$ tree my-operator/ -my-operator -├── 0.1.0 -│ ├── my-operator-crd1.crd.yaml -│ ├── my-operator-crd2.crd.yaml -│ └── my-operator.v0.1.0.clusterserviceversion.yaml -├── 0.5.0 -│ ├── my-operator-crd1.crd.yaml -│ ├── my-operator-crd2.crd.yaml -│ ├── my-operator-crd3.crd.yaml -│ └── my-operator.v0.5.0.clusterserviceversion.yaml -├── 1.0.0 -│ ├── my-operator-crd1.crd.yaml -│ ├── my-operator-crd2.crd.yaml -│ ├── my-operator-crd3.crd.yaml -│ └── my-operator.v1.0.0.clusterserviceversion.yaml -└── my-operator.package.yaml -``` -The `package.yaml` is a YAML file at the root level of the package directory. It provides the package name, a selection of channels pointing to potentially different Operator Versions/CSVs and a default channel. The package name is what users on the cluster see when they discover Operators available to install. - ##### Channels ##### Use channels to allow your users to select a different update cadence, e.g. `stable` vs. `nightly`. If you have only a single channel the use of `defaultChannel` is optional. diff --git a/docs/packaging-required-criteria-ocp.md b/docs/packaging-required-criteria-ocp.md index be6a40c591b..c2f4160196e 100644 --- a/docs/packaging-required-criteria-ocp.md +++ b/docs/packaging-required-criteria-ocp.md @@ -6,9 +6,9 @@ To distribute on OpenShift Catalogs, you will need to comply with the same stand > **IMPORTANT** Kubernetes has been deprecating API(s) which will be removed and no longer available in `1.22` and in the Openshift version `4.9`. Note that your project will be unable to use them on `OCP 4.9/K8s 1.22` and then, it is strongly recommended to check [Deprecated API Migration Guide from v1.22][k8s-deprecated-guide] and ensure that your projects have them migrated and are not using any deprecated API. -> Note that your operator using them will not work in `1.22` and in the Openshift version `4.9`. OpenShift 4.8 introduces two new alerts that fire when an API that will be removed in the next release is in use. Check the event alerts of your Operators running on 4.8 and ensure that you will not find any warning about these API(s) still being used by it. +> Note that your operator using them will not work in `1.22` and in the Openshift version `4.9`. OpenShift 4.8 introduces two new alerts that fire when an API that will be removed in the next release is in use. Check the event alerts of your Operators running on 4.8 and ensure that you will not find any warning about these API(s) still being used by it. -> Also, to prevent workflow issues, its users will need to have installed in their OCP cluster a version of your operator compatible with 4.9 before they try to upgrade their cluster from any previous version to 4.9 or higher. In this way, it is recommended to ensure that your operators are no longer using these API(s) versions. However, If you still need to publish the operator bundles with any of these API(s) for use on earlier k8s/OCP versions, ensure that the operator bundle is configured accordingly. +> Also, to prevent workflow issues, its users will need to have installed in their OCP cluster a version of your operator compatible with 4.9 before they try to upgrade their cluster from any previous version to 4.9 or higher. In this way, it is recommended to ensure that your operators are no longer using these API(s) versions. However, If you still need to publish the operator bundles with any of these API(s) for use on earlier k8s/OCP versions, ensure that the operator bundle is configured accordingly. > Taking the actions below will help prevent users from installing versions of your operator on an incompatible version of OCP, and also prevent them from upgrading to a newer version of OCP that would be incompatible with the version of your operator that is currently installed on their cluster. @@ -21,7 +21,7 @@ apiVersion: operators.coreos.com/v1alpha1 kind: ClusterServiceVersion metadata: annotations: - # Prevent cluster upgrades to OpenShift Version 4.9 when this + # Prevent cluster upgrades to OpenShift Version 4.9 when this # bundle is installed on the cluster "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "4.8"}]' ``` @@ -30,10 +30,10 @@ The CSV annotation will eventually prevent the user from upgrading their OCP clu This option is useful when you know that the current version of your project will not work well on some specific Openshift version. -### Configure the Openshift distribution +### Configure the Openshift distribution Use the annotation `com.redhat.openshift.versions` in `bundle/metadata/annotations.yaml` to ensure that the index image will be generated with its OCP Label, to prevent the bundle from being distributed on to 4.9: - + ``` com.redhat.openshift.versions: "v4.6-v4.8" ``` @@ -65,9 +65,9 @@ Following is an example of an Operator bundle that uses the removed APIs in 1.22 ```sh $ ocp-olm-catalog-validator bundle/ --optional-values="file=bundle/metadata/annotations.yaml" -WARN[0000] Warning: Value memcached-operator.v0.0.1: this bundle is using APIs which were deprecated and removed in v1.22. More info: https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22. Migrate the API(s) for CRD: (["memcacheds.cache.example.com"]) -ERRO[0000] Error: Value : (memcached-operator.v0.0.1) olm.maxOpenShiftVersion csv.Annotations not specified with an OCP version lower than 4.9. This annotation is required to prevent the user from upgrading their OCP cluster before they have installed a version of their operator which is compatible with 4.9. For further information see https://docs.openshift.com/container-platform/4.8/operators/operator_sdk/osdk-working-bundle-images.html#osdk-control-compat_osdk-working-bundle-images -ERRO[0000] Error: Value : (memcached-operator.v0.0.1) this bundle is using APIs which were deprecated and removed in v1.22. More info: https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22. Migrate the APIs for this bundle is using APIs which were deprecated and removed in v1.22. More info: https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22. Migrate the API(s) for CRD: (["memcacheds.cache.example.com"]) or provide compatible version(s) via the labels. (e.g. LABEL com.redhat.openshift.versions='4.6-4.8') +WARN[0000] Warning: Value memcached-operator.v0.0.1: this bundle is using APIs which were deprecated and removed in v1.22. More info: https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22. Migrate the API(s) for CRD: (["memcacheds.cache.example.com"]) +ERRO[0000] Error: Value : (memcached-operator.v0.0.1) olm.maxOpenShiftVersion csv.Annotations not specified with an OCP version lower than 4.9. This annotation is required to prevent the user from upgrading their OCP cluster before they have installed a version of their operator which is compatible with 4.9. For further information see https://docs.openshift.com/container-platform/4.8/operators/operator_sdk/osdk-working-bundle-images.html#osdk-control-compat_osdk-working-bundle-images +ERRO[0000] Error: Value : (memcached-operator.v0.0.1) this bundle is using APIs which were deprecated and removed in v1.22. More info: https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22. Migrate the APIs for this bundle is using APIs which were deprecated and removed in v1.22. More info: https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22. Migrate the API(s) for CRD: (["memcacheds.cache.example.com"]) or provide compatible version(s) via the labels. (e.g. LABEL com.redhat.openshift.versions='4.6-4.8') ``` [sdk-cli-bundle-validate]: https://sdk.operatorframework.io/docs/cli/operator-sdk_bundle_validate/ diff --git a/docs/pull_request_template.md b/docs/pull_request_template.md index b604df2d769..a4863dd6843 100644 --- a/docs/pull_request_template.md +++ b/docs/pull_request_template.md @@ -2,27 +2,19 @@ Thanks for submitting your Operator. Please check the below list before you crea ### New Submissions -* [ ] Are you familiar with our [contribution guidelines](https://github.com/operator-framework/community-operators/blob/master/docs/contributing-via-pr.md)? -* [ ] Have you [packaged and deployed](https://github.com/operator-framework/community-operators/blob/master/docs/testing-operators.md) your Operator for Operator Framework? -* [ ] Have you tested your Operator with all Custom Resource Definitions? -* [ ] Have you tested your Operator in all supported [installation modes](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/building-your-csv.md#operator-metadata)? +* [ ] Are you familiar with our [contribution guidelines](contributing-via-pr.md)? +* [ ] Are you familiar with our [operator pipeline](community-operator-pipeline.md)? +* [ ] Have you tested your Operator with all Custom Resource Definitions [packaging](packaging-operator.md)? +* [ ] Have you tested your Operator in all supported [installation modes](operator-ci-yaml.md##Operator-versioning)? * [ ] Have you considered whether you want to use [semantic versioning order](https://github.com/operator-framework/community-operators/blob/master/docs/operator-ci-yaml.md#semver-mode)? -* [ ] Is your submission [signed](https://github.com/operator-framework/community-operators/blob/master/docs/contributing-prerequisites.md#sign-your-work)? -* [ ] Is operator [icon](https://github.com/operator-framework/community-operators/blob/master/docs/packaging-operator.md#operator-icon) set? - -### Updates to existing Operators - -* [ ] Did you create a `ci.yaml` file according to the [update instructions](https://github.com/operator-framework/community-operators/blob/master/docs/operator-ci-yaml.md)? -* [ ] Is your new CSV pointing to the previous version with the `replaces` property if you chose `replaces-mode` via the `updateGraph` property in `ci.yaml`? -* [ ] Is your new CSV referenced in the [appropriate channel](https://github.com/operator-framework/community-operators/blob/master/docs/packaging-operator.md#channels) defined in the `package.yaml` or `annotations.yaml` ? -* [ ] Have you tested an update to your Operator when deployed via OLM? -* [ ] Is your submission [signed](https://github.com/operator-framework/community-operators/blob/master/docs/contributing-prerequisites.md#sign-your-work)? +* [ ] Is your submission [signed](contributing-prerequisites.md#sign-your-work)? +* [ ] Is operator [icon](packaging-operator.md#operator-icon) set? ### Your submission should not -* [ ] Modify more than one operator -* [ ] Modify an Operator you don't own -* [ ] Rename an operator - please remove and add with a different name instead +* [ ] Add more than one operator bundle per PR +* [ ] Modify any operator +* [ ] Rename an operator * [ ] Modify any files outside the above mentioned folders * [ ] Contain more than one commit. **Please squash your commits.**