|
| 1 | +# Generating a Cluster Service Version (CSV) |
| 2 | + |
| 3 | +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: |
| 4 | + |
| 5 | +- **Generate your first release** - encapsulate the metadata needed to install your Operator and configure the permissions it needs from the generated SDK files. |
| 6 | +- **Upgrade your Operator** - Carry over any customizations you have made and ensure a rolling update to the next version of your Operator. |
| 7 | +- **Refresh your CRDs** - If a new version has updated CRDs, refresh those definitions within the CSV automatically. |
| 8 | + |
| 9 | +## Configuration |
| 10 | + |
| 11 | +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: |
| 12 | + |
| 13 | +* Roles: `role.yaml` |
| 14 | +* Deployments: `operator.yaml` |
| 15 | +* Custom Resources (CR's): `crds/<group>_<version>_<kind>_cr.yaml` |
| 16 | +* Custom Resource Definitions (CRD's): `crds/<group>_<version>_<kind>_crd.yaml`. |
| 17 | + |
| 18 | +`gen-csv` reads these files and adds their data to a CSV in an alternate form. |
| 19 | + |
| 20 | +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]: |
| 21 | + |
| 22 | +>Users can configure CSV composition by populating several fields in the file `deploy/olm-catalog/csv-config.yaml`: |
| 23 | +> |
| 24 | +>- `crd-cr-path-list`: (string(, string)\*) a list of CRD and CR manifest file/directory paths. Defaults to `[deploy/crds]`. |
| 25 | +>- `operator-path`: (string) the operator resource manifest file path. Defaults to `deploy/operator.yaml`. |
| 26 | +>- `rbac-path-list`: (string(, string)\*) a list of RBAC role manifest file paths. Defaults to `[deploy/role.yaml]`. |
| 27 | +
|
| 28 | +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. |
| 29 | + |
| 30 | +## Versioning |
| 31 | + |
| 32 | +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/<operator-name>/0.0.1/<operator-name>.v0.0.1.clusterserviceversion.yaml`. A versioned directory such as `deploy/olm-catalog/<operator-name>/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. |
| 33 | + |
| 34 | +`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/<operator-name>/0.0.2/<operator-name>.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. |
| 35 | + |
| 36 | +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. |
| 37 | + |
| 38 | +## First Generation |
| 39 | + |
| 40 | +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/<operator-name>/0.0.1/<operator-name>.v0.0.1.clusterserviceversion.yaml`. No CSV existed previously in `deploy/olm-catalog/<operator-name>/0.0.1`, so no manifests were overwritten or modified. |
| 41 | + |
| 42 | +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: |
| 43 | + |
| 44 | +```console |
| 45 | +$ operator-sdk olm-catalog gen-csv --csv-version 0.0.1 |
| 46 | +INFO[0000] Generating CSV manifest version 0.0.1 |
| 47 | +INFO[0000] Required csv fields not filled in file deploy/olm-catalog/app-operator/0.0.1/app-operator.v0.0.1.clusterserviceversion.yaml: |
| 48 | + spec.keywords |
| 49 | + spec.maintainers |
| 50 | + spec.provider |
| 51 | +INFO[0000] Created deploy/olm-catalog/app-operator/0.0.1/app-operator.v0.0.1.clusterserviceversion.yaml |
| 52 | +``` |
| 53 | + |
| 54 | +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. |
| 55 | + |
| 56 | +A note on `specDescriptors` and `statusDescriptors` fields in `spec.customresourcedefinitions.owned`: |
| 57 | +* 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. |
| 58 | +* `displayName` is guessed from type names, but will not overwrite values already present. |
| 59 | +* `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. |
| 60 | + |
| 61 | +## Updating your CSV |
| 62 | + |
| 63 | +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. |
| 64 | + |
| 65 | +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). |
| 66 | + |
| 67 | +Including the `--update-crds` flag will update the CRD's in your Operator bundle. |
| 68 | + |
| 69 | +## Upgrading your CSV |
| 70 | + |
| 71 | +New versions of your CSV are created by running `operator-sdk gen-csv --csv-version <new-version> --from-version <old-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. |
| 72 | + |
| 73 | +Be sure to include the `--update-crds` flag if you want to add CRD's to your bundle alongside your CSV. |
| 74 | + |
| 75 | +## CSV fields |
| 76 | + |
| 77 | +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. |
| 78 | + |
| 79 | +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. |
| 80 | + |
| 81 | +Required: |
| 82 | + |
| 83 | +* `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`. |
| 84 | +* `spec.description` (user): a thorough description of the Operator's functionality. |
| 85 | +* `spec.displayName` (user): a name to display for the Operator in Operator Hub. |
| 86 | +* `spec.keywords`: (user) a list of keywords describing the Operator. |
| 87 | +* `spec.maintainers`: (user) a list of human or organizational entities maintaining the Operator, with a `name` and `email`. |
| 88 | +* `spec.provider`: (user) the Operator provider, with a `name`; usually an organization. |
| 89 | +* `spec.labels`: (user) a list of `key:value` pairs to be used by Operator internals. |
| 90 | +* `spec.version`: semantic version of the Operator, ex. `0.1.1`. |
| 91 | +* `spec.installModes`: what mode of [installation namespacing][install-modes] OLM should use. Currently all but `MultiNamespace` are supported by SDK Operators. |
| 92 | +* `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. |
| 93 | + * `description`: description of the CRD. |
| 94 | + * `resources`: any Kubernetes resources used by the CRD, ex. `Pod`'s and `ConfigMap`'s. |
| 95 | + * `specDescriptors`: UI hints for inputs and outputs of the Operator's spec. |
| 96 | + * `statusDescriptors`: UI hints for inputs and outputs of the Operator's status. |
| 97 | + |
| 98 | +Optional: |
| 99 | + |
| 100 | +* `metadata.annotations.alm-examples`: CR examples, in JSON string literal format, for your CRD's. Ideally one per CRD. |
| 101 | +* `metadata.annotations.capabilities`: level of Operator capability. See the [Operator maturity model][olm-capabilities] for a list of valid values. |
| 102 | +* `spec.replaces`: the name of the CSV being replaced by this CSV. |
| 103 | +* `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`. |
| 104 | +* `spec.selector`: (user) selectors by which the Operator can pair resources in a cluster. |
| 105 | +* `spec.icon`: (user) a base64-encoded icon unique to the Operator, set in a `base64data` field with a `mediatype`. |
| 106 | +* `spec.maturity`: the Operator's maturity, ex. `alpha`. |
| 107 | + |
| 108 | +## Further Reading |
| 109 | + |
| 110 | +* [Information][doc-csv] on what goes in your CSV and CSV semantics. |
| 111 | +* The original `gen-csv` [design doc][doc-csv-design], which contains a thorough description how CSV's are generated by the SDK. |
| 112 | + |
| 113 | +[doc-csv]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md |
| 114 | +[olm]:https://github.com/operator-framework/operator-lifecycle-manager |
| 115 | +[doc-gen-csv]:../../sdk-cli-reference.md#gen-csv |
| 116 | +[doc-project-layout]:../../project_layout.md |
| 117 | +[doc-csv-design]:../../design/milestone-0.2.0/csv-generation.md |
| 118 | +[doc-bundle]:https://github.com/operator-framework/operator-registry#manifest-format |
| 119 | +[x-desc-list]:https://github.com/openshift/console/blob/master/frontend/public/components/operator-lifecycle-manager/descriptors/types.ts#L5-L14 |
| 120 | +[install-modes]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md#operator-metadata |
| 121 | +[olm-capabilities]:../../images/operator-maturity-model.png |
0 commit comments