Skip to content

Commit 840a709

Browse files
ecordellecordell
committed
proposal(relatedimages): combine the two previous proposals
1 parent b3e6d46 commit 840a709

File tree

2 files changed

+214
-129
lines changed

2 files changed

+214
-129
lines changed

‎Documentation/contributors/design-proposals/related-images.md

Lines changed: 0 additions & 129 deletions
This file was deleted.

‎doc/contributors/design-proposals/related-images.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Related Images
2+
3+
Status: Pending
4+
5+
Version: Alpha
6+
7+
Implementation Owner: ecordell
8+
9+
# Motivation
10+
11+
Operators often need to make use of other container images to perform their functions as operators.
12+
13+
## Proposal
14+
15+
Introduce a new field `relatedImages` to the `ClusterServiceVersion` spec.
16+
17+
### ClusterServiceVersion Spec Changes
18+
19+
A new section `relatedImages` is added to the ClusterServiceVersionSpec.
20+
21+
```yaml
22+
kind: ClusterServiceVersion
23+
metadata:
24+
name: etcd-operator
25+
spec:
26+
relatedImages:
27+
- name: default
28+
image: quay.io/coreos/etcd@sha256:12345
29+
annotation: default
30+
- name: etcd-2.1.5
31+
image: quay.io/coreos/etcd@sha256:12345
32+
- name: etcd-3.1.1
33+
image: quay.io/coreos/etcd@sha256:12345
34+
```
35+
36+
These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image.
37+
38+
```yaml
39+
kind: Deployment
40+
metadata:
41+
name: etcd-operator
42+
annotations:
43+
default: quay.io/coreos/etcd@sha256:12345
44+
olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345
45+
olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345
46+
spec:
47+
replicas: 1
48+
selector:
49+
matchLabels:
50+
name: etcd-operator
51+
template:
52+
metadata:
53+
name: etcd-operator
54+
labels:
55+
name: etcd-operator
56+
spec:
57+
serviceAccountName: etcd-operator
58+
containers:
59+
- name: etcd-operator
60+
command:
61+
- etcd-operator
62+
- --create-crd=false
63+
- --defaultImage=${DEFAULT}
64+
image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2
65+
env:
66+
- name: NAMESPACE
67+
valueFrom:
68+
fieldRef:
69+
fieldPath: metadata.namespace
70+
- name: DEFAULT
71+
valueFrom:
72+
fieldRef:
73+
fieldPath: metadata.annotations['default']
74+
```
75+
76+
### Implementation
77+
78+
#### ClusterServiceVersion Spec and Status
79+
80+
Spec needs to be updated to include the fields described above, and the openapi validation should be updated as well.
81+
82+
Note that the `name` field for related images must satisfy the annotation name conventions.
83+
84+
#### Install Strategy
85+
86+
Most of the change will take place in the install strategy; which knows how to take the deployment spec defined in a CSV and check if the cluster is up-to-date, and apply changes if needed.
87+
88+
- The install strategy will now need to know about related images.
89+
- `CheckInstalled` will check that the annotations on the operator deployments include the `relatedImages` annotations.
90+
- `Install` will also need to project the relatedImages as annotations on the deployment.
91+
92+
#### Implementation Stages
93+
94+
- [ ] API Changes
95+
- [ ] Annotation Projection on Deployments
96+
97+
### User Documentation
98+
99+
#### Associating Related Images
100+
101+
Operators often need to make use of other container images to perform their functions. For example, the etcd operator
102+
makes use of etcd container images to create etcd clusters as requested by the user.
103+
104+
To indicate that such images are used by the operator, a ClusterServiceVersion author can fill out the `relatedImages`
105+
field on the CSV spec.
106+
107+
These fields are optional, but should be filled out whenever possible. Tooling can take advantage of this information
108+
to ensure that all required images are available in the cluster.
109+
110+
```yaml
111+
kind: ClusterServiceVersion
112+
metadata:
113+
name: etcd-operator
114+
spec:
115+
relatedImages:
116+
- name: default
117+
image: quay.io/coreos/etcd@sha256:12345
118+
annotation: default
119+
- name: etcd-2.1.5
120+
image: quay.io/coreos/etcd@sha256:12345
121+
- name: etcd-3.1.1
122+
image: quay.io/coreos/etcd@sha256:12345
123+
```
124+
125+
### Operator Registry Changes
126+
127+
If a CSV includes an `relatedImages` section, images in this file are extracted during the `load` operation of a bundle into an
128+
operator-registry database. With the following rules:
129+
130+
- Images are pulled from the ClusterServiceVersion `container` definitions as if kustomize has been run over it.
131+
- Images are read from the `relatedImages section`
132+
133+
If a bundle does not include a `relatedImages` section, images are extracted from the ClusterServiceVersion `container` definitions.
134+
135+
The `Query` interface for an operator-registry database will have two new APIs:
136+
137+
```go
138+
type Query interface {
139+
// ...
140+
ListImages(ctx context.Context) ([]string, error)
141+
GetImagesForBundle(ctx context.Context, csvName string) ([]string, error)
142+
}
143+
```
144+
145+
`ListImages` will list all images in an operator-registry database.
146+
147+
148+
### Future Work
149+
150+
#### Using related images via downwardAPI
151+
152+
The related images can be consumed by the operator deployment. This may be useful if, for example, the operator
153+
and operand images are tightly coupled. The `annotation` field from the `relatedImages` is used as the name of the annotation.
154+
155+
These will be made available as annotations on the operator deployments, so that they can be used via downward API if desired. This may be particularly useful for operators that are tightly coupled to another particular image.
156+
157+
```yaml
158+
kind: Deployment
159+
metadata:
160+
name: etcd-operator
161+
annotations:
162+
default: quay.io/coreos/etcd@sha256:12345
163+
olm.relatedImage.etcd-2.1.5: quay.io/coreos/etcd@sha256:12345
164+
olm.relatedImage.etcd-3.1.1: quay.io/coreos/etcd@sha256:12345
165+
spec:
166+
replicas: 1
167+
selector:
168+
matchLabels:
169+
name: etcd-operator
170+
template:
171+
metadata:
172+
name: etcd-operator
173+
labels:
174+
name: etcd-operator
175+
spec:
176+
serviceAccountName: etcd-operator
177+
containers:
178+
- name: etcd-operator
179+
command:
180+
- etcd-operator
181+
- --create-crd=false
182+
- --defaultImage=${DEFAULT}
183+
image: quay.io/coreos/etcd-operator@sha256:c0301e4686c3ed4206e370b42de5a3bd2229b9fb4906cf85f3f30650424abec2
184+
env:
185+
- name: NAMESPACE
186+
valueFrom:
187+
fieldRef:
188+
fieldPath: metadata.namespace
189+
- name: DEFAULT
190+
valueFrom:
191+
fieldRef:
192+
fieldPath: metadata.annotations['default']
193+
```
194+
195+
#### Required Images
196+
197+
Any of the related images may be marked required. This would prevent the operator from installing if the required image is unavailable.
198+
199+
200+
```yaml
201+
kind: ClusterServiceVersion
202+
metadata:
203+
name: etcd-operator
204+
spec:
205+
relatedImages:
206+
- name: default
207+
image: quay.io/coreos/etcd@sha256:12345
208+
annotation: default
209+
required: true
210+
- name: etcd-2.1.5
211+
image: quay.io/coreos/etcd@sha256:12345
212+
- name: etcd-3.1.1
213+
image: quay.io/coreos/etcd@sha256:12345
214+
```

0 commit comments

Comments
 (0)