Skip to content

Commit 1e6c7a7

Browse files
grokspawngrokspawn
authored
- implement opm alpha render-veneer semver (#948)
Signed-off-by: Jordan Keister <[email protected]> Signed-off-by: Ankita Thomas <[email protected]>
1 parent ad7e7ac commit 1e6c7a7

File tree

8 files changed

+1389
-3
lines changed

8 files changed

+1389
-3
lines changed

Diff for: ‎alpha/veneer/semver/README.md

+242
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
## Semver Veneer:
2+
3+
Since a `veneer` is identified as an input schema which may be processed to generate a valid FBC, we can define a `semver veneer` as a schema which uses channel conventions to facilitate the auto-generation of channels along `semver` delimiters.
4+
5+
[**DISCLAIMER:** since version build metadata [MUST be ignored when determining version precedence](https://semver.org) when using semver, it cannot be used in any bundle included in the `semver veneer` and will result in a fatal error.]
6+
7+
### Schema Goals
8+
The `semver veneer` must have:
9+
- terse grammar to minimize creation/maintenance effort
10+
- deterministic output
11+
- simple channel promotion for maturing bundles
12+
- demonstration of a common type of channel maturity model
13+
- minor-version (Y-stream), major-version (X-stream) versioning optionality
14+
15+
The resulting FBC must clearly indicate how generated channels relate to veneer entities
16+
17+
### Schema Anatomy
18+
For convenience and simplicity, this veneer currently supports hard-coded channel names `Candidate`, `Fast`, and `Stable`, in order of increasing channel stability. We leverage this relationship to calculate the default channel for the package.
19+
20+
`GenerateMajorChannels` and `GenerateMinorChannels` dictate whether this veneer will generate X-stream or Y-stream channels (attributes can be set independently). If omitted, only minor (Y-stream) channels will be generated.
21+
22+
Under each channel are a list of bundle image references which contribute to that channel.
23+
24+
With the following (hypothetical) example we define a mock bundle which has 11 versions, represented across each of the channel types:
25+
```yaml
26+
Schema: olm.semver
27+
GenerateMajorChannels: true
28+
GenerateMinorChannels: true
29+
Candidate:
30+
Bundles:
31+
- Image: quay.io/foo/olm:testoperator.v0.1.0
32+
- Image: quay.io/foo/olm:testoperator.v0.1.1
33+
- Image: quay.io/foo/olm:testoperator.v0.1.2
34+
- Image: quay.io/foo/olm:testoperator.v0.1.3
35+
- Image: quay.io/foo/olm:testoperator.v0.2.0
36+
- Image: quay.io/foo/olm:testoperator.v0.2.1
37+
- Image: quay.io/foo/olm:testoperator.v0.2.2
38+
- Image: quay.io/foo/olm:testoperator.v0.3.0
39+
- Image: quay.io/foo/olm:testoperator.v1.0.0
40+
- Image: quay.io/foo/olm:testoperator.v1.0.1
41+
- Image: quay.io/foo/olm:testoperator.v1.1.0
42+
Fast:
43+
Bundles:
44+
- Image: quay.io/foo/olm:testoperator.v0.2.1
45+
- Image: quay.io/foo/olm:testoperator.v0.2.2
46+
- Image: quay.io/foo/olm:testoperator.v0.3.0
47+
- Image: quay.io/foo/olm:testoperator.v1.0.1
48+
- Image: quay.io/foo/olm:testoperator.v1.1.0
49+
Stable:
50+
Bundles:
51+
- Image: quay.io/foo/olm:testoperator.v1.0.1
52+
```
53+
In this example, `Candidate` has the entire version range of bundles, `Fast` has a mix of older and more-recent versions, and `Stable` channel only has a single published entry.
54+
55+
### CLI Tool Usage
56+
```
57+
% ./bin/opm alpha render-veneer semver -h
58+
Generate a file-based catalog from a single 'semver veneer' file
59+
60+
Usage:
61+
opm alpha render-veneer semver <filename> [flags]
62+
63+
Flags:
64+
-h, --help help for semver
65+
-o, --output string Output format (json|yaml|mermaid) (default "json")
66+
67+
Global Flags:
68+
--skip-tls-verify skip TLS certificate verification for container image registries while pulling bundles
69+
--use-http use plain HTTP for container image registries while pulling bundles
70+
```
71+
With the veneer attribute `GenerateMajorChannels: true` resulting major channels from the command are (skipping the rendered bundle image output):
72+
```yaml
73+
---
74+
defaultChannel: stable-v1
75+
name: testoperator
76+
schema: olm.package
77+
---
78+
entries:
79+
- name: testoperator.v0.1.0
80+
- name: testoperator.v0.1.1
81+
- name: testoperator.v0.1.2
82+
- name: testoperator.v0.1.3
83+
skips:
84+
- testoperator.v0.1.0
85+
- testoperator.v0.1.1
86+
- testoperator.v0.1.2
87+
- name: testoperator.v0.2.0
88+
- name: testoperator.v0.2.1
89+
- name: testoperator.v0.2.2
90+
replaces: testoperator.v0.1.3
91+
skips:
92+
- testoperator.v0.2.0
93+
- testoperator.v0.2.1
94+
- name: testoperator.v0.3.0
95+
replaces: testoperator.v0.2.2
96+
name: candidate-v0
97+
package: testoperator
98+
schema: olm.channel
99+
---
100+
entries:
101+
- name: testoperator.v1.0.0
102+
- name: testoperator.v1.0.1
103+
skips:
104+
- testoperator.v1.0.0
105+
- name: testoperator.v1.1.0
106+
replaces: testoperator.v1.0.1
107+
name: candidate-v1
108+
package: testoperator
109+
schema: olm.channel
110+
---
111+
entries:
112+
- name: testoperator.v0.2.1
113+
- name: testoperator.v0.2.2
114+
skips:
115+
- testoperator.v0.2.1
116+
- name: testoperator.v0.3.0
117+
replaces: testoperator.v0.2.2
118+
name: fast-v0
119+
package: testoperator
120+
schema: olm.channel
121+
---
122+
entries:
123+
- name: testoperator.v1.0.1
124+
- name: testoperator.v1.1.0
125+
replaces: testoperator.v1.0.1
126+
name: fast-v1
127+
package: testoperator
128+
schema: olm.channel
129+
---
130+
entries:
131+
- name: testoperator.v1.0.1
132+
name: stable-v1
133+
package: testoperator
134+
schema: olm.channel
135+
```
136+
137+
We generated a channel for each veneer channel entity corresponding to each of the 0.\#.\#, 1.\#.\# major version ranges with skips to the head of the highest semver in a channel. We also generated a replaces edge to traverse across minor version transitions within each major channel. Finally, we generated an `olm.package` object, setting as default the most-stable channel head we created. This process will prefer `Stable` channel over `Fast`, over `Candidate` and then a higher bundle version over a lower version.
138+
(Please note that the naming of the generated channels indicates the digits of significance for that channel. For example, `fast-v1` is a decomposed channel of the `fast` type which contains only major versions of contributing bundles matching `v1`.)
139+
140+
For contrast, with the veneer attribute `GenerateMinorChannels: true` and running the command again (again skipping rendered bundle image output) we get a bunch more channels:
141+
```yaml
142+
---
143+
defaultChannel: stable-v1.0
144+
name: testoperator
145+
schema: olm.package
146+
---
147+
entries:
148+
- name: testoperator.v0.1.0
149+
- name: testoperator.v0.1.1
150+
- name: testoperator.v0.1.2
151+
- name: testoperator.v0.1.3
152+
skips:
153+
- testoperator.v0.1.0
154+
- testoperator.v0.1.1
155+
- testoperator.v0.1.2
156+
name: candidate-v0.1
157+
package: testoperator
158+
schema: olm.channel
159+
---
160+
entries:
161+
- name: testoperator.v0.2.0
162+
- name: testoperator.v0.2.1
163+
- name: testoperator.v0.2.2
164+
replaces: testoperator.v0.1.3
165+
skips:
166+
- testoperator.v0.2.0
167+
- testoperator.v0.2.1
168+
name: candidate-v0.2
169+
package: testoperator
170+
schema: olm.channel
171+
---
172+
entries:
173+
- name: testoperator.v0.3.0
174+
replaces: testoperator.v0.2.2
175+
name: candidate-v0.3
176+
package: testoperator
177+
schema: olm.channel
178+
---
179+
entries:
180+
- name: testoperator.v1.0.0
181+
- name: testoperator.v1.0.1
182+
skips:
183+
- testoperator.v1.0.0
184+
name: candidate-v1.0
185+
package: testoperator
186+
schema: olm.channel
187+
---
188+
entries:
189+
- name: testoperator.v1.1.0
190+
replaces: testoperator.v1.0.1
191+
name: candidate-v1.1
192+
package: testoperator
193+
schema: olm.channel
194+
---
195+
entries:
196+
- name: testoperator.v0.2.1
197+
- name: testoperator.v0.2.2
198+
skips:
199+
- testoperator.v0.2.1
200+
name: fast-v0.2
201+
package: testoperator
202+
schema: olm.channel
203+
---
204+
entries:
205+
- name: testoperator.v0.3.0
206+
replaces: testoperator.v0.2.2
207+
name: fast-v0.3
208+
package: testoperator
209+
schema: olm.channel
210+
---
211+
entries:
212+
- name: testoperator.v1.0.1
213+
name: fast-v1.0
214+
package: testoperator
215+
schema: olm.channel
216+
---
217+
entries:
218+
- name: testoperator.v1.1.0
219+
replaces: testoperator.v1.0.1
220+
name: fast-v1.1
221+
package: testoperator
222+
schema: olm.channel
223+
---
224+
entries:
225+
- name: testoperator.v1.0.1
226+
name: stable-v1.0
227+
package: testoperator
228+
schema: olm.channel
229+
230+
```
231+
Here, a channel is generated for each veneer channel which differs by minor version, and each channel has a `replaces` edge from the predecessor channel to the next-lesser minor bundle version. Please note that at no time do we transgress across major-version boundaries with the channels, to be consistent with [the semver convention](https://semver.org/) for major versions, where the purpose is to make incompatible API changes.
232+
233+
234+
### DEMOS
235+
236+
#### Major Channel Generation
237+
![`GenerateMajorChannels`](./major-version-demo.gif)
238+
239+
#### Minor Channel Generation
240+
![`GenerateMinorChannels`](./minor-version-demo.gif)
241+
242+

Diff for: ‎alpha/veneer/semver/major-version-demo.gif

1.13 MB
Loading

Diff for: ‎alpha/veneer/semver/minor-version-demo.gif

1.14 MB
Loading

0 commit comments

Comments
 (0)