Merge pull request #29567 from adellape/startingcsv

Add module for startingCSV usage

Author: adellape

modules/olm-installing-operators-from-operatorhub.adoc

@@ -12,12 +12,14 @@ ifeval::["{context}" == "olm-installing-operators-in-namespace"]
 endif::[]
 
 [id="olm-installing-operators-from-operatorhub_{context}"]
-= Installing Operators from OperatorHub
+= Operator installation with OperatorHub
+
+OperatorHub is a user interface for discovering Operators; it works in conjunction with Operator Lifecycle Manager (OLM), which installs and manages Operators on a cluster.
 
 ifndef::olm-user[]
 As a cluster administrator, you can install an Operator from OperatorHub using the {product-title}
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-web console or CLI. You can then subscribe the Operator to one or more namespaces to make it available for developers on your cluster.
+web console or CLI. Subscribing an Operator to one or more namespaces makes the Operator available to developers on your cluster.
 endif::[]
 ifdef::openshift-dedicated[]
 web console. You can then subscribe the Operator to the default `openshift-operators` namespace to make it available for developers on your cluster. When you subscribe the Operator to all namespaces, the Operator is installed in the `openshift-operators` namespace; this installation method is not supported by all Operators.

modules/olm-installing-specific-version-cli.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * operators/user/olm-installing-operators-in-namespace.adoc
+// * operators/admin/olm-adding-operators-to-cluster.adoc
+
+ifeval::["{context}" == "olm-installing-operators-in-namespace"]
+:olm-user:
+endif::[]
+
+[id="olm-installing-specific-version-cli_{context}"]
+= Installing a specific version of an Operator
+
+You can install a specific version of an Operator by setting the cluster service version (CSV) in a `Subscription` object.
+
+.Prerequisites
+
+ifndef::olm-user[]
+- Access to an {product-title} cluster using an account with
+ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
+`cluster-admin` permissions
+endif::[]
+ifdef::openshift-dedicated[]
+`dedicated-admins-cluster` permissions
+endif::[]
+endif::[]
+
+ifdef::olm-user[]
+- Access to an {product-title} cluster using an account with Operator installation permissions
+endif::[]
+
+- OpenShift CLI (`oc`) installed
+
+.Procedure
+
+. Create a `Subscription` object YAML file that subscribes a namespace to an Operator with a specific version by setting the `startingCSV` field. Set the `installPlanApproval` field to `Manual` to prevent the Operator from automatically upgrading if a later version exists in the catalog.
++
+For example, the following `sub.yaml` file can be used to install the Red Hat Quay Operator specifically to version 3.4.0:
++
+.Subscription with a specific starting Operator version
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: quay-operator
+  namespace: quay
+spec:
+  channel: quay-v3.4
+  installPlanApproval: Manual <1>
+  name: quay-operator
+  source: redhat-operators
+  sourceNamespace: openshift-marketplace
+  startingCSV: quay-operator.v3.4.0 <2>
+----
+<1> Set the approval strategy to `Manual` in case your specified version is superseded by a later version in the catalog. This plan prevents an automatic upgrade to a later version and requires manual approval before the starting CSV can complete the installation.
+<2> Set a specific version of an Operator CSV.
+
+. Create the `Subscription` object:
++
+[source,terminal]
+----
+$ oc apply -f sub.yaml
+----
+
+. Manually approve the pending install plan to complete the Operator installation.

modules/olm-operatorhub-overview.adoc

@@ -5,7 +5,7 @@
 [id="olm-operatorhub-overview_{context}"]
 = About OperatorHub
 
-_OperatorHub_ is the web console interface in {product-title} that cluster administrators use to discover and install Operators. With one click, an Operator can be pulled from its off-cluster source, installed and subscribed on the cluster, and made ready for engineering teams to self-service manage the product across deployment environments using the Operator Lifecycle Manager (OLM).
+_OperatorHub_ is the web console interface in {product-title} that cluster administrators use to discover and install Operators. With one click, an Operator can be pulled from its off-cluster source, installed and subscribed on the cluster, and made ready for engineering teams to self-service manage the product across deployment environments using Operator Lifecycle Manager (OLM).
 
 ifndef::openshift-origin[]
 Cluster administrators can choose from catalogs grouped into the following categories:

operators/admin/olm-adding-operators-to-cluster.adoc

@@ -8,7 +8,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-This guide walks cluster administrators through installing Operators to an {product-title} cluster and subscribing Operators to namespaces.
+Cluster administrators can install Operators to an {product-title} cluster by subscribing Operators to namespaces with OperatorHub.
 
 ifdef::openshift-origin[]
 [id="olm-adding-operators-to-a-cluster-prereqs"]
@@ -20,10 +20,17 @@ If you have the pull secret, add the `redhat-operators` catalog to the `Operator
 endif::[]
 
 include::modules/olm-installing-operators-from-operatorhub.adoc[leveloffset=+1]
-include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+2]
+* xref:../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub]
+
+include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+1]
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-include::modules/olm-installing-from-operatorhub-using-cli.adoc[leveloffset=+2]
+include::modules/olm-installing-from-operatorhub-using-cli.adoc[leveloffset=+1]
 .Additional resources
 
 * xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-about_olm-understanding-operatorgroups[About Operator groups]
+
+include::modules/olm-installing-specific-version-cli.adoc[leveloffset=+1]
+.Additional resources
+
+* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade]
 endif::[]

operators/understanding/olm-understanding-operatorhub.adoc

@@ -5,8 +5,6 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-This guide outlines the architecture of OperatorHub.
-
 include::modules/olm-operatorhub-overview.adoc[leveloffset=+1]
 include::modules/olm-operatorhub-architecture.adoc[leveloffset=+1]
 

operators/user/olm-installing-operators-in-namespace.adoc

@@ -19,10 +19,17 @@ If you have the pull secret, add the `redhat-operators` catalog to the `Operator
 endif::[]
 
 include::modules/olm-installing-operators-from-operatorhub.adoc[leveloffset=+1]
-include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+2]
+* xref:../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub]
+
+include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+1]
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-include::modules/olm-installing-from-operatorhub-using-cli.adoc[leveloffset=+2]
+include::modules/olm-installing-from-operatorhub-using-cli.adoc[leveloffset=+1]
 .Additional resources
 
 * xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-about_olm-understanding-operatorgroups[About Operator groups]
+
+include::modules/olm-installing-specific-version-cli.adoc[leveloffset=+1]
+.Additional resources
+
+* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade]
 endif::[]