Skip to content

Commit f0cdb20

Browse files
fhennigfhennig
authored
Merge branch 'main' into lb-operator-adr
2 parents 85cacac + 4ec3ef5 commit f0cdb20

File tree

2 files changed

+187
-0
lines changed

2 files changed

+187
-0
lines changed

‎modules/contributor/pages/adr/ADR023-product-image-selection.adoc

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
= ADR023: Product image selection
2+
Maxi Wittich <maximilian.wittich@stackable.tech>, Sebastian Bernauer <sebastian.bernauer@stackable.tech>
3+
v0.1, 2022-08-31
4+
:status: accepted
5+
6+
* Deciders:
7+
** Malte Sander
8+
** Sebastian Bernauer
9+
** Felix Henning
10+
** Maximilian Wittich
11+
** Lars Francke
12+
* Date: 2022-08-31
13+
14+
== Context and Problem Statement
15+
Currently users have to specify the full image tag in the Products CRD.
16+
17+
[source,yaml]
18+
----
19+
spec:
20+
version: 1.4.1-stackable2.1.0
21+
----
22+
23+
This must be a tag belonging to an image from the stackable repository. In order to give the user the opportunity to provide a own repository, mirror our repository or provide a complete own image, we'd like to propose a solution for it.
24+
25+
== Decision Drivers
26+
27+
* Flexible and extendable solution for possible use cases
28+
* Preserve the possibility of magic version completion of operators for images (e.g. `superset:1.4.1` => `superset:1.4.1-stackable2.1.0`)
29+
* Allow the user to easily paste in a complete image name
30+
* Allow users to use some defaults, allow them to only override certain things
31+
32+
In detail we used the following use-cases to drive the decision:
33+
34+
* use Stackable repo
35+
** users specified version 1.4.1-stackable2.1.0
36+
=> operator should use image docker.stackable.tech/stackable/superset:1.4.1-stackable2.1.0
37+
** users specified version 1.4.1
38+
=> operator should use image docker.stackable.tech/stackable/superset:1.4.1-stackable2.1.0 based on compatibility knowledge (which operator works with which image)
39+
** users specifies no version
40+
=> operator should use image docker.stackable.tech/stackable/superset:1.4.1-stackable2.1.0 based on recommended product version of the release/operator and knowledge (which operator works with which image)
41+
42+
* use self-hosted (mirrored) repo
43+
** users specified version 1.4.1-stackable2.1.0 and imageRepository my.corp/superset
44+
=> operator should use image my.corp/superset:1.4.1-stackable2.1.0 based on imageRepository
45+
=> Equivalent to user saying use the image "my.corp/superset:1.4.1-stackable2.1.0"
46+
** users specified version 1.4.1 and imageRepository my.corp/superset
47+
=> operator should use image my.corp/superset:1.4.1-stackable2.1.0 based on imageRepository and compatibility knowledge (which operator works with which image)
48+
=> Equivalent to user saying use the image "my.corp/superset:1.4.1-stackable2.1.0"
49+
=> NOT equivalent to user saying use the image "my.corp/superset:1.4.1"
50+
=> When specifying the image directly users loose the ability to let the operator determine its compatible stackable image version
51+
** user just specifies a repo: my.corp/superset with no versions -> operator should use image my.corp/superset:1.4.1-stackable2.1.0 based on recommended product version of the release/operator and knowledge (which operator works with which image)
52+
53+
54+
== Decision Outcome
55+
56+
Chosen option: "<<option6,Option 6>>" because it is the only option to cover all use cases.
57+
58+
== Pros and Cons of the Options
59+
60+
=== Option 1
61+
[source,yaml]
62+
----
63+
version: 1.4.1-stackable2.1.0 # optional (currently operator will error out but in the future according to ADR 18 operator should pick a good version automatically)
64+
imageRepository: docker.stackable.tech/stackable/superset # Option<String>
65+
----
66+
67+
* Good, because it's non-breaking
68+
* Good, because users can specify `version: 1.4.1` and the operator will resolve it to `1.4.1-stackable2.1.0` (or whatever stackable versions works for *him*). This mechanism continues working. For this to work the customers needs to mirror the exact same tags as we at Stackable have (he can't rename the tags).
69+
70+
=== Option 2
71+
[source,yaml]
72+
----
73+
version: 1.4.1-stackable2.1.0 # optional (currently operator will error out but in the future according to ADR 18 operator should pick a good version automatically)
74+
image: docker.stackable.tech/stackable/superset:1.4.1-stackable2.1.0 # Option<String>. Will overwrite version (if specified)
75+
----
76+
77+
* Good, because it's non-breaking because mechanism from Option 1 is not implemented yet
78+
* Bad, because mechanism explain in Option 1 breaks.
79+
80+
=== Option 3
81+
[source,yaml]
82+
----
83+
image:
84+
version: 1.4.1-stackable2.1.0 # optional (currently operator will error out but in the future according to ADR 18 operator should pick a good version automatically)
85+
imageRepository: docker.stackable.tech/stackable/superset # Option<String>
86+
----
87+
88+
* Bad, because it's breaking
89+
* Bad, because versions can only contain the product version (e.g. `1.4.1`). Having this "hidden" under image may seem like an implementation detail to the user. It can be argued that version is important enough to be a top-level field.
90+
91+
=== Option 4
92+
[source,yaml]
93+
----
94+
version: 1.4.1-stackable2.1.0 # optional (currently operator will error out but in the future according to ADR 18 operator should pick a good version automatically)
95+
imageOverwrite: # Option<struct>
96+
repository: docker.stackable.tech/stackable/superset # String
97+
tag: 1.4.1-stackable2.1.0 # Option<String>. Will overwrite tag (the specified version is ignored/overwritten)
98+
----
99+
100+
* Good, because it's non-breaking
101+
* Good, because when only `imageOverwrite.repository` is specified, it's the same as option 1 with all the benefits
102+
* Good, because when `imageOverwrite.repository` and `imageOverwrite.tag` is specified, it's the same as option 2 with all the benefits
103+
104+
[[option5]]
105+
=== Option 5
106+
[source,yaml]
107+
----
108+
image: # mandatory complex enum
109+
stackableImageTag: 1.4.1-stackable2.1.0 # String
110+
# OR
111+
custom: docker.stackable.tech/stackable/superset:1.4.1-stackable2.1.0 # String
112+
# OR (later on)
113+
stackableVersion: 1.4.1 # String
114+
# OR (later on)
115+
recommendedVersion: true # needs to be set to true. if set to false operator will error out
116+
----
117+
118+
We want to start with the first two variants `stackableImageTag` and `custom`. The `magicVersionResolving` and `recommendedVersion` variants _might_ be added later on.
119+
120+
* Bad, because it's breaking
121+
* Good, because it gives all flexibility of all previous options
122+
* Good, because we can non-breaking introduce new "magic" in the future by adding new image enum variants
123+
* Good, because we can implement it as enum called e.g. `ImageSpec` in operator-rs which will offer a function like `resolve_image` that will make it easy for operators to use
124+
125+
[[option6]]
126+
=== Option 6
127+
128+
This option is **breaking**. It uses a complex enum, similar to Option 5. Option 5 does not account for the need to specify the product version with a custom image. It is also not possible to just use a custom docker repository and still use the operator recommended version (i.e. just mirroring the stackable repository). This option makes that possible. We first start with implementing `stackableVersion` and `custom`. The `stackable` enum variant will be implemented as soon as we have the magic stackableVersion resolution.
129+
130+
[source,yaml]
131+
----
132+
image: # complex enum
133+
stackableVersion: # (1)
134+
repo: docker.stackable.tech # String. Defaults to docker.stackable.tech (kind of optional).
135+
productVersion: 1.4.1 # mandatory
136+
stackableVersion: stackable2.1.0 # mandatory
137+
# OR
138+
stackable: # (2)
139+
repo: docker.stackable.tech # String. Defaults to docker.stackable.tech (kind of optional).
140+
productVersion: 1.4.1 # Option<String>. If not specified use recommended product version ("magic").
141+
# OR
142+
custom: # (3)
143+
productVersion: 1.4.1
144+
custom: docker.stackable.tech/stackable/superset:1.4.1-stackable2.1
145+
146+
pullPolicy: IfNotPresent
147+
pullSecrets: # Option<Vec<LocalObjectReference>>
148+
name: regcred # reference to secret in same namespace
149+
----
150+
151+
**Known issues**: We will start to implement our own schema since kube-rs is not supporting flatten yet.
152+
153+
**Use-case**: I don't want to specify anything, just give me defaults!
154+
155+
-> Don't specify anything.
156+
157+
**Use-case**: I want a specific version of the product:
158+
159+
[source,yaml]
160+
----
161+
image:
162+
productVersion: 1.5.1
163+
----
164+
165+
This resolves to the enum variant 2, with just the product version specified
166+
167+
**Use-case**: I've mirrored the stackable repo locally, but want to use automatic image resolution:
168+
169+
[source,yaml]
170+
----
171+
image:
172+
repo: my.repo.company.org/stackable
173+
----
174+
175+
This resolves to variant 2.
176+
177+
**Use-case**: I have built my own custom image with i.e. additional dependencies for the product, which has a different tag than the original stackable image. I've uploaded it to my custom repo:
178+
179+
[source,yaml]
180+
----
181+
image:
182+
custom: my.repo.company.org/stackable/superset:my-custom-tag
183+
productVersion: 1.4.1
184+
----
185+
186+
This resolves to enum variant 3. The product version is mandatory so the operator knows what to do.

‎modules/contributor/partials/current_adrs.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,5 @@
1919
**** xref:adr/ADR020-trino_catalog_usage.adoc[]
2020
**** xref:adr/ADR021-stackablectl_stacks_inital_version.adoc[]
2121
**** xref:adr/ADR022-spark-history-server.adoc[]
22+
**** xref:adr/ADR023-product-image-selection.adoc[]
2223
**** xref:adr/ADR024-out-of-cluster_access.adoc[]

0 commit comments

Comments
 (0)