OSDOCS-2361: Add olm.catalogImageTemplate docs

modules/olm-catalogsource-image-template.adoc

@@ -0,0 +1,87 @@
+// Module included in the following assemblies:
+//
+// * operators/understanding/olm/olm-understanding-olm.adoc
+
+ifdef::openshift-origin[]
+:global_ns: olm
+endif::[]
+ifndef::openshift-origin[]
+:global_ns: openshift-marketplace
+endif::[]
+
+[id="olm-catalogsource-image-template_{context}"]
+= Image template for custom catalog sources
+
+Operator compatibility with the underlying cluster can be expressed by a catalog source in various ways. One way, which is used for the default Red Hat-provided catalog sources, is to identify image tags for index images that are specifically created for a particular platform release, for example {product-title} 4.9.
+
+During a cluster upgrade, the index image tag for the default Red Hat-provided catalog sources are updated automatically by the Cluster Version Operator (CVO) so that Operator Lifecycle Manager (OLM) pulls the updated version of the catalog. For example during an upgrade from {product-title} 4.8 to 4.9, the `spec.image` field in the `CatalogSource` object for the `redhat-operators` catalog is updated from:
+
+[source,terminal]
+----
+registry.redhat.io/redhat/redhat-operator-index:v4.8
+----
+
+to:
+
+[source,terminal]
+----
+registry.redhat.io/redhat/redhat-operator-index:v4.9
+----
+
+However, the CVO does not automatically update image tags for custom catalogs. To ensure users are left with a compatible and supported Operator installation after a cluster upgrade, custom catalogs should also be kept updated to reference an updated index image.
+
+Starting in {product-title} 4.9, cluster administrators can add the `olm.catalogImageTemplate` annotation in the `CatalogSource` object for custom catalogs to an image reference that includes a template. The following Kubernetes version variables are supported for use in the template:
+
+* `kube_major_version`
+* `kube_minor_version`
+* `kube_patch_version`
+
+[NOTE]
+====
+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.
+
+[IMPORTANT]
+====
+You must ensure that the index image with the updated tag, in whichever registry it is stored in, is accessible by the cluster at the time of the cluster upgrade.
+====
+
+.Example catalog source with an image template
+[%collapsible]
+====
+[source,yaml,subs="attributes+"]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: CatalogSource
+metadata:
+  generation: 1
+  name: example-catalog
+  namespace: openshift-marketplace
+  annotations:
+    olm.catalogImageTemplate:
+      "quay.io/example-org/example-catalog:v{kube_major_version}.{kube_minor_version}"
+spec:
+  displayName: Example Catalog
+  image: quay.io/example-org/example-catalog:v1.22
+  priority: -400
+  publisher: Example Org
+----
+====
+
+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:
+
+[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.
+
+ifdef::openshift-origin[]
+:!global_ns:
+endif::[]
+ifndef::openshift-origin[]
+:!global_ns:
+endif::[]

modules/olm-catalogsource.adoc

@@ -32,6 +32,9 @@ metadata:
   generation: 1
   name: example-catalog <.>
   namespace: {global_ns} <.>
+  annotations:
+    olm.catalogImageTemplate: <.>
+      "quay.io/example-org/example-catalog:v{kube_major_version}.{kube_minor_version}.{kube_patch_version}"
 spec:
   displayName: Example Catalog <.>
   image: quay.io/example-org/example-catalog:v1 <.>
@@ -56,6 +59,9 @@ status:
 ----
 <.> Name for the `CatalogSource` object. This value is also used as part of the name for the related pod that is created in the requested namespace.
 <.> 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.
 <.> Display name for the catalog in the web console and CLI.
 <.> Index image for the catalog.
 <.> 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.

modules/olm-creating-catalog-from-index.adoc

@@ -47,16 +47,29 @@ ifndef::olm-restricted-networks[]
   name: my-operator-catalog
 endif::[]
   namespace: {namespace} <.>
+ifndef::olm-restricted-networks[]
+  annotations:
+    olm.catalogImageTemplate: <.>
+      "<registry>/<namespace>/<index_image_name>:v{kube_major_version}.{kube_minor_version}.{kube_patch_version}"
+endif::[]
 spec:
   sourceType: grpc
-  image: <registry>:<port>/<namespace>/{index-image}:{tag} <.>
+ifdef::olm-restricted-networks[]
+  image: <registry>/<namespace>/{index-image}:{tag} <.>
+endif::[]
+ifndef::olm-restricted-networks[]
+  image: <registry>/<namespace>/<index_image_name>:<tag> <.>
+endif::[]
   displayName: My Operator Catalog
   publisher: <publisher_name> <.>
   updateStrategy:
     registryPoll: <.>
       interval: 30m
 ----
 <.> If you want the catalog source to be available globally to users in all namespaces, specify the `{namespace}` namespace. Otherwise, you can specify a different namespace for the catalog to be scoped and available only for that namespace.
+ifndef::olm-restricted-networks[]
+<.> Optional: 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.
+endif::[]
 ifdef::olm-restricted-networks[]
 <.> If you mirrored content to local files before uploading to a registry, remove any backslash (`/`) characters from the `metadata.name` field to avoid an "invalid resource name" error when you create the object.
 endif::[]

modules/olm-rh-catalogs.adoc

@@ -32,4 +32,18 @@ The following Operator catalogs are distributed by Red Hat:
 |Software maintained by relevant representatives in the link:https://github.com/operator-framework/community-operators[operator-framework/community-operators] GitHub repository. No official support.
 |===
 
+During a cluster upgrade, the index image tag for the default Red Hat-provided catalog sources are updated automatically by the Cluster Version Operator (CVO) so that Operator Lifecycle Manager (OLM) pulls the updated version of the catalog. For example during an upgrade from {product-title} 4.8 to 4.9, the `spec.image` field in the `CatalogSource` object for the `redhat-operators` catalog is updated from:
+
+[source,terminal]
+----
+registry.redhat.io/redhat/redhat-operator-index:v4.8
+----
+
+to:
+
+[source,terminal]
+----
+registry.redhat.io/redhat/redhat-operator-index:v4.9
+----
+
 :!tag:

operators/admin/olm-managing-custom-catalogs.adoc

@@ -32,6 +32,7 @@ include::modules/olm-creating-index-image.adoc[leveloffset=+1]
 include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+1]
 .Additional resources
 
+* See xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[Operator Lifecycle Manager concepts and resources -> Catalog source] for more details on the `CatalogSource` object spec.
 * If your index image is hosted on a private registry and requires authentication, see xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries].
 
 include::modules/olm-updating-index-image.adoc[leveloffset=+1]

operators/admin/olm-restricted-networks.adoc

@@ -56,7 +56,10 @@ include::modules/olm-mirroring-catalog.adoc[leveloffset=+1]
 * xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-arch-os-support_osdk-generating-csvs[Architecture and operating system support for Operators]
 
 include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+1]
+.Additional resources
+
 * If your index image is hosted on a private registry and requires authentication, see xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries].
+* If you want your catalogs to be able to automatically update their index image version after cluster upgrades by using Kubernetes version-based image tags, see xref:../../operators/understanding/olm/olm-understanding-olm.html#olm-catalogsource-image-template_olm-understanding-olm[Image template for custom catalog sources].
 
 include::modules/olm-updating-index-image.adoc[leveloffset=+1]
 .Additional resources

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

@@ -15,9 +15,11 @@ include::modules/olm-catalogsource.adoc[leveloffset=+2]
 
 * xref:../../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub]
 * xref:../../../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red Hat-provided Operator catalogs]
+* xref:../../../operators/admin/olm-managing-custom-catalogs.adoc#olm-creating-catalog-from-index_olm-managing-custom-catalogs[Creating a catalog from an index image]
 * xref:../../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-dependency-catalog-priority_olm-understanding-dependency-resolution[Catalog priority]
 * xref:../../../operators/admin/olm-status.adoc#olm-cs-status-cli_olm-status[Viewing Operator catalog source status by using the CLI]
 
+include::modules/olm-catalogsource-image-template.adoc[leveloffset=+3]
 include::modules/olm-subscription.adoc[leveloffset=+2]
 .Additional resources
 
@@ -29,13 +31,11 @@ include::modules/olm-installplan.adoc[leveloffset=+2]
 * xref:../../../operators/admin/olm-creating-policy.adoc#olm-creating-policy[Allowing non-cluster administrators to install Operators]
 
 include::modules/olm-operatorgroups-about.adoc[leveloffset=+2]
-
 .Additional resources
 
 * xref:../../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-understanding-operatorgroups[Operator groups].
 
 include::modules/olm-operatorconditions-about.adoc[leveloffset=+2]
-
 .Additional resources
 
 * xref:../../../operators/understanding/olm/olm-operatorconditions.adoc#olm-operatorconditions[Operator conditions].