github.com/tototoman/operator-sdk@v0.8.2/doc/user/olm-catalog/generating-a-csv.md (about)

     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-paths`: (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  >- `role-path`: (string) the RBAC role manifest file path. 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-capability-level.png