Skip to content

Commit 6feaa0d

Browse files
michaelryanpetermichaelryanpeter
authored
Merge pull request #88394 from michaelryanpeter/osdocs-12905-resolving-content-from-multiple-catalogs
OSDOCS#12905: Resolving content from multiple catalogs
2 parents 637127c + e3af2d7 commit 6feaa0d

8 files changed

+339
-16
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2082,6 +2082,8 @@ Topics:
20822082
File: rh-catalogs
20832083
- Name: Managing catalogs
20842084
File: managing-catalogs
2085+
- Name: Catalog content resolution
2086+
File: catalog-content-resolution
20852087
- Name: Creating catalogs
20862088
File: creating-catalogs
20872089
- Name: Disconnected environment support in OLM v1

‎extensions/catalogs/catalog-content-resolution.adoc

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="catalog-content-resolution"]
3+
= Catalog content resolution
4+
include::_attributes/common-attributes.adoc[]
5+
:context: catalog-content-resolution
6+
7+
toc::[]
8+
9+
When you specify the cluster extension you want to install in a custom resource (CR), {olmv1-first} uses catalog selection to resolve what content is installed.
10+
11+
You can perform the following actions to control the selection of catalog content:
12+
13+
* Specify labels to select the catalog.
14+
* Use match expressions to perform complex filtering across catalogs.
15+
* Set catalog priority.
16+
17+
If you do not specify any catalog selection criteria, {olmv1-first} selects an extension from any available catalog on the cluster that provides the requested package.
18+
19+
During resolution, bundles that are not deprecated are preferred over deprecated bundles by default.
20+
21+
include::modules/olmv1-catalog-selection-by-name.adoc[leveloffset=1]
22+
include::modules/olmv1-catalog-selection-by-labels-or-expressions.adoc[leveloffset=1]
23+
include::modules/olmv1-catalog-exclusion-by-labels-or-expressions.adoc[leveloffset=1]
24+
include::modules/olmv1-catalog-selection-by-priority.adoc[leveloffset=1]
25+
include::modules/olmv1-troubleshooting-catalog-selection-errors.adoc[leveloffset=1]

‎modules/olmv1-catalog-exclusion-by-labels-or-expressions.adoc

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// Module included in the following assemblies:
2+
// * extensions/catalogs/catalog-content-resolution.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
6+
[id="olmv1-catalog-exclusion-by-labels-or-expressions_{context}"]
7+
= Catalog exclusion by labels or expressions
8+
9+
You can exclude catalogs by using match expressions on metadata with the `NotIn` or `DoesNotExist` operators.
10+
11+
The following CRs add an `example.com/testing` label to the `unwanted-catalog-1` and `unwanted-catalog-2` cluster catalogs:
12+
13+
.Example cluster catalog CR
14+
[source,yaml]
15+
----
16+
apiVersion: olm.operatorframework.io/v1
17+
kind: ClusterCatalog
18+
metadata:
19+
name: unwanted-catalog-1
20+
labels:
21+
example.com/testing: "true"
22+
spec:
23+
source:
24+
type: Image
25+
image:
26+
ref: quay.io/example/content-management-a:latest
27+
----
28+
29+
.Example cluster catalog CR
30+
[source,yaml]
31+
----
32+
apiVersion: olm.operatorframework.io/v1
33+
kind: ClusterCatalog
34+
metadata:
35+
name: unwanted-catalog-2
36+
labels:
37+
example.com/testing: "true"
38+
spec:
39+
source:
40+
type: Image
41+
image:
42+
ref: quay.io/example/content-management-b:latest
43+
----
44+
45+
The following cluster extension CR excludes selection from the `unwanted-catalog-1` catalog:
46+
47+
.Example cluster extension CR that excludes a specific catalog
48+
[source,yaml]
49+
----
50+
apiVersion: olm.operatorframework.io/v1
51+
kind: ClusterExtension
52+
metadata:
53+
name: <example_extension>
54+
spec:
55+
namespace: <example_namespace>
56+
serviceAccount:
57+
name: <example_extension>-installer
58+
source:
59+
sourceType: Catalog
60+
catalog:
61+
packageName: <example_extension>-operator
62+
selector:
63+
matchExpressions:
64+
- key: olm.operatorframework.io/metadata.name
65+
operator: NotIn
66+
values:
67+
- unwanted-catalog-1
68+
----
69+
70+
The following cluster extension CR selects from catalogs that do not have the `example.com/testing` label. As a result, both `unwanted-catalog-1` and `unwanted-catalog-2` are excluded from catalog selection.
71+
72+
.Example cluster extension CR that excludes catalogs with a specific label
73+
[source,yaml]
74+
----
75+
apiVersion: olm.operatorframework.io/v1
76+
kind: ClusterExtension
77+
metadata:
78+
name: <example_extension>
79+
spec:
80+
namespace: <example_namespace>
81+
serviceAccount:
82+
name: <example_extension>-installer
83+
source:
84+
sourceType: Catalog
85+
catalog:
86+
packageName: <example_extension>-operator
87+
selector:
88+
matchExpressions:
89+
- key: example.com/testing
90+
operator: DoesNotExist
91+
----

‎modules/olmv1-catalog-selection-by-labels-or-expressions.adoc

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// Module included in the following assemblies:
2+
// * extensions/catalogs/olmv1-catalog-content-resolution.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
6+
[id="olmv1-catalog-selection-by-labels-or-exp_{context}"]
7+
= Catalog selection by labels or expressions
8+
9+
You can add metadata to a catalog by using labels in the custom resource (CR) of a cluster catalog. You can then filter catalog selection by specifying the assigned labels or using expressions in the CR of the cluster extension.
10+
11+
The following cluster catalog CR adds the `example.com/support` label with the value of `true` to the `catalog-a` cluster catalog:
12+
13+
.Example cluster catalog CR with labels
14+
[source,yaml]
15+
----
16+
apiVersion: olm.operatorframework.io/v1
17+
kind: ClusterCatalog
18+
metadata:
19+
name: catalog-a
20+
labels:
21+
example.com/support: "true"
22+
spec:
23+
source:
24+
type: Image
25+
image:
26+
ref: quay.io/example/content-management-a:latest
27+
----
28+
29+
The following cluster extension CR uses the `matchLabels` selector to select catalogs with the `example.com/support` label and the value of `true`:
30+
31+
.Example cluster extension CR with `matchLabels` selector
32+
[source,yaml]
33+
----
34+
apiVersion: olm.operatorframework.io/v1
35+
kind: ClusterExtension
36+
metadata:
37+
name: <example_extension>
38+
spec:
39+
namespace: <example_namespace>
40+
serviceAccount:
41+
name: <example_extension>-installer
42+
source:
43+
sourceType: Catalog
44+
catalog:
45+
packageName: <example_extension>-operator
46+
selector:
47+
matchLabels:
48+
example.com/support: "true"
49+
----
50+
51+
You can use the `matchExpressions` field to perform more complex filtering for labels. The following cluster extension CR selects catalogs with the `example.com/support` label and a value of `production` or `supported`:
52+
53+
.Example cluster extension CR with `matchExpression` selector
54+
[source,yaml]
55+
----
56+
apiVersion: olm.operatorframework.io/v1
57+
kind: ClusterExtension
58+
metadata:
59+
name: <example_extension>
60+
spec:
61+
namespace: <example_namespace>
62+
serviceAccount:
63+
name: <example_extension>-installer
64+
source:
65+
sourceType: Catalog
66+
catalog:
67+
packageName: <example_extension>-operator
68+
selector:
69+
matchExpressions:
70+
- key: example.com/support
71+
operator: In
72+
values:
73+
- "production"
74+
- "supported"
75+
----
76+
77+
[NOTE]
78+
====
79+
If you use both the `matchLabels` and `matchExpressions` fields, the selected catalog must satisfy all specified criteria.
80+
====

‎modules/olmv1-catalog-selection-by-name.adoc

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Module included in the following assemblies:
2+
// * extensions/catalogs/olmv1-catalog-content-resolution.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
6+
[id="olmv1-catalog-selection-by-name_{context}"]
7+
= Catalog selection by name
8+
9+
When a catalog is added to a cluster, a label is created by using the value of the `metadata.name` field of the catalog custom resource (CR). In the CR of an extension, you can specify the catalog name by using the `spec.source.catalog.selector.matchLabels` field. The value of the `matchLabels` field uses the following format:
10+
11+
.Example label derived from the `metadata.name` field
12+
[source,yaml]
13+
----
14+
apiVersion: olm.operatorframework.io/v1
15+
kind: ClusterExtension
16+
metadata:
17+
name: <example_extension>
18+
labels:
19+
olm.operatorframework.io/metadata.name: <example_extension> <1>
20+
...
21+
----
22+
<1> A label derived from the `metadata.name` field and automatically added when the catalog is applied.
23+
24+
The following example resolves the `<example_extension>-operator` package from a catalog with the `openshift-redhat-operators` label:
25+
26+
.Example extension CR
27+
[source,yaml]
28+
----
29+
apiVersion: olm.operatorframework.io/v1
30+
kind: ClusterExtension
31+
metadata:
32+
name: <example_extension>
33+
spec:
34+
namespace: <example_namespace>
35+
serviceAccount:
36+
name: <example_extension>-installer
37+
source:
38+
sourceType: Catalog
39+
catalog:
40+
packageName: <example_extension>-operator
41+
selector:
42+
matchLabels:
43+
olm.operatorframework.io/metadata.name: openshift-redhat-operators
44+
----

‎modules/olmv1-catalog-selection-by-priority.adoc

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Module included in the following assemblies:
2+
// * extensions/catalogs/olmv1-catalog-content-resolution.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
6+
[id="olmv1-catalog-exclusion-by-priority_{context}"]
7+
= Catalog selection by priority
8+
9+
When multiple catalogs provide the same package, you can resolve ambiguities by specifying the priority in the custom resource (CR) of each catalog. If unspecified, catalogs have a default priority value of `0`. The priority can be any positive or negative 32-bit integer.
10+
11+
[NOTE]
12+
====
13+
* During bundle resolution, catalogs with higher priority values are selected over catalogs with lower priority values.
14+
* Bundles that are not deprecated are prioritized over bundles that are deprecated.
15+
* If multiple bundles exist in catalogs with the same priority and the catalog selection is ambiguous, an error is printed.
16+
====
17+
18+
.Example cluster catalog CR with a higher priority
19+
[source,yaml]
20+
----
21+
apiVersion: olm.operatorframework.io/v1
22+
kind: ClusterCatalog
23+
metadata:
24+
name: high-priority-catalog
25+
spec:
26+
priority: 1000
27+
source:
28+
type: Image
29+
image:
30+
ref: quay.io/example/higher-priority-catalog:latest
31+
----
32+
33+
.Example cluster catalog CR with a lower priority
34+
[source,yaml]
35+
----
36+
apiVersion: olm.operatorframework.io/v1
37+
kind: ClusterCatalog
38+
metadata:
39+
name: lower-priority-catalog
40+
spec:
41+
priority: 10
42+
source:
43+
type: Image
44+
image:
45+
ref: quay.io/example/lower-priority-catalog:latest
46+
----

‎modules/olmv1-red-hat-catalogs.adoc

Lines changed: 36 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -11,50 +11,70 @@
1111

1212
{olmv1-first} includes the following Red Hat-provided Operator catalogs on the cluster by default. If you want to add an additional catalog to your cluster, create a custom resource (CR) for the catalog and apply it to the cluster. The following custom resource (CR) examples show the default catalogs installed on the cluster.
1313

14-
.Example Red Hat Operators catalog
14+
.Red{nbsp}Hat Operators catalog
1515
[source,yaml,subs="attributes+"]
1616
----
17-
apiVersion: catalogd.operatorframework.io/v1alpha1
17+
apiVersion: olm.operatorframework.io/v1
1818
kind: ClusterCatalog
1919
metadata:
20-
name: redhat-operators
20+
name: openshift-redhat-operators
2121
spec:
22+
priority: -100
2223
source:
23-
type: image
2424
image:
25+
pollIntervalMinutes: <poll_interval_duration> <1>
2526
ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
26-
pollInterval: <poll_interval_duration> <1>
27+
type: Image
2728
----
28-
<1> Specify the interval for polling the remote registry for newer image digests. The default value is `24h`. Valid units include seconds (`s`), minutes (`m`), and hours (`h`). To disable polling, set a zero value, such as `0s`.
29+
<1> Specify the interval in minutes for polling the remote registry for newer image digests. To disable polling, do not set the field.
2930

30-
.Example Certified Operators catalog
31+
.Certified Operators catalog
3132
[source,yaml,subs="attributes+"]
3233
----
33-
apiVersion: catalogd.operatorframework.io/v1alpha1
34+
apiVersion: olm.operatorframework.io/v1
3435
kind: ClusterCatalog
3536
metadata:
36-
name: certified-operators
37+
name: openshift-certified-operators
3738
spec:
39+
priority: -200
3840
source:
3941
type: image
4042
image:
43+
pollIntervalMinutes: 10
4144
ref: registry.redhat.io/redhat/certified-operator-index:v{product-version}
42-
pollInterval: 24h
45+
type: Image
4346
----
4447

45-
.Example Community Operators catalog
48+
.Red{nbsp}Hat Marketplace catalog
4649
[source,yaml,subs="attributes+"]
4750
----
48-
apiVersion: catalogd.operatorframework.io/v1alpha1
51+
apiVersion: olm.operatorframework.io/v1
4952
kind: ClusterCatalog
5053
metadata:
51-
name: community-operators
54+
name: openshift-redhat-marketplace
5255
spec:
56+
priority: -300
57+
source:
58+
image:
59+
pollIntervalMinutes: 10
60+
ref: registry.redhat.io/redhat/redhat-marketplace-index:v{product-version}
61+
type: Image
62+
----
63+
64+
.Community Operators catalog
65+
[source,yaml,subs="attributes+"]
66+
----
67+
apiVersion: olm.operatorframework.io/v1
68+
kind: ClusterCatalog
69+
metadata:
70+
name: openshift-community-operators
71+
spec:
72+
priority: -400
5373
source:
54-
type: image
5574
image:
75+
pollIntervalMinutes: 10
5676
ref: registry.redhat.io/redhat/community-operator-index:v{product-version}
57-
pollInterval: 24h
77+
type: Image
5878
----
5979

6080
The following command adds a catalog to your cluster:
@@ -64,4 +84,4 @@ The following command adds a catalog to your cluster:
6484
----
6585
$ oc apply -f <catalog_name>.yaml <1>
6686
----
67-
<1> Specifies the catalog CR, such as `redhat-operators.yaml`.
87+
<1> Specifies the catalog CR, such as `my-catalog.yaml`.

0 commit comments

Comments
 (0)