From 73caed6c93d2d309f25be594b97cefaed8368816 Mon Sep 17 00:00:00 2001 From: dmesser Date: Mon, 3 Jun 2019 10:31:21 +0200 Subject: [PATCH] contribution documentation --- README.md | 70 +++++----------------------- docs/contributing.md | 87 +++++++++++++++++++++++++++++++++++ docs/pull_request_template.md | 43 +++++++++++++++++ docs/testing-operators.md | 4 +- 4 files changed, 143 insertions(+), 61 deletions(-) create mode 100644 docs/contributing.md create mode 100644 docs/pull_request_template.md diff --git a/README.md b/README.md index 125e5e94be7..24e6bbb513b 100644 --- a/README.md +++ b/README.md @@ -2,78 +2,30 @@ This repo is the canonical source for Kubernetes Operators that appear on [OperatorHub.io](https://operatorhub.io), [OpenShift Container Platform](https://openshift.com) and [OKD](https://okd.io). -# Know what to contribute +## Add your Operator -To add your operator to any of the above platforms, you will need to submit a PR with your Operator packaged for use with [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager/). This package contains all of the Custom Resource Definitions (CRDs), access control rules and references to the container image needed to install and securely run your Operator, plus other info like a description of its features and supported Kubernetes versions. [Follow this guide to create an OLM-compatible CSV for your operator](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md), CRDs, and the package.yaml file for your operator. +We would love to see your Operator being 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://github.com/operator-framework/getting-started). -An Operator's CSV must contain the annotations mentioned [here][required-fields] for it to be displayed properly within the various platforms. +If you have an existing Operator read our [contribution guidelines](./docs/contributing.md) on how to package and test it. Then submit a Pull Request. -Your PR needs to be formatted as a `bundle` which is a directory named after your Operator with all `CustomResourceDefinitions`, the `ClusterServiceVersion` and package definitons in separate YAML manifests like so: +## Submitting your PR -```bash -$ ls my-operator/ -my-operator.v1.0.0.clusterserviceversion.yaml -my-operator-crd1.crd.yaml -my-operator-crd2.crd.yaml -my-operator.package.yaml -``` -Please note that the directory name should match the `packageName` of your operator in it's `package.yaml`, and should be used as a prefix for all files in the bundle. Please follow the conventions of the example above. +Review this [checklist](./docs/pull_request_template.md) upon creating a PR and after you acknowledged the contribution guidelines. -# Where to contribute +## Update your Operator -There are 2 directories where you can contribute, depending on a set of requirements: - -| Target Directory | Type of Operators | Target Platform | Requirements | -|--------------------------------|--------------------------------|-----------------------------|---------------------------------------------------------------| -| `community-operators` | Community OpenShift Operators | OpenShift / OKD | needs to work on OpenShift 3.11 or newer | -| `upstream-community-operators` | Community Kubernetes Operators | Kubernetes / OperatorHub.io | needs to work on Kubernetes 1.7 or newer | - -The column _Target Platform_ denotes where this Operator will be visible (embedded OperatorHub in OpenShift and OKD, or OperatorHub.io for Kubernetes) and where it's intended to run. - -For partners and ISVs, certified operators can now be submitted via connect.redhat.com - -**If you Operator works on both Kubernetes and OpenShift, place a copy of your bundle in the `upstream-community-operators` directory, as well as the `community-operators` directory.** - -Note that OpenShift and OKD clusters by default come with access to operators from `community-operators`, certified operators, and additional Red Hat operators. Please keep this in mind when submitting operators, as duplicate operators between these sources will not be tolerated. - -# Before submitting a PR +Similarly, to update your operator you need to submit a PR with any changes to your Operator resources. Refere to our [contribution guide](docs/contributing.md#updating-your-existing-operator) for more details. ## Test your Operator -Upon creating a pull request against this repo, a set of CI pipelines will run, see more details [here](https://github.com/operator-framework/community-operators/blob/master/docs/ci.md). - -You can help speed up the review of your PR by [testing manually](https://github.com/operator-framework/community-operators/blob/master/docs/testing-operators.md). - -## Verify your Operator Metadata - -The maintainers will work with you to make sure your Operator has the required metadata to function properly and be displayed with useful information for the end user. +Upon creating a pull request against this repo, a set of CI pipelines will run, see more details [here](./docs/ci.md). -You can help us with that by validating your `bundle` with [operator-courier](https://github.com/operator-framework/operator-courier). This tool will check against the [required fields][required-fields] in your CSV. - -```sh -operator-courier verify --ui_validate_io path/to/bundle -``` +You can help speed up the review of your PR by [testing locally](./docs/testing-operators.md). ## Preview your Operator on OperatorHub.io -If you are submitting your Operator in the `upstream-community-operators` directory your Operator will appear on OperatorHub.io. You can preview how your Operator would be rendered there by using this tool: [https://operatorhub.io/preview](https://operatorhub.io/preview) - -## Updating your Operator - -Similarly, to update your operator you need to submit a PR with any changes to your Operator resources. Within your CSV, add the additional `replaces: my-operator.v1.0.0` parameter which indicates that existing installations of your Operator may be upgraded seamlessly to the new version. It is encouraged to use continuous delivery to update your Operator often as new features are added and bugs are fixed. - -[Read more about testing your Operator](docs/testing-operators.md) - -## Operator CI Pipeline - -New Operator PRs are automatically checked for [required fields][required-fields] using the [`operator-courier`][operator-courier] and are run through a [`operator-sdk scorecard`][sdk-scorecard] test against a live cluster. PRs are also reviewed manually by the maintainers to ensure that the automated tests are running smoothly and that Operators with additional setup can be verified. - -[You can learn more about the tests run on submitted Operators in this doc](docs/testing-operators.md) +If you are submitting your Operator in the `upstream-community-operators` directory your Operator will appear on OperatorHub.io. You can preview how your Operator would be rendered there by using the [preview tool](https://operatorhub.io/preview). ## Reporting Bugs -Report bugs using the project issue tracker. - -[required-fields]: https://github.com/operator-framework/community-operators/blob/master/docs/required-fields.md -[operator-courier]: https://github.com/operator-framework/operator-courier -[sdk-scorecard]:https://github.com/operator-framework/operator-sdk/blob/master/doc/test-framework/scorecard.md +Use the issue tracker in this repository to report bugs. \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000000..d0e1da93474 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,87 @@ +# Submitting your Operator + +:+1::tada: First off, thanks for taking the time to contribute your Operator! :tada::+1: + +## A primer to Kubernetes Community Operators + +This projects collects Operators and publishes them to OperatorHub.io, a central registry for community-powered Kubernetes Operators. For OperatorHub.io your Operator needs to work with vanilla Kubernetes. +This project also collects Community Operators that work with OpenShift to be displayed in the embedded OperatorHub. If you are new to Operators, start [here](https://github.com/operator-framework/getting-started). + +## Package your Operator + +This repository makes use of the [Operator Framework](https://github.com/operator-framework) and its packaging concept for Operators. Your contribution is welcome in the form of a _Pull Request_ with your Operator packaged for use with [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager/). + +### Create a ClusterServiceVersion + +To add your operator to any of the above platforms, you will need to submit your Operator packaged for use with [Operator Lifecycle Manager](https://github.com/operator-framework/operator-lifecycle-manager/). This mainly consists of a YAML file called `ClusterServiceVersion` which contains references to all of the `CustomResource Definitions` (CRDs), RBAC rules, `Deployment` and container image needed to install and securely run your Operator. It also contains user-visible info like a description of its features and supported Kubernetes versions (also see further recommendations below). Note that your Operator is not supposed to self-register it's CRDs. + +[Follow this guide to create an OLM-compatible CSV for your operator](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md). You can also see an example [here](docs/required-fields#example-csv). An Operator's CSV must contain the fields and mentioned [here](./docs/required-fields#required-fields-for-operatorhub) for it to be displayed properly within the various platforms. + +### Bundle format + +Your Operator package will be formatted as a `bundle` which is a directory named after your Operator with all `CustomResourceDefinitions`, the `ClusterServiceVersion` and the package definiton in separate YAML manifests. + +Follow this example, assuming your Operator bundle is called `my-operator`. The bundle name should also correspond to the `name` field in the CSV. + +```bash +$ ls my-operator/ +my-operator.v1.0.0.clusterserviceversion.yaml +my-operator-crd1.crd.yaml +my-operator-crd2.crd.yaml +my-operator.package.yaml +``` + +Subsequent updates to your Operator should result in new CSV files, and potentially updated CRDs - they should all land in the directory mentioned above. + +The `package.yaml` describes the bundle. It provides the bundle name, a selection of channels pointing to potentially different CSVs and a default channel. 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. + +An example of `my-operator.package.yaml`: + +```yaml +packageName: my-operator +channels: +- name: stable + currentCSV: my-operator.v1.0.2 +- name: nightly + currentCSV: my-operator.v1.1.3-beta +defaultChannel: stable +``` + +Your CSV versioning should follow [semantic versioning](https://semver.org/) concepts. Again, `packageName`, the suffix of the `package.yaml` file name and the field in `spec.name` in the CSV should all refer to the same Operator name. + +### Updating your existing Operator + +Similarly to add a new Operator, to update your Operator you need to submit a PR with any changes to your Operator resources. Please create a new CSV when you submit more than cosmetic fixes. Within your new CSV, reference your previous CSV like so: `replaces: my-operator.v1.0.0` + +This indicates that existing installations of your Operator may be upgraded seamlessly to the new version. It is encouraged to use continuous delivery to update your Operator often as new features are added and bugs are fixed. + +## Provide information about your Operator + +A large part of the information gathered in the CSV is used for user-friendly visualization on [OperatorHub.io](https://operatorhub.io) or components like the embedded OperatorHub in OpenShift. Your work is on display, so please ensure to provide relevant information in your Operator's description, specifically covering: + +* What the managed application is about and where to find more information +* The features your Operator and how to use it +* Any manual steps required to fulfill pre-requisites for running / installing your Operator + +## Test locally before you contribute + +The team behind OperatorHub.io will support you in making sure you are Operator works and is packaged correctly. You can accelerate your submission greatly by testing your Operator with the Operator Framework by following our [documentation for local testing](./testing-operators.md). You are responsible for testing your Operator's APIs when deployed with OLM. + +## Verify CI test results + +Every PR against this repository is tested via [Continuous Integration](./ci.md). During these tests your Operator will be deployed on either a `minikube` or OpenShift 4 environments and checked for a healthy deployment. Also several tools are run to check your bundle for completeness. These are the same tools as referenced in our [testing docs](./testing-operators.md). Pay attention to the result of GitHub checks. + +## Where to contribute + +There are 2 directories where you can contribute, depending on some basic requirements and where you would like your Operator to show up: + +| Target Directory | Appears on | Target Platform | Requirements | +|--------------------------------|----------------------------|-----------------------------|------------------------------------------| +| `community-operators` | Embedded OperatorHub in OpenShift 4 | OpenShift / OKD | needs to work on OpenShift 4 or newer | +| `upstream-community-operators` | OperatorHub.io | Upstream Kubernetes | needs to work on Kubernetes 1.7 or newer | + +These repositories are used by OpenShift 4 and OperatorHub.io respectively. Specifically, Operators for Upstream Kubernetes for OperatorHub.io won't automatically appear on the embedded OperatorHub in OpenShift and should not be used on OpenShift. + +**If you Operator works on both Kubernetes and OpenShift, place a copy of your packaged bundle in the `upstream-community-operators` directory, as well as the `community-operators` directory. Submit them as separate PRs.** + +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). \ No newline at end of file diff --git a/docs/pull_request_template.md b/docs/pull_request_template.md new file mode 100644 index 00000000000..f99890bdd94 --- /dev/null +++ b/docs/pull_request_template.md @@ -0,0 +1,43 @@ +Thanks submitting your Operator. Please check below list before you create your Pull Request. + +### New Submissions + +* [ ] Are you familiar with our [contribution guidelines](https://github.com/operator-framework/community-operators/blob/master/docs/contributing.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/Documentation/design/building-your-csv.md#operator-metadata)? + +### Updates to existing Operators + +* [ ] Is your new CSV pointing to the previous version with the `replaces` property? +* [ ] Have you tested an update to your Operator when deployed via OLM? + +### Your submission should not + +* [ ] Modify more than one operator +* [ ] Submit operators to both `upstream-community-operators` and `community-operators` at once +* [ ] Modify any files outside the above mentioned folders +* [ ] Contain more than one commit. **Please squash your commits.** + +### Operator Description must contain (in order) + +1. [ ] Description about the managed Application and where to find more information +2. [ ] Features and capabilities of your Operator and how to use it +3. [ ] Any manual steps about potential pre-requisites for using your Operator + +### Operator Metadata should contain + +* [ ] Human readable name and 1-liner description about your Operator +* [ ] Valid [category name](https://github.com/operator-framework/community-operators/blob/master/docs/required-fields.md#categories)1 +* [ ] One of the pre-defined [capability levels](https://github.com/operator-framework/operator-courier/blob/4d1a25d2c8d52f7de6297ec18d8afd6521236aa2/operatorcourier/validate.py#L556)2 +* [ ] Links to the maintainer, source code and documentation +* [ ] Example templates for all Custom Resource Definitions intended to be used +* [ ] A quadratic logo + +Remember that you can preview your CSV [here](https://operatorhub.io/preview). + +-- + +1 If you feel your Operator does not fit any of the pre-defined categories, file a PR against this repo and explain your need + +2 For more information see [here](https://github.com/operator-framework/operator-sdk/blob/master/doc/images/operator-capability-level.svg) \ No newline at end of file diff --git a/docs/testing-operators.md b/docs/testing-operators.md index c0d4315d10a..7eefc99c9d0 100644 --- a/docs/testing-operators.md +++ b/docs/testing-operators.md @@ -1,6 +1,6 @@ # Testing your Operator with Operator Framework -These instructions walk you through how to test if your Operator deploys correctly with Operator Framework. +These instructions walk you through how to test if your Operator deploys correctly with Operator Framework. Although your submission will always be tested as part of the [CI](./ci.md) you can accelerate the process by testing locally. The process below assume that you have an Kubernetes Operator in the Operator Framework *bundle* format, for example: @@ -12,7 +12,7 @@ my-operator-crd2.crd.yaml my-operator.package.yaml ``` -where *my-operator* is the name of your Operator. If you don't have this format yet, refer to our [README](https://github.com/operator-framework/community-operators/blob/master/README.md). We will refer to this example of `my-operator` in the following instructions. +where *my-operator* is the name of your Operator. If you don't have this format yet, refer to our [contribution documentation](./contributing.md). We will refer to this example of `my-operator` in the following instructions. # Table of Contents