From 7ba2c6569f4862b1033543a7676e5e7115ba2123 Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Mon, 10 Feb 2025 10:35:06 -0500 Subject: [PATCH] OSDOCS#12905: Resolving content from multiple catalogs --- _topic_maps/_topic_map.yml | 2 + .../catalogs/catalog-content-resolution.adoc | 25 +++++ ...og-exclusion-by-labels-or-expressions.adoc | 91 +++++++++++++++++++ ...og-selection-by-labels-or-expressions.adoc | 80 ++++++++++++++++ modules/olmv1-catalog-selection-by-name.adoc | 44 +++++++++ .../olmv1-catalog-selection-by-priority.adoc | 46 ++++++++++ modules/olmv1-red-hat-catalogs.adoc | 52 +++++++---- ...ubleshooting-catalog-selection-errors.adoc | 15 +++ 8 files changed, 339 insertions(+), 16 deletions(-) create mode 100644 extensions/catalogs/catalog-content-resolution.adoc create mode 100644 modules/olmv1-catalog-exclusion-by-labels-or-expressions.adoc create mode 100644 modules/olmv1-catalog-selection-by-labels-or-expressions.adoc create mode 100644 modules/olmv1-catalog-selection-by-name.adoc create mode 100644 modules/olmv1-catalog-selection-by-priority.adoc create mode 100644 modules/olmv1-troubleshooting-catalog-selection-errors.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 9d93a70fbc..9e23d4950b 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2081,6 +2081,8 @@ Topics: File: rh-catalogs - Name: Managing catalogs File: managing-catalogs + - Name: Catalog content resolution + File: catalog-content-resolution - Name: Creating catalogs File: creating-catalogs - Name: Disconnected environment support in OLM v1 diff --git a/extensions/catalogs/catalog-content-resolution.adoc b/extensions/catalogs/catalog-content-resolution.adoc new file mode 100644 index 0000000000..becd134a6d --- /dev/null +++ b/extensions/catalogs/catalog-content-resolution.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: ASSEMBLY +[id="catalog-content-resolution"] += Catalog content resolution +include::_attributes/common-attributes.adoc[] +:context: catalog-content-resolution + +toc::[] + +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. + +You can perform the following actions to control the selection of catalog content: + +* Specify labels to select the catalog. +* Use match expressions to perform complex filtering across catalogs. +* Set catalog priority. + +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. + +During resolution, bundles that are not deprecated are preferred over deprecated bundles by default. + +include::modules/olmv1-catalog-selection-by-name.adoc[leveloffset=1] +include::modules/olmv1-catalog-selection-by-labels-or-expressions.adoc[leveloffset=1] +include::modules/olmv1-catalog-exclusion-by-labels-or-expressions.adoc[leveloffset=1] +include::modules/olmv1-catalog-selection-by-priority.adoc[leveloffset=1] +include::modules/olmv1-troubleshooting-catalog-selection-errors.adoc[leveloffset=1] diff --git a/modules/olmv1-catalog-exclusion-by-labels-or-expressions.adoc b/modules/olmv1-catalog-exclusion-by-labels-or-expressions.adoc new file mode 100644 index 0000000000..f2c88a93cc --- /dev/null +++ b/modules/olmv1-catalog-exclusion-by-labels-or-expressions.adoc @@ -0,0 +1,91 @@ +// Module included in the following assemblies: +// * extensions/catalogs/catalog-content-resolution.adoc + +:_mod-docs-content-type: REFERENCE + +[id="olmv1-catalog-exclusion-by-labels-or-expressions_{context}"] += Catalog exclusion by labels or expressions + +You can exclude catalogs by using match expressions on metadata with the `NotIn` or `DoesNotExist` operators. + +The following CRs add an `example.com/testing` label to the `unwanted-catalog-1` and `unwanted-catalog-2` cluster catalogs: + +.Example cluster catalog CR +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterCatalog +metadata: + name: unwanted-catalog-1 + labels: + example.com/testing: "true" +spec: + source: + type: Image + image: + ref: quay.io/example/content-management-a:latest +---- + +.Example cluster catalog CR +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterCatalog +metadata: + name: unwanted-catalog-2 + labels: + example.com/testing: "true" +spec: + source: + type: Image + image: + ref: quay.io/example/content-management-b:latest +---- + +The following cluster extension CR excludes selection from the `unwanted-catalog-1` catalog: + +.Example cluster extension CR that excludes a specific catalog +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: +spec: + namespace: + serviceAccount: + name: -installer + source: + sourceType: Catalog + catalog: + packageName: -operator + selector: + matchExpressions: + - key: olm.operatorframework.io/metadata.name + operator: NotIn + values: + - unwanted-catalog-1 +---- + +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. + +.Example cluster extension CR that excludes catalogs with a specific label +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: +spec: + namespace: + serviceAccount: + name: -installer + source: + sourceType: Catalog + catalog: + packageName: -operator + selector: + matchExpressions: + - key: example.com/testing + operator: DoesNotExist +---- diff --git a/modules/olmv1-catalog-selection-by-labels-or-expressions.adoc b/modules/olmv1-catalog-selection-by-labels-or-expressions.adoc new file mode 100644 index 0000000000..7717ce958a --- /dev/null +++ b/modules/olmv1-catalog-selection-by-labels-or-expressions.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// * extensions/catalogs/olmv1-catalog-content-resolution.adoc + +:_mod-docs-content-type: REFERENCE + +[id="olmv1-catalog-selection-by-labels-or-exp_{context}"] += Catalog selection by labels or expressions + +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. + +The following cluster catalog CR adds the `example.com/support` label with the value of `true` to the `catalog-a` cluster catalog: + +.Example cluster catalog CR with labels +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterCatalog +metadata: + name: catalog-a + labels: + example.com/support: "true" +spec: + source: + type: Image + image: + ref: quay.io/example/content-management-a:latest +---- + +The following cluster extension CR uses the `matchLabels` selector to select catalogs with the `example.com/support` label and the value of `true`: + +.Example cluster extension CR with `matchLabels` selector +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: +spec: + namespace: + serviceAccount: + name: -installer + source: + sourceType: Catalog + catalog: + packageName: -operator + selector: + matchLabels: + example.com/support: "true" +---- + +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`: + +.Example cluster extension CR with `matchExpression` selector +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: +spec: + namespace: + serviceAccount: + name: -installer + source: + sourceType: Catalog + catalog: + packageName: -operator + selector: + matchExpressions: + - key: example.com/support + operator: In + values: + - "production" + - "supported" +---- + +[NOTE] +==== +If you use both the `matchLabels` and `matchExpressions` fields, the selected catalog must satisfy all specified criteria. +==== diff --git a/modules/olmv1-catalog-selection-by-name.adoc b/modules/olmv1-catalog-selection-by-name.adoc new file mode 100644 index 0000000000..b3ecfe7e6f --- /dev/null +++ b/modules/olmv1-catalog-selection-by-name.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// * extensions/catalogs/olmv1-catalog-content-resolution.adoc + +:_mod-docs-content-type: REFERENCE + +[id="olmv1-catalog-selection-by-name_{context}"] += Catalog selection by name + +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: + +.Example label derived from the `metadata.name` field +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: + labels: + olm.operatorframework.io/metadata.name: <1> +... +---- +<1> A label derived from the `metadata.name` field and automatically added when the catalog is applied. + +The following example resolves the `-operator` package from a catalog with the `openshift-redhat-operators` label: + +.Example extension CR +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: +spec: + namespace: + serviceAccount: + name: -installer + source: + sourceType: Catalog + catalog: + packageName: -operator + selector: + matchLabels: + olm.operatorframework.io/metadata.name: openshift-redhat-operators +---- diff --git a/modules/olmv1-catalog-selection-by-priority.adoc b/modules/olmv1-catalog-selection-by-priority.adoc new file mode 100644 index 0000000000..b0e4ae42f4 --- /dev/null +++ b/modules/olmv1-catalog-selection-by-priority.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// * extensions/catalogs/olmv1-catalog-content-resolution.adoc + +:_mod-docs-content-type: REFERENCE + +[id="olmv1-catalog-exclusion-by-priority_{context}"] += Catalog selection by priority + +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. + +[NOTE] +==== +* During bundle resolution, catalogs with higher priority values are selected over catalogs with lower priority values. +* Bundles that are not deprecated are prioritized over bundles that are deprecated. +* If multiple bundles exist in catalogs with the same priority and the catalog selection is ambiguous, an error is printed. +==== + +.Example cluster catalog CR with a higher priority +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterCatalog +metadata: + name: high-priority-catalog +spec: + priority: 1000 + source: + type: Image + image: + ref: quay.io/example/higher-priority-catalog:latest +---- + +.Example cluster catalog CR with a lower priority +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterCatalog +metadata: + name: lower-priority-catalog +spec: + priority: 10 + source: + type: Image + image: + ref: quay.io/example/lower-priority-catalog:latest +---- diff --git a/modules/olmv1-red-hat-catalogs.adoc b/modules/olmv1-red-hat-catalogs.adoc index c3735fddd7..ef498c1e8f 100644 --- a/modules/olmv1-red-hat-catalogs.adoc +++ b/modules/olmv1-red-hat-catalogs.adoc @@ -11,50 +11,70 @@ {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. -.Example Red Hat Operators catalog +.Red{nbsp}Hat Operators catalog [source,yaml,subs="attributes+"] ---- -apiVersion: catalogd.operatorframework.io/v1alpha1 +apiVersion: olm.operatorframework.io/v1 kind: ClusterCatalog metadata: - name: redhat-operators + name: openshift-redhat-operators spec: + priority: -100 source: - type: image image: + pollIntervalMinutes: <1> ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version} - pollInterval: <1> + type: Image ---- -<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`. +<1> Specify the interval in minutes for polling the remote registry for newer image digests. To disable polling, do not set the field. -.Example Certified Operators catalog +.Certified Operators catalog [source,yaml,subs="attributes+"] ---- -apiVersion: catalogd.operatorframework.io/v1alpha1 +apiVersion: olm.operatorframework.io/v1 kind: ClusterCatalog metadata: - name: certified-operators + name: openshift-certified-operators spec: +priority: -200 source: type: image image: + pollIntervalMinutes: 10 ref: registry.redhat.io/redhat/certified-operator-index:v{product-version} - pollInterval: 24h + type: Image ---- -.Example Community Operators catalog +.Red{nbsp}Hat Marketplace catalog [source,yaml,subs="attributes+"] ---- -apiVersion: catalogd.operatorframework.io/v1alpha1 +apiVersion: olm.operatorframework.io/v1 kind: ClusterCatalog metadata: - name: community-operators + name: openshift-redhat-marketplace spec: + priority: -300 source: - type: image image: + pollIntervalMinutes: 10 + ref: registry.redhat.io/redhat/redhat-marketplace-index:v{product-version} + type: Image +---- + +.Community Operators catalog +[source,yaml,subs="attributes+"] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterCatalog +metadata: + name: openshift-community-operators +spec: + priority: -400 + source: + image: + pollIntervalMinutes: 10 ref: registry.redhat.io/redhat/community-operator-index:v{product-version} - pollInterval: 24h + type: Image ---- The following command adds a catalog to your cluster: @@ -64,4 +84,4 @@ The following command adds a catalog to your cluster: ---- $ oc apply -f .yaml <1> ---- -<1> Specifies the catalog CR, such as `redhat-operators.yaml`. +<1> Specifies the catalog CR, such as `my-catalog.yaml`. diff --git a/modules/olmv1-troubleshooting-catalog-selection-errors.adoc b/modules/olmv1-troubleshooting-catalog-selection-errors.adoc new file mode 100644 index 0000000000..18f55d8468 --- /dev/null +++ b/modules/olmv1-troubleshooting-catalog-selection-errors.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// * extensions/catalogs/olmv1-catalog-content-resolution.adoc + +:_mod-docs-content-type: REFERENCE + +[id="olmv1-troubleshooting-catalog-selection-errors_{context}"] += Troubleshooting catalog selection errors + +If bundle resolution fails because of ambiguity or because no catalog is selected, an error message is printed in the `status.conditions` field of the cluster extension. + +Perform the following actions to troubleshoot catalog selection errors: + +* Refine your selection criteria using labels or expressions. +* Adjust your catalog priorities. +* Ensure that only one bundle matches your package name and version requirements.