You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/design/milestone-0.0.7/csv-generation.md
+31-67Lines changed: 31 additions & 67 deletions
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Goal
4
4
5
-
The `operator-sdk generate olm-catalog` sub-command should generate a [**Cluster Service Version (CSV)**][olm-csv-definition] customized using information contained in user-defined yaml manifests and Golang source files. Operator developers, *users*, should be able to run `operator-sdk generate olm-catalog` and have their operators' state encapsulated in a CSV; this command should be idempotent and only update the CSV when a yaml manifest or Golang source file is changed. Users should not have to directly interact with a CSV, and should not be required to have in-depth CSV knowledge in order for their operator to interact with [**Operator Lifecycle Manager (OLM)**][olm-description] or publish metadata to the [**Catalog**][catalog-description].
5
+
The `operator-sdk build` sub-command should generate a [**Cluster Service Version (CSV)**][olm-csv-definition] customized using information contained in user-defined yaml manifests and Golang source files. Operator developers, *users*, should be able to run `operator-sdk build` and have their operators' state encapsulated in a CSV; this command should be idempotent and only update the CSV when a yaml manifest or Golang source file is changed. Users should not have to directly interact with a CSV, and should not be required to have in-depth CSV knowledge in order for their operator to interact with [**Operator Lifecycle Manager (OLM)**][olm-description] or publish metadata to the [**Catalog**][catalog-description].
6
6
7
7
## Background
8
8
@@ -14,13 +14,13 @@ The `operator-sdk generate olm-catalog` command currently produces a generic CSV
14
14
15
15
## Proposed Solution
16
16
17
-
`operator-sdk generate olm-catalog` creates a `deploy` directory, which is the standard location for all manifests and scripts required to deploy an operator. This location is where users should place RBAC rules, deployments, CRD's, etc. The SDK can leverage manifests in `deploy` to write a CSV.
17
+
Functionality of `operator-sdk generate olm-catalog` is refactored into `operator-sdk build` such that user workflow is simplified; the former command and functionality will persist. `operator-sdk build` creates a `deploy` directory, which is the standard location for all manifests and scripts required to deploy an operator. This location is where users should place RBAC rules, deployments, CRD's, etc. The SDK can leverage manifests in `deploy` to write a CSV.
18
18
19
-
`operator-sdk generate olm-catalog` will call the function `renderCSV` to either:
19
+
`operator-sdk build` will call the function `renderCSV` to either:
20
20
21
21
1. Create a new CSV, with the same location and naming convention as exists currently, using available data in yaml manifests and Golang source files.
22
22
23
-
1.`renderCSV` will check for an existing CSV in `deploy`. Upon not finding one, a [`ClusterServiceVersion` instance][olm-code-csv-struct], defined by the OLM, is created and fields easily derived from operator metadata, such as Kubernetes API `ObjectMeta`, are populated.
23
+
1.`renderCSV` will check for an existing CSV in `deploy`. Upon not finding one, a [`ClusterServiceVersion` instance][olm-csv-struct-code], defined by the OLM, is created and fields easily derived from operator metadata, such as Kubernetes API `ObjectMeta`, are populated.
24
24
1.`renderCSV` will search `deploy` for manifests that contain yaml objects a CSV uses, such as a `Deployment` Kubernetes API resource, and cache found objects in a CSV struct
25
25
1. Once this search completes, every cache instance field populated will be written back to the CSV yaml file. Note that individual yaml objects are overwritten and not the entire file.
26
26
@@ -42,7 +42,7 @@ type CSVUpdater interface {
42
42
}
43
43
```
44
44
45
-
`Apply` will use data from the `CSVUpdater` implementer to operate on `*v1alpha1.ClusterServiceVersion` instance fields relevant to that updater. The OLM defines the entire CSV spec [in Golang][olm-code-csv-spec] as a (versioned) hierarchy of `struct` components, each of which the SDK can alias to implement `CSVUpdater`.
45
+
`Apply` will use data from the `CSVUpdater` implementer to operate on `*v1alpha1.ClusterServiceVersion` instance fields relevant to that updater. The OLM defines the entire CSV spec [in Golang][olm-csv-spec-code] as a (versioned) hierarchy of `struct` components, each of which the SDK can alias to implement `CSVUpdater`.
46
46
47
47
Once sub-step 2 is reached when creating or updating a CSV, `renderCSV` will extract each yaml document discovered, and pass document data into a dispatcher function. The dispatcher selects the correct `CSVUpdater` to populate based on the documents' `Kind` yaml object, a manifest type identifier used in all (*TODO*: verify) operator manifests. The SDK accesses the latest version of CSV format and maintains OLM compatibility by leveraging the OLM spec implementations, rather than implementing the spec locally.
48
48
@@ -123,76 +123,40 @@ func (us *CSVInstallStrategyUpdate) Apply(csv *v1alpha1.ClusterServiceVersion) e
123
123
124
124
### User-defined yaml objects
125
125
126
-
Many CSV component objects cannot be populated using generated, non-SDK-specific manifests. These objects are mostly human-written, English metadata about the operator and various CRD's. A file, `describe.yaml`, should be written by a user with which the SDK can populate CSV objects; this file should live in the `deploy` directory. `describe.yaml`will have the following format:
126
+
Many CSV component objects cannot be populated using generated, non-SDK-specific manifests. These objects 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 objects. A lack of data in any of the required objects will generate an error on `operator-sdk build`.
127
127
128
-
```yaml
129
-
replaces: test-operator.0.1.0
130
-
displayName: Test Operator
131
-
description: |
128
+
Required:
129
+
-`displayName`: a public name to identify the operator.
130
+
-`description`: a short description of the operator's functionality.
131
+
-`keywords`: 1..N keywords describing the operator.
132
+
-`maintainers`: 1..N human or organizational entities maintaining the operator, with a `name` and `email`.
133
+
-`provider`: the operators' provider, with a `name`; usually an organization.
134
+
-`labels`: 1..N `key`:`value` pairs to be used by operator internals.
135
+
-`version`: semantic version of the operator, ex. `0.1.1`.
136
+
-`customresourcedefinitions`: any CRD's the operator uses.
137
+
- **Note**: this field will be populated automatically by the SDKif any CRD yaml files are present in `deploy`; however, several objects require user input (more details in the [CSV CRD spec section][olm-csv-crd-doc]):
138
+
- `description`: description of the CRD.
139
+
- `resources`: any Kubernetes resources leveraged by the CRD, ex. `Pod`'s, `StatefulSet`'s.
140
+
- `specDescriptors`: UI hints for inputs and outputs of the operator.
132
141
133
-
The Test Operator for Kubernetes provides ...
142
+
Optional:
143
+
-`replaces`: the CSV being replaced by this CSV.
144
+
-`links`: 1..N URL's to websites, documentation, etc. pertaining to the operator or application being managed, each with a `name` and `url`.
145
+
-`selector`: selectors by which the operator can pair resources in a cluster.
146
+
-`icon`: a base64-encoded icon unique to the operator, set in a `base64data` object with a `mediatype`.
147
+
-`maturity`: the operators' stage of development, ex. `beta`.
134
148
135
-
keywords: ['test', 'application', ...]
149
+
Further details on what data each field above should hold are found in the [CSV spec][olm-csv-spec-doc].
- description: Desired number of Pods for the cluster
179
-
displayName: Size
180
-
path: replicas
181
-
x-descriptors:
182
-
- 'urn:olm:descriptor:for:test:operator'
183
-
...
184
-
```
185
-
186
-
Each of the above yaml objects corresponds to a homonymous `spec` object child described by the CSV [`spec` documentation][olm-csv-spec-doc]. [Here][describe-yaml-example] is a workable, complex example `describe.yaml` a Prometheus operator developer would write to assist the SDK in CSV generation.
187
-
188
-
**Note**: Several yaml objects currently in `describe.yaml` can potentially be parsed from operator code; this SDK functionality will be addressed in a future design document.
151
+
**Note**: Several yaml objects currently requiring user intervention can potentially be parsed from operator code; such SDK functionality will be addressed in a future design document.
0 commit comments