Skip to content

Commit a62bd68

Browse files
michaelryanpetermichaelryanpeter
committed
OSDOCS#8863 & 8864: Version range comparison strings
1 parent e1f20ad commit a62bd68

File tree

3 files changed

+166
-0
lines changed

3 files changed

+166
-0
lines changed

‎modules/olmv1-version-range-comparisons.adoc

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
7+
[id="olmv1-version-range-comparisons_{context}"]
8+
= Version comparison strings
9+
10+
You can define a version range by adding a comparison string to the `spec.version` field in an Operator or extension's custom resource (CR). A comparison string is a list of space- or comma-separated values and one or more comparison operators. You can add another comparison string by including an `OR`, or double vertical bar (`||`), comparison operator between the strings.
11+
12+
.Basic comparisons
13+
[options="header"]
14+
|===
15+
16+
|Comparison operator |Definition
17+
18+
|`=`
19+
|Equal to
20+
21+
|`!=`
22+
|Not equal to
23+
24+
|`>`
25+
|Greater than
26+
27+
| `<`
28+
|Less than
29+
30+
|`>=`
31+
|Greater than or equal to
32+
33+
|`\<=`
34+
|Less than or equal to
35+
36+
|===
37+
38+
You can specify a version range in an Operator or extension's CR by using a range comparison similar to the following example:
39+
40+
.Example version range comparison
41+
[source,yaml]
42+
----
43+
apiVersion: operators.operatorframework.io/v1alpha1
44+
kind: Operator
45+
metadata:
46+
name: pipelines-operator
47+
spec:
48+
packageName: openshift-pipelines-operator-rh
49+
version: >=1.11, <1.13
50+
----
51+
52+
You can use wildcard characters in all types of comparison strings. {olmv1} accepts `x`, `X`, and asterisks (`*`) as wildcard characters. When you use a wildcard character with the equal sign (`=`) comparison operator, you define a comparison at the patch or minor version level.
53+
54+
.Example wildcard characters in comparison strings
55+
[options="header"]
56+
|===
57+
58+
|Wildcard comparison |Matching string
59+
60+
|`1.11.x`
61+
|`>=1.11.0, <1.12.0`
62+
63+
|`>=1.12.X`
64+
|`>=1.12.0`
65+
66+
|`\<=2.x`
67+
|`<3`
68+
69+
|`*`
70+
|`>=0.0.0`
71+
72+
|===
73+
74+
You can make patch release comparisons by using the tilde (`~`) comparison operator. Patch release comparisons specify a minor version up to the next major version.
75+
76+
.Example patch release comparisons
77+
[options="header"]
78+
|===
79+
80+
|Patch release comparison |Matching string
81+
82+
|`~1.11.0`
83+
|`>=1.11.0, <1.12.0`
84+
85+
|`~1`
86+
|`>=1, <2`
87+
88+
|`~1.12`
89+
|`>=1.12, <1.13`
90+
91+
|`~1.12.x`
92+
|`>=1.12.0, <1.13.0`
93+
94+
|`~1.x`
95+
|`>=1, <2`
96+
97+
|===
98+
99+
You can use the caret (`^`) comparison operator to make a comparison for a major release. If you use a major release comparison before the first stable release is published, the minor versions define the API's level of stability. In the semantic versioning (SemVer) specification, the first stable release is published as the `1.0.0` version.
100+
101+
.Example major release comparisons
102+
[options="header"]
103+
|===
104+
105+
|Major release comparison |Matching string
106+
107+
|`^0`
108+
|`>=0.0.0, <1.0.0`
109+
110+
|`^0.0`
111+
|`>=0.0.0, <0.1.0`
112+
113+
|`^0.0.3`
114+
|`>=0.0.3, <0.0.4`
115+
116+
|`^0.2`
117+
|`>=0.2.0, <0.3.0`
118+
119+
|`^0.2.3`
120+
|`>=0.2.3, <0.3.0`
121+
122+
|`^1.2.x`
123+
|`>= 1.2.0, < 2.0.0`
124+
125+
|`^1.2.3`
126+
|`>= 1.2.3, < 2.0.0`
127+
128+
|`^2.x`
129+
|`>= 2.0.0, < 3`
130+
131+
|`^2.3`
132+
|`>= 2.3, < 3`
133+
134+
|===

‎modules/olmv1-version-range-support.adoc

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
7+
[id="olmv1-version-range-support_{context}"]
8+
= Support for version ranges
9+
10+
In {olmv1-first}, you can specify a version range by using a comparison string in an Operator or extension's custom resource (CR). If you specify a version range in the CR, {olmv1} installs or updates to the latest version of the Operator that can be resolved within the version range.
11+
12+
.Resolved version workflow
13+
* The resolved version is the latest version of the Operator that satisfies the dependencies and constraints of the Operator and the environment.
14+
* An Operator update within the specified range is automatically installed if it is resolved successfully.
15+
* An update is not installed if it is outside of the specified range or if it cannot be resolved successfully.
16+
17+
For more information about dependency and constraint resolution in {olmv1}, see "Dependency resolution in {olmv1}".

‎operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,5 +57,20 @@ include::modules/olmv1-finding-operators-to-install.adoc[leveloffset=+1]
5757
include::modules/olmv1-catalog-queries.adoc[leveloffset=+2]
5858

5959
include::modules/olmv1-about-target-versions.adoc[leveloffset=+1]
60+
include::modules/olmv1-version-range-support.adoc[leveloffset=+2]
61+
62+
[role="_additional-resources"]
63+
.Additional resources
64+
* xref:../../operators/olm_v1/arch/olmv1-dependency.adoc#olmv1-dependency[Dependency resolution in OLM 1.0]
65+
66+
include::modules/olmv1-version-range-comparisons.adoc[leveloffset=+2]
67+
68+
include::modules/olmv1-installing-an-operator.adoc[leveloffset=+1]
69+
70+
[role="_additional-resources"]
71+
.Additional resources
72+
* xref:../../operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc#olmv1-about-operator-updates_olmv1-installing-operator[About target versions in OLM 1.0]
73+
* xref:../../operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc#olmv1-version-range-support_olmv1-installing-operator[Support for version ranges]
74+
6075
include::modules/olmv1-updating-an-operator.adoc[leveloffset=+1]
6176
include::modules/olmv1-deleting-an-operator.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)