Skip to content

Commit 65a60bf

Browse files
bentitojoelanford
bentito
and
joelanford
authored
📖[Docs] Document minimal catalog selection (#1227)
* Document minimal catalog selection Signed-off-by: Brett Tofel <[email protected]> * Update docs/drafts/controlling-catalog-selection.md Co-authored-by: Joe Lanford <[email protected]> * Update docs/drafts/controlling-catalog-selection.md Co-authored-by: Joe Lanford <[email protected]> * Update docs/drafts/controlling-catalog-selection.md * Update docs/drafts/controlling-catalog-selection.md * Rest of redhat -> example Signed-off-by: Brett Tofel <[email protected]> * Add upstream ref about labels & selectors This commit adds a reference to the Kubernetes documentation on working with labels and selectors. It provides more context and resources for understanding catalog selection mechanisms. Signed-off-by: Brett Tofel <[email protected]> --------- Signed-off-by: Brett Tofel <[email protected]> Co-authored-by: Joe Lanford <[email protected]>
1 parent eb99236 commit 65a60bf

File tree

1 file changed

+239
-0
lines changed

1 file changed

+239
-0
lines changed

‎docs/drafts/controlling-catalog-selection.md

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
2+
# How A ClusterExtension Is Resolved From Various Catalogs
3+
4+
## Overview
5+
6+
Here you will find guidance on how catalog selection affects which bundle is actually resolved for a given package name. These features allow you to control which catalogs are used when resolving and installing operator bundles via `ClusterExtension`. You can:
7+
8+
- **Select specific catalogs by name or labels.**
9+
- **Set priorities for catalogs to resolve ambiguities.**
10+
- **Handle scenarios where multiple bundles match your criteria.**
11+
12+
## Usage Examples
13+
14+
### Selecting Catalogs by Name
15+
16+
To select a specific catalog by name, you can use the `matchLabels` field in your `ClusterExtension` resource.
17+
18+
#### Example
19+
20+
```yaml
21+
apiVersion: olm.operatorframework.io/v1alpha1
22+
kind: ClusterExtension
23+
metadata:
24+
name: my-extension
25+
spec:
26+
packageName: my-package
27+
catalog:
28+
selector:
29+
matchLabels:
30+
olm.operatorframework.io/metadata.name: my-catalog
31+
```
32+
33+
In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`.
34+
35+
### Selecting Catalogs by Labels
36+
37+
If you have catalogs labeled with specific metadata, you can select them using `matchLabels` or `matchExpressions`.
38+
39+
#### Using `matchLabels`
40+
41+
```yaml
42+
apiVersion: olm.operatorframework.io/v1alpha1
43+
kind: ClusterExtension
44+
metadata:
45+
name: my-extension
46+
spec:
47+
packageName: my-package
48+
catalog:
49+
selector:
50+
matchLabels:
51+
example.com/support: "true"
52+
```
53+
54+
This selects catalogs labeled with `example.com/support: "true"`.
55+
56+
#### Using `matchExpressions`
57+
58+
```yaml
59+
apiVersion: olm.operatorframework.io/v1alpha1
60+
kind: ClusterExtension
61+
metadata:
62+
name: my-extension
63+
spec:
64+
packageName: my-package
65+
catalog:
66+
selector:
67+
matchExpressions:
68+
- key: example.com/support
69+
operator: In
70+
values:
71+
- "gold"
72+
- "platinum"
73+
```
74+
75+
This selects catalogs where the label `example.com/support` has the value `gold` or `platinum`.
76+
77+
### Excluding Catalogs
78+
79+
You can exclude catalogs by using the `NotIn` or `DoesNotExist` operators in `matchExpressions`.
80+
81+
#### Example: Exclude Specific Catalogs
82+
83+
```yaml
84+
apiVersion: olm.operatorframework.io/v1alpha1
85+
kind: ClusterExtension
86+
metadata:
87+
name: my-extension
88+
spec:
89+
packageName: my-package
90+
catalog:
91+
selector:
92+
matchExpressions:
93+
- key: olm.operatorframework.io/metadata.name
94+
operator: NotIn
95+
values:
96+
- unwanted-catalog
97+
```
98+
99+
This excludes the catalog named `unwanted-catalog` from consideration.
100+
101+
#### Example: Exclude Catalogs with a Specific Label
102+
103+
```yaml
104+
apiVersion: olm.operatorframework.io/v1alpha1
105+
kind: ClusterExtension
106+
metadata:
107+
name: my-extension
108+
spec:
109+
packageName: my-package
110+
catalog:
111+
selector:
112+
matchExpressions:
113+
- key: example.com/support
114+
operator: DoesNotExist
115+
```
116+
117+
This selects catalogs that do not have the `example.com/support` label.
118+
119+
### Setting Catalog Priority
120+
121+
When multiple catalogs provide the same package, you can set priorities to resolve ambiguities. Higher priority catalogs are preferred.
122+
123+
#### Defining Catalog Priority
124+
125+
In your `ClusterCatalog` resource, set the `priority` field:
126+
127+
```yaml
128+
apiVersion: catalogd.operatorframework.io/v1alpha1
129+
kind: ClusterCatalog
130+
metadata:
131+
name: high-priority-catalog
132+
spec:
133+
priority: 1000
134+
source:
135+
type: image
136+
image:
137+
ref: quay.io/example/high-priority-catalog:latest
138+
```
139+
140+
Catalogs have a default priority of `0`. The priority can be any 32-bit integer. Catalogs with higher priority values are preferred during bundle resolution.
141+
142+
#### How Priority Resolves Ambiguity
143+
144+
When multiple bundles match your criteria:
145+
146+
1. **Bundles from catalogs with higher priority are selected.**
147+
2. **If multiple bundles are from catalogs with the same highest priority, and there is still ambiguity, an error is generated.**
148+
3. **Deprecated bundles are deprioritized.** If non-deprecated bundles are available, deprecated ones are ignored.
149+
150+
### Handling Ambiguity Errors
151+
152+
If the system cannot resolve to a single bundle due to ambiguity, it will generate an error. You can resolve this by:
153+
154+
- **Refining your catalog selection criteria.**
155+
- **Adjusting catalog priorities.**
156+
- **Ensuring that only one bundle matches your package name and version requirements.**
157+
158+
## End to End Example
159+
160+
1. **Create or Update `ClusterCatalogs` with Appropriate Labels and Priority**
161+
162+
```yaml
163+
apiVersion: catalogd.operatorframework.io/v1alpha1
164+
kind: ClusterCatalog
165+
metadata:
166+
name: catalog-a
167+
labels:
168+
example.com/support: "true"
169+
spec:
170+
priority: 1000
171+
source:
172+
type: image
173+
image:
174+
ref: quay.io/example/catalog-a:latest
175+
```
176+
177+
```yaml
178+
apiVersion: catalogd.operatorframework.io/v1alpha1
179+
kind: ClusterCatalog
180+
metadata:
181+
name: catalog-b
182+
labels:
183+
example.com/support: "false"
184+
spec:
185+
priority: 500
186+
source:
187+
type: image
188+
image:
189+
ref: quay.io/example/catalog-b:latest
190+
```
191+
NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied
192+
193+
194+
2. **Create a `ClusterExtension` with Catalog Selection**
195+
196+
```yaml
197+
apiVersion: olm.operatorframework.io/v1alpha1
198+
kind: ClusterExtension
199+
metadata:
200+
name: install-my-operator
201+
spec:
202+
packageName: my-operator
203+
catalog:
204+
selector:
205+
matchLabels:
206+
example.com/support: "true"
207+
```
208+
209+
3. **Apply the Resources**
210+
211+
```shell
212+
kubectl apply -f catalog-a.yaml
213+
kubectl apply -f catalog-b.yaml
214+
kubectl apply -f install-my-operator.yaml
215+
```
216+
217+
4. **Verify the Installation**
218+
219+
Check the status of the `ClusterExtension`:
220+
221+
```shell
222+
kubectl get clusterextension install-my-operator -o yaml
223+
```
224+
225+
The status should indicate that the bundle was resolved from `catalog-a` due to the higher priority and matching label.
226+
227+
## Important Notes
228+
229+
- **Default Behavior**: If you do not specify any catalog selection criteria, the system may select any available catalog that provides the requested package, and the choice is undefined.
230+
- **Logical AND of Selectors**: When using both `matchLabels` and `matchExpressions`, catalogs must satisfy all criteria.
231+
- **Deprecation Status**: Non-deprecated bundles are preferred over deprecated ones during resolution.
232+
- **Error Messages**: The system will update the `.status.conditions` of the `ClusterExtension` with meaningful messages if resolution fails due to ambiguity or no catalogs being selected.
233+
234+
## References
235+
236+
- [Minimal Controls for Selecting Catalogs to Resolve From](https://github.com/operator-framework/operator-controller/issues/1028)
237+
- [RFC: Minimal Catalog Selection - Labels](https://docs.google.com/document/d/1v9iPRZHt1YXhwK9__7OITnEN430lryQzWaAaIpn---Y)
238+
- [RFC: Minimal Catalog Selection - Priority](https://docs.google.com/document/d/1jGAOvE0yf_U2lpyhy2U0KPLGOaG-8-ML0lve1mR-o1Q)
239+
- [General Concept - Working with Labels & Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)

0 commit comments

Comments
 (0)