Skip to content

Commit 9e7cd7c

Browse files
adellapeadellape
committed
OSDOCS-2940/2941: OLM arbitrary prop & compound constraints
1 parent 7899771 commit 9e7cd7c

7 files changed

+289
-37
lines changed

‎modules/olm-bundle-format-dependencies-file.adoc

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

‎modules/olm-dependencies.adoc

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/understanding/olm-packaging-format.adoc
4+
// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc
5+
6+
:_content-type: CONCEPT
7+
[id="olm-dependencies_{context}"]
8+
ifeval::["{context}" == "olm-packaging-format"]
9+
= Dependencies
10+
endif::[]
11+
ifeval::["{context}" != "olm-packaging-format"]
12+
= Operator dependencies
13+
endif::[]
14+
15+
The dependencies of an Operator are listed in a `dependencies.yaml` file in the `metadata/` folder of a bundle. This file is optional and currently only used to specify explicit Operator-version dependencies.
16+
17+
The dependency list contains a `type` field for each item to specify what kind of dependency this is. The following types of Operator dependencies are supported:
18+
19+
`olm.package`:: This type indicates a dependency for a specific Operator version. The dependency information must include the package name and the version of the package in semver format. For example, you can specify an exact version such as `0.5.2` or a range of versions such as `>0.5.1`.
20+
21+
`olm.gvk`:: With this type, the author can specify a dependency with group/version/kind (GVK) information, similar to existing CRD and API-based usage in a CSV. This is a path to enable Operator authors to consolidate all dependencies, API or explicit versions, to be in the same place.
22+
23+
`olm.constraint`:: This type declares generic constraints on arbitrary Operator properties.
24+
25+
In the following example, dependencies are specified for a Prometheus Operator and etcd CRDs:
26+
27+
.Example `dependencies.yaml` file
28+
[source,yaml]
29+
----
30+
dependencies:
31+
- type: olm.package
32+
value:
33+
packageName: prometheus
34+
version: ">0.27.0"
35+
- type: olm.gvk
36+
value:
37+
group: etcd.database.coreos.com
38+
kind: EtcdCluster
39+
version: v1beta2
40+
----

‎modules/olm-dependency-resolution-about.adoc

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,19 @@
66
[id="olm-dependency-resolution-about_{context}"]
77
= About dependency resolution
88

9-
OLM manages the dependency resolution and upgrade lifecycle of running Operators. In many ways, the problems OLM faces are similar to other operating system package managers like `yum` and `rpm`.
9+
Operator Lifecycle Manager (OLM) manages the dependency resolution and upgrade lifecycle of running Operators. In many ways, the problems OLM faces are similar to other system or language package managers, such as `yum` and `rpm`.
1010

1111
However, there is one constraint that similar systems do not generally have that OLM does: because Operators are always running, OLM attempts to ensure that you are never left with a set of Operators that do not work with each other.
1212

13-
This means that OLM must never do the following:
13+
As a result, OLM must never create the following scenarios:
1414

15-
- Install a set of Operators that require APIs that cannot be provided.
16-
- Update an Operator in a way that breaks another that depends upon it.
15+
- Install a set of Operators that require APIs that cannot be provided
16+
- Update an Operator in a way that breaks another that depends upon it
17+
18+
This is made possible with two types of data:
19+
20+
[horizontal]
21+
Properties:: Typed metadata about the Operator that constitutes the public interface for it in the dependency resolver. Examples include the group/version/kind (GVK) of the APIs provided by the Operator and the semantic version (semver) of the Operator.
22+
Constraints or dependencies:: An Operator's requirements that should be satisfied by other Operators that might or might not have already been installed on the target cluster. These act as queries or filters over all available Operators and constrain the selection during dependency resolution and installation. Examples include requiring a specific API to be available on the cluster or expecting a particular Operator with a particular version to be installed.
23+
24+
OLM converts these properties and constraints into a system of Boolean formulas and passes them to a SAT solver, a program that establishes Boolean satisfiability, which does the work of determining what Operators should be installed.

‎modules/olm-generic-constraints.adoc

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="olm-generic-constraints_{context}"]
7+
= Generic constraints
8+
9+
An `olm.constraint` property declares a dependency constraint of a particular type, differentiating non-constraint and constraint properties. Its `value` field is an object containing a `failureMessage` field holding a string-representation of the constraint message. This message is surfaced as an informative comment to users if the constraint is not satisfiable at runtime.
10+
11+
The following keys denote the available constraint types:
12+
13+
`gvk`:: Type whose value and interpretation is identical to the `olm.gvk` type
14+
15+
`package`:: Type whose value and interpretation is identical to the `olm.package` type
16+
17+
`cel`:: A Common Expression Language (CEL) expression evaluated at runtime by the Operator Lifecycle Manager (OLM) resolver over arbitrary bundle properties and cluster information
18+
19+
`all`, `any`, `not`:: Conjunction, disjunction, and negation constraints, respectively, containing one or more concrete constraints, such as `gvk` or a nested compound constraint
20+
21+
[id="olm-cel_{context}"]
22+
== Common Expression Language (CEL) constraints
23+
24+
The `cel` constraint type supports link:https://github.com/google/cel-go[Common Expression Language (CEL)] as the expression language. The `cel` struct has a `rule` field which contains the CEL expression string that is evaluated against Operator properties at runtime to determine if the Operator satisfies the constraint.
25+
26+
.Example `cel` constraint
27+
[source,yaml]
28+
----
29+
type: olm.constraint
30+
value:
31+
failureMessage: 'require to have "certified"'
32+
cel:
33+
rule: 'properties.exists(p, p.type == "certified")'
34+
----
35+
36+
The CEL syntax supports a wide range of logical operators, such as `AND` and `OR`. As a result, a single CEL expression can have multiple rules for multiple conditions that are linked together by these logical operators. These rules are evaluated against a dataset of multiple different properties from a bundle or any given source, and the output is solved into a single bundle or Operator that satisfies all of those rules within a single constraint.
37+
38+
.Example `cel` constraint with multiple rules
39+
[source,yaml]
40+
----
41+
type: olm.constraint
42+
value:
43+
failureMessage: 'require to have "certified" and "stable" properties'
44+
cel:
45+
rule: 'properties.exists(p, p.type == "certified") && properties.exists(p, p.type == "stable")'
46+
----
47+
48+
[id="olm-compound-constraints_{context}"]
49+
== Compound constraints (all, any, not)
50+
51+
Compound constraint types are evaluated following their logical definitions.
52+
53+
The following is an example of a conjunctive constraint (`all`) of two packages and one GVK. That is, they must all be satisfied by installed bundles:
54+
55+
.Example `all` constraint
56+
[source,yaml]
57+
----
58+
schema: olm.bundle
59+
name: red.v1.0.0
60+
properties:
61+
- type: olm.constraint
62+
value:
63+
failureMessage: All are required for Red because...
64+
all:
65+
constraints:
66+
- failureMessage: Package blue is needed for...
67+
package:
68+
name: blue
69+
versionRange: '>=1.0.0'
70+
- failureMessage: GVK Green/v1 is needed for...
71+
gvk:
72+
group: greens.example.com
73+
version: v1
74+
kind: Green
75+
----
76+
77+
The following is an example of a disjunctive constraint (`any`) of three versions of the same GVK. That is, at least one must be satisfied by installed bundles:
78+
79+
.Example `any` constraint
80+
[source,yaml]
81+
----
82+
schema: olm.bundle
83+
name: red.v1.0.0
84+
properties:
85+
- type: olm.constraint
86+
value:
87+
failureMessage: Any are required for Red because...
88+
any:
89+
constraints:
90+
- gvk:
91+
group: blues.example.com
92+
version: v1beta1
93+
kind: Blue
94+
- gvk:
95+
group: blues.example.com
96+
version: v1beta2
97+
kind: Blue
98+
- gvk:
99+
group: blues.example.com
100+
version: v1
101+
kind: Blue
102+
----
103+
104+
The following is an example of a negation constraint (`not`) of one version of a GVK. That is, this GVK cannot be provided by any bundle in the result set:
105+
106+
.Example `not` constraint
107+
[source,yaml]
108+
----
109+
schema: olm.bundle
110+
name: red.v1.0.0
111+
properties:
112+
- type: olm.constraint
113+
value:
114+
all:
115+
constraints:
116+
- failureMessage: Package blue is needed for...
117+
package:
118+
name: blue
119+
versionRange: '>=1.0.0'
120+
- failureMessage: Cannot be required for Red because...
121+
not:
122+
constraints:
123+
- gvk:
124+
group: greens.example.com
125+
version: v1alpha1
126+
kind: greens
127+
----
128+
129+
The negation semantics might appear unclear in the `not` constraint context. To clarify, the negation is really instructing the resolver to remove any possible solution that includes a particular GVK, package at a version, or satisfies some child compound constraint from the result set.
130+
131+
As a corollary, the `not` compound constraint should only be used within `all` or `any` constraints, because negating without first selecting a possible set of dependencies does not make sense.
132+
133+
[id="olm-nested-compound_{context}"]
134+
== Nested compound constraints
135+
136+
A nested compound constraint, one that contains at least one child compound constraint along with zero or more simple constraints, is evaluated from the bottom up following the procedures for each previously described constraint type.
137+
138+
The following is an example of a disjunction of conjunctions, where one, the other, or both can satisfy the constraint:
139+
140+
.Example nested compound constraint
141+
[source,yaml]
142+
----
143+
schema: olm.bundle
144+
name: red.v1.0.0
145+
properties:
146+
- type: olm.constraint
147+
value:
148+
failureMessage: Required for Red because...
149+
any:
150+
constraints:
151+
- all:
152+
constraints:
153+
- package:
154+
name: blue
155+
versionRange: '>=1.0.0'
156+
- gvk:
157+
group: blues.example.com
158+
version: v1
159+
kind: Blue
160+
- all:
161+
constraints:
162+
- package:
163+
name: blue
164+
versionRange: '<1.0.0'
165+
- gvk:
166+
group: blues.example.com
167+
version: v1beta1
168+
kind: Blue
169+
----
170+
171+
[NOTE]
172+
====
173+
The maximum raw size of an `olm.constraint` type is 64KB to limit resource exhaustion attacks.
174+
====

‎modules/olm-properties.adoc

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="olm-properties_{context}"]
7+
ifeval::["{context}" == "olm-packaging-format"]
8+
= Properties
9+
endif::[]
10+
ifeval::["{context}" != "olm-packaging-format"]
11+
= Operator properties
12+
endif::[]
13+
14+
All Operators in a catalog have the following properties:
15+
16+
`olm.package`:: Includes the name of the package and the version of the Operator
17+
18+
`olm.gvk`:: A single property for each provided API from the cluster service version (CSV)
19+
20+
Additional properties can also be directly declared by an Operator author by including a `properties.yaml` file in the `metadata/` directory of the Operator bundle.
21+
22+
.Example arbitrary property
23+
[source,yaml]
24+
----
25+
properties:
26+
- type: olm.kubeversion
27+
value:
28+
version: "1.16.0"
29+
----
30+
31+
[id="olm-arbitrary-properties_{context}"]
32+
== Arbitrary properties
33+
34+
Operator authors can declare arbitrary properties in a `properties.yaml` file in the `metadata/` directory of the Operator bundle. These properties are translated into a map data structure that is used as an input to the Operator Lifecycle Manager (OLM) resolver at runtime.
35+
36+
These properties are opaque to the resolver as it does not understand the properties, but it can evaluate the generic constraints against those properties to determine if the constraints can be satisfied given the properties list.
37+
38+
.Example arbitrary properties
39+
[source,yaml]
40+
----
41+
properties:
42+
- property:
43+
type: color
44+
value: red
45+
- property:
46+
type: shape
47+
value: square
48+
- property:
49+
type: olm.gvk
50+
value:
51+
group: olm.coreos.io
52+
version: v1alpha1
53+
kind: myresource
54+
----
55+
56+
This structure can be used to construct a Common Expression Language (CEL) expression for generic constraints.

‎operators/understanding/olm-packaging-format.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Support for the legacy _package manifest format_ for Operators is removed in {pr
1515
//Consider updating this during the 4.10 to 4.11 version scrub.
1616

1717
include::modules/olm-bundle-format.adoc[leveloffset=+1]
18-
include::modules/olm-bundle-format-dependencies-file.adoc[leveloffset=+2]
18+
include::modules/olm-dependencies.adoc[leveloffset=+2]
1919

2020
[role="_additional-resources"]
2121
.Additional resources

‎operators/understanding/olm/olm-understanding-dependency-resolution.adoc

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,12 @@ toc::[]
99
This guide outlines dependency resolution and custom resource definition (CRD) upgrade lifecycles with Operator Lifecycle Manager (OLM) in {product-title}.
1010

1111
include::modules/olm-dependency-resolution-about.adoc[leveloffset=+1]
12-
include::modules/olm-bundle-format-dependencies-file.adoc[leveloffset=+1]
12+
include::modules/olm-properties.adoc[leveloffset=+1]
13+
.Additional resources
14+
* xref:../../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-cel_olm-understanding-dependency-resolution[Common Expression Language (CEL) constraints]
15+
16+
include::modules/olm-dependencies.adoc[leveloffset=+1]
17+
include::modules/olm-generic-constraints.adoc[leveloffset=+1]
1318
include::modules/olm-dependency-resolution-preferences.adoc[leveloffset=+1]
1419
include::modules/olm-dependency-resolution-crd-upgrades.adoc[leveloffset=+1]
1520

0 commit comments

Comments
 (0)