Merge pull request #37347 from adellape/img_templ_edit

Clarify mixed usage of olm.catalogImageTemplate

Author: jeana-redhat

modules/olm-catalogsource-image-template.adoc

@@ -41,7 +41,7 @@ Starting in {product-title} 4.9, cluster administrators can add the `olm.catalog
 You must specify the Kubernetes cluster version and not an {product-title} cluster version, as the latter is not currently available for templating.
 ====
 
-Provided that you have created and pushed an index image with a tag specifying the updated Kubernetes version, setting this annotation enables the index image versions in custom catalogs to be automatically changed after a cluster upgrade. The annotation value is used to overwrite any image reference in the `spec.image` field of the `CatalogSource` object, whether or not the `spec.image` field was set. This helps avoid cluster upgrades leaving Operator installations in unsupported states or without a continued update path.
+Provided that you have created and pushed an index image with a tag specifying the updated Kubernetes version, setting this annotation enables the index image versions in custom catalogs to be automatically changed after a cluster upgrade. The annotation value is used to set or update the image reference in the `spec.image` field of the `CatalogSource` object. This helps avoid cluster upgrades leaving Operator installations in unsupported states or without a continued update path.
 
 [IMPORTANT]
 ====
@@ -70,14 +70,21 @@ spec:
 ----
 ====
 
-For an {product-title} 4.9 cluster, which uses Kubernetes 1.22, the `olm.catalogImageTemplate` annotation in the preceding example would resolve to the following image reference:
+[NOTE]
+====
+If the `spec.image` field and the `olm.catalogImageTemplate` annotation are both set, the `spec.image` field is overwritten by the resolved value from the annotation. If the annotation does not resolve to a usable pull spec, the catalog source falls back to the set `spec.image` value.
+
+If the `spec.image` field is not set and the annotation does not resolve to a usable pull spec, OLM stops reconciliation of the catalog source and sets it into a human-readable error condition.
+====
+
+For an {product-title} 4.9 cluster, which uses Kubernetes 1.22, the `olm.catalogImageTemplate` annotation in the preceding example resolves to the following image reference:
 
 [source,terminal]
 ----
 quay.io/example-org/example-catalog:v1.22
 ----
 
-For future releases of {product-title}, you could create updated index images for your custom catalogs that target the later Kubernetes version that is used by the later {product-title} version. With the `olm.catalogImageTemplate` annotation set before the upgrade, upgrading the cluster to the later {product-title} version would then automatically update the catalog's index image as well.
+For future releases of {product-title}, you can create updated index images for your custom catalogs that target the later Kubernetes version that is used by the later {product-title} version. With the `olm.catalogImageTemplate` annotation set before the upgrade, upgrading the cluster to the later {product-title} version would then automatically update the catalog's index image as well.
 
 ifdef::openshift-origin[]
 :!global_ns:

modules/olm-catalogsource.adoc

@@ -61,9 +61,9 @@ status:
 <.> Namespace to create the catalog available. To make the catalog available cluster-wide in all namespaces, set this value to `{global_ns}`. The default Red Hat-provided catalog sources also use the `{global_ns}` namespace. Otherwise, set the value to a specific namespace to make the Operator only available in that namespace.
 <.> Optional: To avoid cluster upgrades potentially leaving Operator installations in an unsupported state or without a continued update path, you can enable automatically changing your Operator catalog's index image version as part of cluster upgrades.
 +
-Set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag. See the "Image template for custom catalog sources" section for more details.
+Set the `olm.catalogImageTemplate` annotation to your index image name and use one or more of the Kubernetes cluster version variables as shown when constructing the template for the image tag. The annotation overwrites the `spec.image` field at run time. See the "Image template for custom catalog sources" section for more details.
 <.> Display name for the catalog in the web console and CLI.
-<.> Index image for the catalog.
+<.> Index image for the catalog. Optionally, can be omitted when using the `olm.catalogImageTemplate` annotation, which sets the pull spec at run time.
 <.> Weight for the catalog source. OLM uses the weight for prioritization during dependency resolution. A higher weight indicates the catalog is preferred over lower-weighted catalogs.
 <.> Source types include the following:
 +