mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
OSDOCS#12905: Resolving content from multiple catalogs
This commit is contained in:
Michael Ryan Peter
committed by
openshift-cherrypick-robot
openshift-cherrypick-robot
parent
4f4b88c76d
commit
7ba2c6569f
@@ -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
|
||||
|
||||
25
extensions/catalogs/catalog-content-resolution.adoc
Normal file
25
extensions/catalogs/catalog-content-resolution.adoc
Normal file
@@ -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]
|
||||
@@ -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: <example_extension>
|
||||
spec:
|
||||
namespace: <example_namespace>
|
||||
serviceAccount:
|
||||
name: <example_extension>-installer
|
||||
source:
|
||||
sourceType: Catalog
|
||||
catalog:
|
||||
packageName: <example_extension>-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: <example_extension>
|
||||
spec:
|
||||
namespace: <example_namespace>
|
||||
serviceAccount:
|
||||
name: <example_extension>-installer
|
||||
source:
|
||||
sourceType: Catalog
|
||||
catalog:
|
||||
packageName: <example_extension>-operator
|
||||
selector:
|
||||
matchExpressions:
|
||||
- key: example.com/testing
|
||||
operator: DoesNotExist
|
||||
----
|
||||
@@ -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: <example_extension>
|
||||
spec:
|
||||
namespace: <example_namespace>
|
||||
serviceAccount:
|
||||
name: <example_extension>-installer
|
||||
source:
|
||||
sourceType: Catalog
|
||||
catalog:
|
||||
packageName: <example_extension>-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: <example_extension>
|
||||
spec:
|
||||
namespace: <example_namespace>
|
||||
serviceAccount:
|
||||
name: <example_extension>-installer
|
||||
source:
|
||||
sourceType: Catalog
|
||||
catalog:
|
||||
packageName: <example_extension>-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.
|
||||
====
|
||||
44
modules/olmv1-catalog-selection-by-name.adoc
Normal file
44
modules/olmv1-catalog-selection-by-name.adoc
Normal file
@@ -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: <example_extension>
|
||||
labels:
|
||||
olm.operatorframework.io/metadata.name: <example_extension> <1>
|
||||
...
|
||||
----
|
||||
<1> A label derived from the `metadata.name` field and automatically added when the catalog is applied.
|
||||
|
||||
The following example resolves the `<example_extension>-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: <example_extension>
|
||||
spec:
|
||||
namespace: <example_namespace>
|
||||
serviceAccount:
|
||||
name: <example_extension>-installer
|
||||
source:
|
||||
sourceType: Catalog
|
||||
catalog:
|
||||
packageName: <example_extension>-operator
|
||||
selector:
|
||||
matchLabels:
|
||||
olm.operatorframework.io/metadata.name: openshift-redhat-operators
|
||||
----
|
||||
46
modules/olmv1-catalog-selection-by-priority.adoc
Normal file
46
modules/olmv1-catalog-selection-by-priority.adoc
Normal file
@@ -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
|
||||
----
|
||||
@@ -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: <poll_interval_duration> <1>
|
||||
ref: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
|
||||
pollInterval: <poll_interval_duration> <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 <catalog_name>.yaml <1>
|
||||
----
|
||||
<1> Specifies the catalog CR, such as `redhat-operators.yaml`.
|
||||
<1> Specifies the catalog CR, such as `my-catalog.yaml`.
|
||||
|
||||
15
modules/olmv1-troubleshooting-catalog-selection-errors.adoc
Normal file
15
modules/olmv1-troubleshooting-catalog-selection-errors.adoc
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user