Merge pull request #64601 from adellape/cat_note

Author: adellape

modules/olm-cs-health.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+// * operators/understanding/olm/olm-understanding-olm.adoc
+
+[id="olm-cs-health_{context}"]
+= Catalog health requirements
+
+Operator catalogs on a cluster are interchangeable from the perspective of installation resolution; a `Subscription` object might reference a specific catalog, but dependencies are resolved using all catalogs on the cluster.
+
+For example, if Catalog A is unhealthy, a subscription referencing Catalog A could resolve a dependency in Catalog B, which the cluster administrator might not have been expecting, because B normally had a lower catalog priority than A.
+
+As a result, OLM requires that all catalogs with a given global namespace (for example, the default `openshift-marketplace` namespace or a custom global namespace) are healthy. When a catalog is unhealthy, all Operator installation or update operations within its shared global namespace will fail with a `CatalogSourcesUnhealthy` condition. If these operations were permitted in an unhealthy state, OLM might make resolution and installation decisions that were unexpected to the cluster administrator.
+
+As a cluster administrator, if you observe an unhealthy catalog and want to consider the catalog as invalid and resume Operator installations, see the "Removing custom catalogs" or "Disabling the default OperatorHub catalog sources" sections for information about removing the unhealthy catalog.

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

@@ -16,6 +16,13 @@ include::modules/olm-properties.adoc[leveloffset=+1]
 include::modules/olm-dependencies.adoc[leveloffset=+1]
 include::modules/olm-generic-constraints.adoc[leveloffset=+1]
 include::modules/olm-dependency-resolution-preferences.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_dependency-resolution-preferences"]
+=== Additional resources
+
+* xref:../../../operators/understanding/olm/olm-understanding-olm.adoc#olm-cs-health_olm-understanding-olm[Catalog health requirements]
+
 include::modules/olm-dependency-resolution-crd-upgrades.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

operators/understanding/olm/olm-understanding-olm.adoc

@@ -12,7 +12,6 @@ include::modules/olm-overview.adoc[leveloffset=+1]
 include::modules/olm-crds.adoc[leveloffset=+1]
 include::modules/olm-csv.adoc[leveloffset=+2]
 include::modules/olm-catalogsource.adoc[leveloffset=+2]
-
 [role="_additional-resources"]
 .Additional resources
 
@@ -25,6 +24,13 @@ include::modules/olm-catalogsource.adoc[leveloffset=+2]
 * xref:../../../operators/admin/olm-cs-podsched.adoc#olm-cs-podsched[Catalog source pod scheduling]
 
 include::modules/olm-catalogsource-image-template.adoc[leveloffset=+3]
+include::modules/olm-cs-health.adoc[leveloffset=+3]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../../operators/admin/olm-managing-custom-catalogs.adoc#olm-removing-catalogs_olm-managing-custom-catalogs[Removing custom catalogs]
+* xref:../../../operators/admin/olm-managing-custom-catalogs.adoc#olm-restricted-networks-operatorhub_olm-managing-custom-catalogs[Disabling the default OperatorHub catalog sources]
+
 include::modules/olm-subscription.adoc[leveloffset=+2]
 
 [role="_additional-resources"]

support/troubleshooting/troubleshooting-operator-issues.adoc

@@ -16,6 +16,10 @@ If you experience Operator issues, verify Operator subscription status. Check Op
 
 // Operator subscription condition types
 include::modules/olm-status-conditions.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-cs-health_olm-understanding-olm[Catalog health requirements]
 
 // Viewing Operator subscription status by using the CLI
 include::modules/olm-status-viewing-cli.adoc[leveloffset=+1]