diff --git a/doc/design/milestone-0.2.0/csv-generation.md b/doc/design/milestone-0.2.0/csv-generation.md index 6b2df0ea8d8..837b30135a3 100644 --- a/doc/design/milestone-0.2.0/csv-generation.md +++ b/doc/design/milestone-0.2.0/csv-generation.md @@ -2,7 +2,7 @@ ## Goal -The `operator-sdk olm-catalog gen-csv` sub-command will generate a [**Cluster Service Version (CSV)**][olm_csv_definition] customized using information contained in user-defined yaml manifests and operator source files. Operator developers, *users*, will run `operator-sdk olm-catalog gen-csv` with the `--csv-version $version` flag to have their operators' state encapsulated in a CSV with the supplied version; this action should be idempotent and only update the CSV file when a new version is supplied, or a yaml manifest or source file is changed. Users should not have to directly modify most fields in a CSV manifest. Those that require modification are defined [below](#user-defined-yaml-fields). A CSV-generating command removes the responsibility from users of having in-depth [**Operator Lifecycle Manager (OLM)**][olm_description] knowledge in order for their operator to interact with OLM or publish metadata to the [**Catalog**][catalog_description]. +The `operator-sdk olm-catalog gen-csv` sub-command will generate a [**Cluster Service Version (CSV)**][olm_csv_definition] customized using information contained in user-defined yaml manifests and operator source files. Operator developers, *users*, will run `operator-sdk olm-catalog gen-csv` with the `--csv-version $version` flag to have their operators' state encapsulated in a CSV with the supplied version; this action should be idempotent and only update the CSV file when a new version is supplied, or a yaml manifest or source file is changed. Users should not have to directly modify most fields in a CSV manifest. Those that require modification are defined in the [user docs][csv_user_doc]. A CSV-generating command removes the responsibility from users of having in-depth [**Operator Lifecycle Manager (OLM)**][olm_description] knowledge in order for their operator to interact with OLM or publish metadata to the [**Catalog**][catalog_description]. ## Background @@ -132,43 +132,6 @@ func (us *CSVInstallStrategyUpdate) Apply(csv *v1alpha1.ClusterServiceVersion) e } ``` -### User-defined yaml fields - -Many CSV fields cannot be populated using generated, non-SDK-specific manifests. These fields are mostly human-written, English metadata about the operator and various CRD's. Users must directly modify their CSV yaml file, adding personalized data to the following required fields. Users will receive a warning from `operator-sdk olm-catalog gen-csv` when a lack of data in any of the required fields is detected. - -Required: - -- `metadata.name`: a *unique* name for this CSV. Operator version should be included in the name to ensure uniqueness, ex. `app-operator.v0.1.1`. -- `spec.displayName`: a public name to identify the operator. -- `spec.description`: a short description of the operator's functionality. -- `spec.keywords`: 1..N keywords describing the operator. -- `spec.maintainers`: 1..N human or organizational entities maintaining the operator, with a `name` and `email`. -- `spec.provider`: the operators' provider, with a `name`; usually an organization. -- `spec.labels`: 1..N `key`:`value` pairs to be used by operator internals. -- `spec.version`: semantic version of the operator, ex. `0.1.1`. -- `spec.customresourcedefinitions`: any CRD's the operator uses. This field will be populated automatically by the SDK if any CRD yaml files are present in `deploy`; however, several fields not in the CRD manifest spec that require user input (more details in the [CSV CRD spec section][olm_csv_crd_doc]): - - `description`: description of the CRD. - - `resources`: any Kubernetes resources leveraged by the CRD, ex. `Pod`'s, `StatefulSet`'s. - - `specDescriptors`: UI hints for inputs and outputs of the operator. - -Optional: - -- `spec.replaces`: the name of the CSV being replaced by this CSV. -- `spec.links`: 1..N URL's to websites, documentation, etc. pertaining to the operator or application being managed, each with a `name` and `url`. -- `spec.selector`: selectors by which the operator can pair resources in a cluster. -- `spec.icon`: a base64-encoded icon unique to the operator, set in a `base64data` field with a `mediatype`. -- `spec.maturity`: the operators' capability level according to the [maturity model](../../images/operator-maturity-model.png), ex. `Seamless Upgrades`. - -Further details on what data each field above should hold are found in the [CSV spec][olm_csv_spec_doc]. - -**Note**: Several yaml fields currently requiring user intervention can potentially be parsed from operator code; such SDK functionality will be addressed in a future design document. - -### CSV versioning - -The CSV version is the same as the operators', and should be included somewhere in `metadata.name`. A new CSV will be generated when upgrading operator versions. - -**TODO:** discuss whether multiple CSV files can be present, each with a unique file name (ex. `app-operator.csv.0.1.1.yaml`), or a single `app-operator.csv.yaml` file that relies on VCS (git) to version the file. - [olm_csv_definition]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md#what-is-a-cluster-service-version-csv [olm_description]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/README.md [catalog_description]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/architecture.md#catalog-registry-design @@ -177,3 +140,4 @@ The CSV version is the same as the operators', and should be included somewhere [olm_csv_spec_doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#building-a-cluster-service-version-csv-for-the-operator-framework [olm_csv_install_strat_doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#operator-install [olm_csv_crd_doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#owned-crds +[csv_user_doc]:../../user/olm-catalog/generating-a-csv.md#csv-fields diff --git a/doc/user/olm-catalog/generating-a-csv.md b/doc/user/olm-catalog/generating-a-csv.md new file mode 100644 index 00000000000..fab3c472d95 --- /dev/null +++ b/doc/user/olm-catalog/generating-a-csv.md @@ -0,0 +1,121 @@ +# Generating a Cluster Service Version (CSV) + +This document describes how to manage the following lifecycle for your Operator using the SDK's [`operator-sdk olm-catalog gen-csv`][doc-gen-csv] command: + +- **Generate your first release** - encapsulate the metadata needed to install your Operator and configure the permissions it needs from the generated SDK files. +- **Upgrade your Operator** - Carry over any customizations you have made and ensure a rolling update to the next version of your Operator. +- **Refresh your CRDs** - If a new version has updated CRDs, refresh those definitions within the CSV automatically. + +## Configuration + +Operator SDK projects have an expected [project layout][doc-project-layout]. In particular, a few manifests are expected to be present in the `deploy` directory: + +* Roles: `role.yaml` +* Deployments: `operator.yaml` +* Custom Resources (CR's): `crds/___cr.yaml` +* Custom Resource Definitions (CRD's): `crds/___crd.yaml`. + +`gen-csv` reads these files and adds their data to a CSV in an alternate form. + +By default, a `deploy/olm-catalog/csv-config.yaml` file is generated when `gen-csv` is first run. The defaults written in the following fields contain paths to the aforementioned files. From the [design doc][doc-csv-design]: + +>Users can configure CSV composition by populating several fields in the file `deploy/olm-catalog/csv-config.yaml`: +> +>- `crd-cr-path-list`: (string(, string)\*) a list of CRD and CR manifest file/directory paths. Defaults to `[deploy/crds]`. +>- `operator-path`: (string) the operator resource manifest file path. Defaults to `deploy/operator.yaml`. +>- `rbac-path-list`: (string(, string)\*) a list of RBAC role manifest file paths. Defaults to `[deploy/role.yaml]`. + +Fields in this config file can be modified to point towards alternate manifest locations. For example, if I have one set of production CR/CRD manifests under `deploy/crds/production`, and a set of test manifests under `deploy/crds/test`, and I only want to include production manifests in my CSV, I can set `crd-cr-path-list: [deploy/crds/production]`. `gen-csv` will then ignore `deploy/crds/test` when getting CR/CRD data. + +## Versioning + +CSV's are versioned in path, file name, and in their `metadata.name` field. For example, running `operator-sdk olm-catalog gen-csv --csv-version 0.0.1` will generate a CSV at `deploy/olm-catalog//0.0.1/.v0.0.1.clusterserviceversion.yaml`. A versioned directory such as `deploy/olm-catalog//0.0.1` is known as a [*bundle*][doc-bundle]. Versions allow the OLM to upgrade or downgrade your Operator at runtime, i.e. in a cluster. A valid semantic version is required. + +`gen-csv` allows you to upgrade your CSV using the `--from-version` flag. If you have an existing CSV with version `0.0.1` and want to write a new version `0.0.2`, you can run `operator-sdk olm-catalog gen-csv --csv-version 0.0.2 --from-version 0.0.1`. This will write a new CSV manifest to `deploy/olm-catalog//0.0.2/.v0.0.2.clusterserviceversion.yaml` containing user-defined data from `0.0.1` and any modifications you've made to `roles.yaml`, `operator.yaml`, CR's, or CRD's. + +The SDK can manage CRD's in your Operator bundle as well. You can pass the `--update-crds` flag to `gen-csv` to add or update your CRD's in your bundle by copying manifests pointed to by `crd-cr-path-list` in your config. CRD's in a bundle are not updated by default. + +## First Generation + +Now that you've configured the generator, assuming version `0.0.1` is being generated, running `operator-sdk olm-catalog gen-csv --csv-version 0.0.1` will generate a CSV defining your Operator under `deploy/olm-catalog//0.0.1/.v0.0.1.clusterserviceversion.yaml`. No CSV existed previously in `deploy/olm-catalog//0.0.1`, so no manifests were overwritten or modified. + +Some fields might not have values after running `gen-csv` the first time. The SDK will warn you to fill required fields and make suggestions for values for other fields: + +```console +$ operator-sdk olm-catalog gen-csv --csv-version 0.0.1 +INFO[0000] Generating CSV manifest version 0.0.1 +INFO[0000] Required csv fields not filled in file deploy/olm-catalog/app-operator/0.0.1/app-operator.v0.0.1.clusterserviceversion.yaml: + spec.keywords + spec.maintainers + spec.provider +INFO[0000] Created deploy/olm-catalog/app-operator/0.0.1/app-operator.v0.0.1.clusterserviceversion.yaml +``` + +When running `gen-csv` with a version that already exists, the `Required csv fields...` info statement will become a warning, as these fields are useful for displaying your Operator in Operator Hub. + +A note on `specDescriptors` and `statusDescriptors` fields in `spec.customresourcedefinitions.owned`: +* Code comments are parsed to create `description`'s for each item in `specDescriptors` and `statusDescriptors`, so these comments should be kept up-to-date with Operator semantics. +* `displayName` is guessed from type names, but will not overwrite values already present. +* `path` and `x-descriptors` are guessed from JSON tags and their corresponding UI element from [this list][x-desc-list]. These values are presented as suggestions by `gen-csv` if they are not filled. + +## Updating your CSV + +Let's say you added a new CRD `deploy/crds/group_v1beta1_yourkind_crd.yaml` to your Operator project, and added a port to your Deployment manifest `operator.yaml`. Assuming you're using the same version as above, updating your CSV is as simple as running `operator-sdk olm-catalog gen-csv --csv-version 0.0.1`. `gen-csv` will append your new CRD to `spec.customresourcedefinitions.owned`, replace the old data at `spec.install.spec.deployments` with your updated Deployment, and write an updated CSV to the same location. + +The SDK will not overwrite user-defined fields like `spec.maintainers` or descriptions of CSV elements, with the exception of `specDescriptors[].displayName` and `statusDescriptors[].displayName` in `spec.customresourcedefinitions.owned`, as mentioned [above](#first-generation). + +Including the `--update-crds` flag will update the CRD's in your Operator bundle. + +## Upgrading your CSV + +New versions of your CSV are created by running `operator-sdk gen-csv --csv-version --from-version `. Running this command will copy user-defined fields from the old CSV to the new CSV and make updates to the new version if any manifest data was changed. This command fills the `spec.replaces` field with the old CSV versions' name. + +Be sure to include the `--update-crds` flag if you want to add CRD's to your bundle alongside your CSV. + +## CSV fields + +Below are two lists of fields: the first is a list of all fields the SDK and OLM expect in a CSV, and the second are optional. + +Several fields require user input. The set of fields with this requirement may change as the SDK becomes better at generating CSV's. For now, those are marked with a `(user)` qualifier. + +Required: + +* `metadata.name`: a *unique* name for this CSV. Operator version should be included in the name to ensure uniqueness, ex. `app-operator.v0.1.1`. +* `spec.description` (user): a thorough description of the Operator's functionality. +* `spec.displayName` (user): a name to display for the Operator in Operator Hub. +* `spec.keywords`: (user) a list of keywords describing the Operator. +* `spec.maintainers`: (user) a list of human or organizational entities maintaining the Operator, with a `name` and `email`. +* `spec.provider`: (user) the Operator provider, with a `name`; usually an organization. +* `spec.labels`: (user) a list of `key:value` pairs to be used by Operator internals. +* `spec.version`: semantic version of the Operator, ex. `0.1.1`. +* `spec.installModes`: what mode of [installation namespacing][install-modes] OLM should use. Currently all but `MultiNamespace` are supported by SDK Operators. +* `spec.customresourcedefinitions`: any CRD's the Operator uses. This field will be filled by the SDK if any CRD manifests pointed to by `crd-cr-path-list` in your config. + * `description`: description of the CRD. + * `resources`: any Kubernetes resources used by the CRD, ex. `Pod`'s and `ConfigMap`'s. + * `specDescriptors`: UI hints for inputs and outputs of the Operator's spec. + * `statusDescriptors`: UI hints for inputs and outputs of the Operator's status. + +Optional: + +* `metadata.annotations.alm-examples`: CR examples, in JSON string literal format, for your CRD's. Ideally one per CRD. +* `metadata.annotations.capabilities`: level of Operator capability. See the [Operator maturity model][olm-capabilities] for a list of valid values. +* `spec.replaces`: the name of the CSV being replaced by this CSV. +* `spec.links`: (user) a list of URL's to websites, documentation, etc. pertaining to the Operator or application being managed, each with a `name` and `url`. +* `spec.selector`: (user) selectors by which the Operator can pair resources in a cluster. +* `spec.icon`: (user) a base64-encoded icon unique to the Operator, set in a `base64data` field with a `mediatype`. +* `spec.maturity`: the Operator's maturity, ex. `alpha`. + +## Further Reading + +* [Information][doc-csv] on what goes in your CSV and CSV semantics. +* The original `gen-csv` [design doc][doc-csv-design], which contains a thorough description how CSV's are generated by the SDK. + +[doc-csv]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md +[olm]:https://github.com/operator-framework/operator-lifecycle-manager +[doc-gen-csv]:../../sdk-cli-reference.md#gen-csv +[doc-project-layout]:../../project_layout.md +[doc-csv-design]:../../design/milestone-0.2.0/csv-generation.md +[doc-bundle]:https://github.com/operator-framework/operator-registry#manifest-format +[x-desc-list]:https://github.com/openshift/console/blob/master/frontend/public/components/operator-lifecycle-manager/descriptors/types.ts#L5-L14 +[install-modes]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md#operator-metadata +[olm-capabilities]:../../images/operator-maturity-model.png