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
+28-64Lines changed: 28 additions & 64 deletions
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,7 @@ The `operator-sdk generate olm-catalog` command currently produces a generic CSV
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