diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 275db19c7..ea2b37da0 100644 --- a/.github/workflows/documentation.yaml +++ b/.github/workflows/documentation.yaml @@ -24,7 +24,7 @@ jobs: mkdocs build - name: Deploy uses: peaceiris/actions-gh-pages@v4 - if: github.ref == 'refs/heads/main' + # if: github.ref == 'refs/heads/main' with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./site diff --git a/docs/img/fbc-auto-release-pr.png b/docs/img/fbc-auto-release-pr.png new file mode 100644 index 000000000..2607aa845 Binary files /dev/null and b/docs/img/fbc-auto-release-pr.png differ diff --git a/docs/users/contributing-via-pr.md b/docs/users/contributing-via-pr.md index 272bd0bd8..9c0dfdec6 100644 --- a/docs/users/contributing-via-pr.md +++ b/docs/users/contributing-via-pr.md @@ -4,14 +4,16 @@ To submit an operator one has to do these steps 1. Fork project based on desired [Operator Repository](./pipelines_overview.md#operator-repositories) -1. Place the operator in the target directory. [More info](./contributing-where-to.md) +2. 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) +3. Configure `ci.yaml` file. [More info](./operator-ci-yaml.md) - Setup reviewers - 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 + - Add template to catalog mapping +4. Configure the `release-config.yaml` file if you want to automatically release the operator to the OCP catalogs. [More info](./fcb_autorelease.md#release-configyaml) +5. Make a pull request with a new operator bundle or catalog changes +6. Verify tests and fix problems, if possible +7. Ask for help in the PR in case of problems ## Pull request diff --git a/docs/users/contributing-where-to.md b/docs/users/contributing-where-to.md index 06b242879..58393f56e 100644 --- a/docs/users/contributing-where-to.md +++ b/docs/users/contributing-where-to.md @@ -15,6 +15,7 @@ Once you have forked the upstream repo, you will require to add your Operator Bu │ │ │ └── tools.opdev.io_demoresources.yaml │ │ ├── metadata │ │ │ └── annotations.yaml +│ │ ├── release-config.yaml │ │ └── tests │ │ └── scorecard │ │ └── config.yaml diff --git a/docs/users/fbc_workflow.md b/docs/users/fbc_workflow.md index 752344f58..f67488200 100644 --- a/docs/users/fbc_workflow.md +++ b/docs/users/fbc_workflow.md @@ -18,13 +18,59 @@ File-based catalog templates serve as a simplified view of a catalog that can be 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 -* SemVer template +* Basic template - `olm.template.basic` +* SemVer template - `olm.semver` More information about each template can be found at [opm doc](https://olm.operatorframework.io/docs/reference/catalog-templates/). The recommended template from the maintainability point of view is `SemVer`. +### FCB template mapping +To be able to generate a catalog from templates a user needs to provide a mapping between +template and catalog. The mapping is stored in the `ci.yaml` file. Based on your preference +you can map a template to a catalog version with 1:N mapping or 1:1 mapping. + +Here is an example of the `ci.yaml` file with single template rendering multiple catalogs (`1:N`): + +```yaml +--- +fbc: + enabled: true + catalog_mapping: + - template_name: my-custom-semver-template.yaml # The name of the file inside ./catalog-templates directory + catalogs_names: # a list of catalogs within the /catalogs directory + - "v4.15" + - "v4.16" + - "v4.17" + type: olm.semver + - template_name: my-custom-basic-template.yaml # The name of the file inside catalog-templates directory + catalogs_names: + - "v4.12" + - "v4.13" + type: olm.template.basic +``` + +And here is an example of the `ci.yaml` file with a single template rendering a single catalog (`1:1`): + +```yaml +--- +fbc: + enabled: true + catalog_mapping: + - template_name: v4.14.yaml + catalog_names: ["v4.14"] + type: olm.template.basic + - template_name: v4.15.yaml + catalog_names: ["v4.15"] + type: olm.template.basic + - template_name: v4.16.yaml + catalog_names: ["v4.16"] + type: olm.template.basic + - template_name: v4.17.yaml + catalog_names: ["v4.17"] + type: olm.template.basic +``` + ## Generate catalogs using templates To generate a final catalog for an operator a user needs to execute different `opm` commands based on the template type. We as operator pipeline maintainers want @@ -43,6 +89,7 @@ The right place for the Makefile is in the operator's root directory ``` . ├── 0.0.1 +| ├── release-config.yaml │   ├── manifests │   └── metadata ├── catalog-templates @@ -51,8 +98,6 @@ The right place for the Makefile is in the operator's root directory ``` -You can modify the Makefile based on your needs and use it to generate catalogs by running `make catalogs`. - > [!IMPORTANT] > In case an operator isn't shipped to all OCP catalog versions manually update `OCP_VERSIONS` > variable in the `Makefile` and include only versions supported by an operator. @@ -83,6 +128,16 @@ catalogs ``` ### Adding new bundle to Catalog +A new bundle can be added automatically to your templates and catalogs if you use +the automated release feature. The process is described in the +[fbc auto-release](./fbc_autorelease.md) documentation. + +It is highly recommended to use the automated release feature as it simplifies the process +from the user perspective. + +However if you want to manually add a new bundle to the catalog follow the steps below. + + 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 diff --git a/docs/users/fcb_autorelease.md b/docs/users/fcb_autorelease.md new file mode 100644 index 000000000..944225908 --- /dev/null +++ b/docs/users/fcb_autorelease.md @@ -0,0 +1,69 @@ +# File-Based Catalog - auto-release +By the nature of the File-Based Catalog (FBC) mode, the release of operator is made of two steps. +* The first step builds, test and release bundle image +* The second step adds a bundle to OCP catalog and releases it + +The second step can be now automated and user is no longer required to manually create a +second PR with catalog changes. The release pipeline will take care of it. + +The process will require an additional configuration in the `release-config.yaml` file. +Once a PR with new bundle and `release-config.yaml` is merged, the release pipeline will +open a new PR with catalog changes. + +Example of such PR can be found [here](https://github.com/Allda/community-operators-pipeline-preprod/pull/20). +The second PR is linked with it original PR and looks like [this](https://github.com/Allda/community-operators-pipeline-preprod/pull/25): + +![Release info](../img/fbc-auto-release-pr.png) + +## release-config.yaml + +If you want your operators to be automatically released to the OCP catalogs in the FBC mode, +you will need to configure the `release-config.yaml` file. The file should be placed +into the bundle version directory, e.g. `operators/aqua/0.0.2/release-config.yaml`. + +``` +tree operators/aqua +. +├── 0.0.2 +│   ├── release-config.yaml # This is the file +│   ├── manifests +│   └── metadata +├── catalog-templates +├── ci.yaml +└── Makefile +``` +Its content determines where exactly the bundle will be released in terms of +the OCP version and the place in the update graph. + +### Example + +```yaml +--- +catalog_templates: + - template_name: basic.yaml + channels: [my-channel] + replaces: aqua.0.0.1 + - template_name: semver.yaml + channels: [Fast, Stable] +``` +The example above shows a release configuration where operator bundle is going to be +released to the `my-channel` channel in the `basic.yaml` catalog template and to the +`Fast` and `Stable` channels in the `semver.yaml` catalog template. + +The `replaces` field is optional and it specifies the bundle that the new bundle +replaces in the update graph. + +### File structure +The schema of the file is available here: [release-config.yaml schema](https://github.com/redhat-openshift-ecosystem/operator-pipelines/blob/main/operator-pipeline-images/operatorcert/schemas/release-config-schema.json). +The schema is validated automatically in the pipeline and the PR will fail with explanations if the file is not valid. + +Here is a summary of the file structure: + +* The top-level key is `catalog_templates` which is a list of objects. +* Each object has the following keys: + * `template_name` - the name of the catalog template file in the `catalog-templates` directory. + * `channels` - a list of channels where the bundle should be released. + * In case of using `SemVer` a user can pick from allowed values: `Fast`, `Stable` and `Candidate`. + * `replaces` - the bundle that the new bundle replaces in the update graph. (**Optional**, only for the basic templates) + * `skips` - a list of bundles that should be skipped in the update graph. (**Optional**, only for the basic templates) + * `skipRange` - a range of bundles that should be skipped in the update graph. (**Optional**, only for the basic templates) diff --git a/docs/users/operator-ci-yaml.md b/docs/users/operator-ci-yaml.md index 5cf8eb6dd..ac57378da 100644 --- a/docs/users/operator-ci-yaml.md +++ b/docs/users/operator-ci-yaml.md @@ -45,12 +45,29 @@ The `fbc.version_promotion_strategy` option defines the strategy for promoting t - `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 +### `fbc.catalog_mapping` +The mapping serves as a link between catalog templates within the `./catalog-templates` directory and catalogs within the `./catalogs` directory. + +For more details and structure visit the [FBC workflow page](./fbc_workflow.md#fcb-template-mapping). + ### Example ```yaml --- fbc: - enabled: true - version_promotion_strategy: never + enabled: true + version_promotion_strategy: never + catalog_mapping: + - template_name: my-custom-semver-template.yaml # The name of the file inside ./catalog-templates directory + catalogs_names: # a list of catalogs within the /catalogs directory + - "v4.15" + - "v4.16" + - "v4.17" + type: olm.semver + - template_name: my-custom-basic-template.yaml # The name of the file inside catalog-templates directory + catalogs_names: + - "v4.12" + - "v4.13" + type: olm.template.basic ``` diff --git a/docs/users/static_checks.md b/docs/users/static_checks.md index 4c4203843..4bd30d5ed 100644 --- a/docs/users/static_checks.md +++ b/docs/users/static_checks.md @@ -52,15 +52,15 @@ The test is based on `operator-sdk bundle validate` command with `name=operatorh The test is based on `operator-sdk bundle validate` command with `suite=operatorframework` test suite [(link)](https://sdk.operatorframework.io/docs/cli/operator-sdk_bundle_validate/#operator-sdk-bundle-validate). #### check_required_fields -| Field name | Validation | Description | -|------------|------------|------| -| `spec.displayName` | `.{3,50}` | A string with 3 - 50 characters | -| `spec.description` | `.{20,}` | A bundle description with at least 20 characters | -| `spec.icon` | `media` | A valid base64 content with a supported media type (`{"base64data": , "mediatype": enum["image/png", "image/jpeg", "image/gif", "image/svg+xml"]}`) | -| `spec.version` | `SemVer` | Valid semantic version | -| `spec.maintainers` | | At least 1 maintainer contacts. Example: `{"name": "User 123", "email": "user@redhat.com"}` | -| `spec.provider.name` | `.{3,}` | A string with at least 3 characters | -| `spec.links` | | At least 1 link. Example: `{"name": "Documentation", "url": "https://redhat.com"}` | +| Field name | Validation | Description | +| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `spec.displayName` | `.{3,50}` | A string with 3 - 50 characters | +| `spec.description` | `.{20,}` | A bundle description with at least 20 characters | +| `spec.icon` | `media` | A valid base64 content with a supported media type (`{"base64data": , "mediatype": enum["image/png", "image/jpeg", "image/gif", "image/svg+xml"]}`) | +| `spec.version` | `SemVer` | Valid semantic version | +| `spec.maintainers` | | At least 1 maintainer contacts. Example: `{"name": "User 123", "email": "user@redhat.com"}` | +| `spec.provider.name` | `.{3,}` | A string with at least 3 characters | +| `spec.links` | | At least 1 link. Example: `{"name": "Documentation", "url": "https://redhat.com"}` | #### check_dangling_bundles The test prevents from releasing an operator and keeping any previous bundle dangling. @@ -133,6 +133,10 @@ This check will ensure that all bundle images in the file based catalog for give operator catalog(s) use allowed image registry. Allowed registries are configured in `(repo_root)/config.yaml` under the key `allowed_bundle_registries`. +#### check_schema_bundle_release_config +The test validates the `release-config.yaml` file against the schema. The schema +the file including the schema is described [here](./fcb_autorelease.md#release-configyaml) + ## Running tests locally ```bash diff --git a/mkdocs.yml b/mkdocs.yml index fc488f963..53374e6d1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,8 +17,9 @@ nav: - "Before submitting your Operator": "users/contributing-prerequisites.md" - "Where to place operator": "users/contributing-where-to.md" - "Best practices": "users/best-practices.md" - - "File base catalog onboarding": "users/fbc_onboarding.md" - - "File base catalog workflow": "users/fbc_workflow.md" + - "File based catalog onboarding": "users/fbc_onboarding.md" + - "File based catalog workflow": "users/fbc_workflow.md" + - "File based catalog auto-release": "users/fbc_autorelease.md" - "OKD/OpenShift Catalogs criteria and options": "users/packaging-required-criteria-ocp.md" - "Admin": - "Admin guide": "pipeline-admin-guide.md"