Skip to content

Commit 69b71cb

Browse files
estrozestroz
committed
doc/design/milestone-0.0.7/csv-generation.md: sections on 'CSVUpdater' and user-written data
doc/design/milestone-0.0.7example.describe.yaml: example 'describe.yaml' file referenced in csv-generation.md
1 parent bf46e70 commit 69b71cb

File tree

2 files changed

+212
-1
lines changed

2 files changed

+212
-1
lines changed

‎doc/design/milestone-0.0.7/csv-generation.md

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,84 @@ The `operator-sdk generate olm-catalog` command currently produces a generic CSV
2929
1. `renderCSV` will check for an existing CSV in `deploy`. Upon finding one, the CSV yaml file contents will be marshalled into a `ClusterServiceVersion` struct instance, which will act as the cache described above.
3030
1. Same as above.
3131
1. Same as above.
32+
33+
### Extensible `CSVUpdater` CSV update mechanism
34+
35+
The CSV spec will likely change over time as new Kubernetes and OLM features are implemented; we need the ability to easily extend the update system. We can define the `CSVUpdater` interface as follows to encapsulate individual CSV field updates in methods:
36+
37+
```Go
38+
import v1alpha1 "github.com/operator-framework/operator-lifecycle-manager/pkg/api/apis/operators/v1alpha1"
39+
40+
type CSVUpdater interface {
41+
Apply(*v1alpha1.ClusterServiceVersion) error
42+
}
43+
```
44+
45+
`Apply` will use data from the underlying implementer of the `CSVUpdater` interface 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 separate `struct` components, each of which we can alias to implement `CSVUpdater`. 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.
46+
47+
### User-defined yaml objects
48+
49+
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`, with the following format should be written by a user with which the SDK can populate CSV objects:
50+
51+
```yaml
52+
replaces: test-operator.0.1.0
53+
displayName: Test Operator
54+
description: |
55+
56+
The Test Operator for Kubernetes provides ...
57+
58+
keywords: ['test', 'application', ...]
59+
60+
maintainers:
61+
- name: Your Org
62+
email: [email protected]
63+
...
64+
65+
provider:
66+
name: Your Org
67+
68+
links:
69+
- name: Test
70+
url: https://www.test.com/
71+
- name: Documentation
72+
url: https://your.org/operators/test/docs/latest/
73+
...
74+
75+
labels:
76+
my-label-1: test.0.1.1
77+
my-label-2: testoperator
78+
...
79+
80+
selector:
81+
matchLabels:
82+
my-label-2: testoperator
83+
...
84+
85+
icon:
86+
- base64data: PHN2ZyB3aWR0aD0iMjQ ... ==
87+
mediatype: image/svg+xml
88+
89+
maturity: beta
90+
version: 0.1.1
91+
92+
customresourcedefinitions:
93+
owned:
94+
- name: test.coreos.com
95+
description: A running Test instance
96+
resources:
97+
- kind: Pod
98+
version: v1
99+
...
100+
specDescriptors:
101+
- description: Desired number of Pods for the cluster
102+
displayName: Size
103+
path: replicas
104+
x-descriptors:
105+
- 'urn:olm:descriptor:for:test:operator'
106+
...
107+
```
108+
109+
Each of the above yaml objects corresponds to homonymous `spec` object children described by the CSV [`spec` documentation][olm-csv-spec-doc]. [Here][describe-yaml-example] is an example `describe.yaml` a Prometheus operator developer would write to assist in CSV generation.
32110

33111
## API
34112

@@ -38,4 +116,7 @@ The `operator-sdk generate olm-catalog` command currently produces a generic CSV
38116
[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
39117
[olm-description]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/README.md
40118
[catalog-description]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/architecture.md#catalog-registry-design
41-
[olm-code-csv-struct]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go#L261
119+
[olm-code-csv-struct]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go#L261
120+
[olm-code-csv-spec]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go
121+
[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
122+
[describe-yaml-example]:example.describe.yaml

‎doc/design/milestone-0.0.7/example.describe.yaml

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
replaces: prometheusoperator.0.15.0
2+
displayName: Prometheus Operator
3+
description: |
4+
The Prometheus Operator for Kubernetes provides easy monitoring definitions for Kubernetes services and deployment and management of Prometheus instances.
5+
Once installed, the Prometheus Operator provides the following features:
6+
* **Create/Destroy**: Easily launch a Prometheus instance for your Kubernetes namespace, a specific application or team easily using the Operator.
7+
* **Simple Configuration**: Configure the fundamentals of Prometheus like versions, persistence, retention policies, and replicas from a native Kubernetes resource.
8+
* **Target Services via Labels**: Automatically generate monitoring target configurations based on familiar Kubernetes label queries; no need to learn a Prometheus specific configuration language.
9+
### Other Supported Features
10+
**High availability**
11+
Multiple instances are run across failure zones and data is replicated. This keeps your monitoring available during an outage, when you need it most.
12+
**Updates via automated operations**
13+
New Prometheus versions are deployed using a rolling update with no downtime, making it easy to stay up to date.
14+
**Handles the dynamic nature of containers**
15+
Alerting rules are attached to groups of containers instead of individual instances, which is ideal for the highly dynamic nature of container deployment.
16+
keywords: ['prometheus', 'monitoring', 'tsdb', 'alerting']
17+
18+
maintainers:
19+
- name: Red Hat
20+
email: [email protected]
21+
22+
provider:
23+
name: Red Hat
24+
25+
links:
26+
- name: Prometheus
27+
url: https://www.prometheus.io/
28+
- name: Documentation
29+
url: https://coreos.com/operators/prometheus/docs/latest/
30+
- name: Prometheus Operator
31+
url: https://github.com/coreos/prometheus-operator
32+
33+
labels:
34+
alm-status-descriptors: prometheusoperator.0.22.2
35+
alm-owner-prometheus: prometheusoperator
36+
37+
selector:
38+
matchLabels:
39+
alm-owner-prometheus: prometheusoperator
40+
41+
icon:
42+
- base64data: PHN2ZyB3aWR0aD0iMjQ5MCIgaGVpZ2h0PSIyNTAwIiB2aWV3Qm94PSIwIDAgMjU2IDI1NyIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiBwcmVzZXJ2ZUFzcGVjdFJhdGlvPSJ4TWlkWU1pZCI+PHBhdGggZD0iTTEyOC4wMDEuNjY3QzU3LjMxMS42NjcgMCA1Ny45NzEgMCAxMjguNjY0YzAgNzAuNjkgNTcuMzExIDEyNy45OTggMTI4LjAwMSAxMjcuOTk4UzI1NiAxOTkuMzU0IDI1NiAxMjguNjY0QzI1NiA1Ny45NyAxOTguNjg5LjY2NyAxMjguMDAxLjY2N3ptMCAyMzkuNTZjLTIwLjExMiAwLTM2LjQxOS0xMy40MzUtMzYuNDE5LTMwLjAwNGg3Mi44MzhjMCAxNi41NjYtMTYuMzA2IDMwLjAwNC0zNi40MTkgMzAuMDA0em02MC4xNTMtMzkuOTRINjcuODQyVjE3OC40N2gxMjAuMzE0djIxLjgxNmgtLjAwMnptLS40MzItMzMuMDQ1SDY4LjE4NWMtLjM5OC0uNDU4LS44MDQtLjkxLTEuMTg4LTEuMzc1LTEyLjMxNS0xNC45NTQtMTUuMjE2LTIyLjc2LTE4LjAzMi0zMC43MTYtLjA0OC0uMjYyIDE0LjkzMyAzLjA2IDI1LjU1NiA1LjQ1IDAgMCA1LjQ2NiAxLjI2NSAxMy40NTggMi43MjItNy42NzMtOC45OTQtMTIuMjMtMjAuNDI4LTEyLjIzLTMyLjExNiAwLTI1LjY1OCAxOS42OC00OC4wNzkgMTIuNTgtNjYuMjAxIDYuOTEuNTYyIDE0LjMgMTQuNTgzIDE0LjggMzYuNTA1IDcuMzQ2LTEwLjE1MiAxMC40Mi0yOC42OSAxMC40Mi00MC4wNTYgMC0xMS43NjkgNy43NTUtMjUuNDQgMTUuNTEyLTI1LjkwNy02LjkxNSAxMS4zOTYgMS43OSAyMS4xNjUgOS41MyA0NS40IDIuOTAyIDkuMTAzIDIuNTMyIDI0LjQyMyA0Ljc3MiAzNC4xMzguNzQ0LTIwLjE3OCA0LjIxMy00OS42MiAxNy4wMTQtNTkuNzg0LTUuNjQ3IDEyLjguODM2IDI4LjgxOCA1LjI3IDM2LjUxOCA3LjE1NCAxMi40MjQgMTEuNDkgMjEuODM2IDExLjQ5IDM5LjYzOCAwIDExLjkzNi00LjQwNyAyMy4xNzMtMTEuODQgMzEuOTU4IDguNDUyLTEuNTg2IDE0LjI4OS0zLjAxNiAxNC4yODktMy4wMTZsMjcuNDUtNS4zNTVjLjAwMi0uMDAyLTMuOTg3IDE2LjQwMS0xOS4zMTQgMzIuMTk3eiIgZmlsbD0iI0RBNEUzMSIvPjwvc3ZnPg==
43+
mediatype: image/svg+xml
44+
45+
maturity: beta
46+
version: 0.22.2
47+
48+
customresourcedefinitions:
49+
owned:
50+
- name: prometheuses.monitoring.coreos.com
51+
version: v1
52+
kind: Prometheus
53+
displayName: Prometheus
54+
description: A running Prometheus instance
55+
resources:
56+
- kind: StatefulSet
57+
version: v1beta2
58+
- kind: Pod
59+
version: v1
60+
specDescriptors:
61+
- description: Desired number of Pods for the cluster
62+
displayName: Size
63+
path: replicas
64+
x-descriptors:
65+
- 'urn:alm:descriptor:com.tectonic.ui:podCount'
66+
- description: A selector for the ConfigMaps from which to load rule files
67+
displayName: Rule Config Map Selector
68+
path: ruleSelector
69+
x-descriptors:
70+
- 'urn:alm:descriptor:com.tectonic.ui:selector:core:v1:ConfigMap'
71+
- description: ServiceMonitors to be selected for target discovery
72+
displayName: Service Monitor Selector
73+
path: serviceMonitorSelector
74+
x-descriptors:
75+
- 'urn:alm:descriptor:com.tectonic.ui:selector:monitoring.coreos.com:v1:ServiceMonitor'
76+
- description: The ServiceAccount to use to run the Prometheus pods
77+
displayName: Service Account
78+
path: serviceAccountName
79+
x-descriptors:
80+
- 'urn:alm:descriptor:io.kubernetes:ServiceAccount'
81+
- description: Limits describes the minimum/maximum amount of compute resources required/allowed
82+
displayName: Resource Requirements
83+
path: resources
84+
x-descriptors:
85+
- 'urn:alm:descriptor:com.tectonic.ui:resourceRequirements'
86+
- name: prometheusrules.monitoring.coreos.com
87+
version: v1
88+
kind: PrometheusRule
89+
displayName: Prometheus Rule
90+
description: A Prometheus Rule configures groups of sequentially evaluated recording and alerting rules.
91+
- name: servicemonitors.monitoring.coreos.com
92+
version: v1
93+
kind: ServiceMonitor
94+
displayName: Service Monitor
95+
description: Configures prometheus to monitor a particular k8s service
96+
resources:
97+
- kind: Pod
98+
version: v1
99+
specDescriptors:
100+
- description: The label to use to retrieve the job name from
101+
displayName: Job Label
102+
path: jobLabel
103+
x-descriptors:
104+
- 'urn:alm:descriptor:com.tectonic.ui:label'
105+
- description: A list of endpoints allowed as part of this ServiceMonitor
106+
displayName: Endpoints
107+
path: endpoints
108+
x-descriptors:
109+
- 'urn:alm:descriptor:com.tectonic.ui:endpointList'
110+
- name: alertmanagers.monitoring.coreos.com
111+
version: v1
112+
kind: Alertmanager
113+
displayName: Alertmanager
114+
description: Configures an Alertmanager for the namespace
115+
resources:
116+
- kind: StatefulSet
117+
version: v1beta2
118+
- kind: Pod
119+
version: v1
120+
specDescriptors:
121+
- description: Desired number of Pods for the cluster
122+
displayName: Size
123+
path: replicas
124+
x-descriptors:
125+
- 'urn:alm:descriptor:com.tectonic.ui:podCount'
126+
- description: Limits describes the minimum/maximum amount of compute resources required/allowed
127+
displayName: Resource Requirements
128+
path: resources
129+
x-descriptors:
130+
- 'urn:alm:descriptor:com.tectonic.ui:resourceRequirements'

0 commit comments

Comments
 (0)