Merge pull request #52965 from bscott-rh/pre-install-caps

OSDOCS-4569 CIT: Add pre-install explanation of optional OCP capabilities

Author: jldohmann

_topic_maps/_topic_map.yml

@@ -113,6 +113,9 @@ Topics:
 - Name: Selecting an installation method and preparing a cluster
   File: installing-preparing
   Distros: openshift-origin,openshift-enterprise
+- Name: Cluster capabilities
+  File: cluster-capabilities
+  Distros: openshift-origin,openshift-enterprise
 - Name: Disconnected installation mirroring
   Dir: disconnected_install
   Distros: openshift-origin,openshift-enterprise
@@ -531,8 +534,9 @@ Topics:
   File: configuring-alert-notifications
 - Name: Converting a connected cluster to a disconnected cluster
   File: connected-to-disconnected
-- Name: Cluster capabilities
-  File: cluster-capabilities
+- Name: Enabling cluster capabilities
+  File: enabling-cluster-capabilities
+  Distros: openshift-origin,openshift-enterprise
 - Name: Configuring additional devices in an IBM Z or LinuxONE environment
   File: ibmz-post-install
 - Name: Red Hat Enterprise Linux CoreOS image layering

applications/connecting_applications_to_services/installing-sbo.adoc

@@ -16,7 +16,7 @@ You can install {servicebinding-title} on {product-title} 4.7 and later.
 == Prerequisites
 
 * You have access to an {product-title} cluster using an account with `cluster-admin` permissions.
-* Your cluster has the xref:../../post_installation_configuration/cluster-capabilities.adoc#cluster-capabilities[Marketplace capability] enabled or the Red Hat Operator catalog source configured manually.
+* Your cluster has the xref:../../post_installation_configuration/enabling-cluster-capabilities.adoc#enabling-cluster-capabilities[Marketplace capability] enabled or the Red Hat Operator catalog source configured manually.
 
 
 //Installing Service Binding Operator using web console

architecture/control-plane.adoc

@@ -41,7 +41,7 @@ include::modules/arch-platform-operators.adoc[leveloffset=+2]
 * xref:../operators/admin/olm-managing-po.adoc#olm-managing-po[Managing platform Operators]
 * xref:../operators/admin/olm-managing-po.adoc#olm-po-techpreview_olm-managing-po[Technology Preview restrictions for platform Operators]
 * xref:../operators/understanding/olm-packaging-format.adoc#olm-rukpak-about_olm-packaging-format[RukPak component and packaging format]
-* xref:../post_installation_configuration/cluster-capabilities.adoc#cluster-capabilities[Cluster capabilities]
+* xref:../installing/cluster-capabilities.adoc#cluster-capabilities[Cluster capabilities]
 endif::[]
 
 include::modules/understanding-machine-config-operator.adoc[leveloffset=+1]

cicd/gitops/installing-openshift-gitops.adoc

@@ -15,7 +15,7 @@ toc::[]
 * You have access to the {product-title} web console.
 * You are logged in as a user with the `cluster-admin` role.
 * You are logged in to the {product-title} cluster as an administrator.
-* Your cluster has the xref:../../post_installation_configuration/cluster-capabilities.adoc#cluster-capabilities[Marketplace capability] enabled or the Red Hat Operator catalog source configured manually.
+* Your cluster has the xref:../../installing/cluster-capabilities.adoc#marketplace-operator_cluster-capabilities[Marketplace capability] enabled or the Red Hat Operator catalog source configured manually.
 
 [WARNING]
 ====

cicd/pipelines/installing-pipelines.adoc

@@ -16,7 +16,7 @@ This guide walks cluster administrators through the process of installing the {p
 * You have access to an {product-title} cluster using an account with `cluster-admin` permissions.
 * You have installed `oc` CLI.
 * You have installed xref:../../cli_reference/tkn_cli/installing-tkn.adoc#installing-tkn[OpenShift Pipelines (`tkn`) CLI] on your local system.
-* Your cluster has the xref:../../post_installation_configuration/cluster-capabilities.adoc#cluster-capabilities[Marketplace capability] enabled or the Red Hat Operator catalog source configured manually.
+* Your cluster has the xref:../../installing/cluster-capabilities.adoc#marketplace-operator_cluster-capabilities[Marketplace capability] enabled or the Red Hat Operator catalog source configured manually.
 
 ifdef::openshift-origin[]
 * Ensure that you have downloaded the {cluster-manager-url-pull} as shown in the xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#installation-obtaining-installer_installing-gcp-customizations[Obtaining the installation program] to install this Operator.

installing/cluster-capabilities.adoc

@@ -0,0 +1,74 @@
+:_content-type: ASSEMBLY
+[id="cluster-capabilities"]
+= Cluster capabilities
+include::_attributes/common-attributes.adoc[]
+:context: cluster-capabilities
+
+toc::[]
+
+Cluster administrators can use cluster capabilities to enable or disable optional components prior to installation. Cluster administrators can enable cluster capabilities at anytime after installation.
+
+[NOTE]
+====
+Cluster administrators cannot disable a cluster capability after it is enabled.
+====
+
+include::modules/selecting-cluster-capabilities.adoc[leveloffset=+1]
+
+include::snippets/capabilities-table.adoc[]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[Installing a cluster on AWS with customizations]
+* xref:../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[Installing a cluster on GCP with customizations]
+
+include::modules/explanation-of-capabilities.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../operators/operator-reference.adoc#cluster-operator-reference[Cluster Operators reference]
+
+include::modules/cluster-bare-metal-operator.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../installing/installing_bare_metal_ipi/ipi-install-overview.adoc#ipi-install-overview[Deploying installer-provisioned clusters on bare metal]
+* xref:../installing/installing_bare_metal/preparing-to-install-on-bare-metal.adoc#preparing-to-install-on-bare-metal[Preparing for bare metal cluster installation]
+* xref:../post_installation_configuration/bare-metal-configuration.adoc#post-install-bare-metal-configuration[Bare metal configuration]
+
+include::modules/cluster-storage-operator.adoc[leveloffset=+2]
+
+include::modules/console-operator.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../web_console/web-console-overview.adoc#web-console-overview[Web console overview]
+
+include::modules/cluster-csi-snapshot-controller-operator.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../storage/container_storage_interface/persistent-storage-csi-snapshots.adoc#persistent-storage-csi-snapshots[CSI volume snapshots]
+
+include::modules/insights-operator.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../support/remote_health_monitoring/using-insights-operator.adoc#using-insights-operator[Using Insights Operator]
+
+include::modules/operator-marketplace.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red Hat-provided Operator catalogs]
+
+include::modules/cluster-samples-operator.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Configuring the Cluster Samples Operator]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+* xref:../post_installation_configuration/enabling-cluster-capabilities.adoc#enabling-cluster-capabilities[Enabling cluster capabilities after installation]

modules/cluster-bare-metal-operator.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //
 // *  operators/operator-reference.adoc
-// *  post_installation_configuration/cluster-capabilities.adoc
+// *  installing/cluster-capabilities.adoc
 
 ifeval::["{context}" == "cluster-operators-ref"]
 :operator-ref:
@@ -20,7 +20,7 @@ ifdef::operator-ref[]
 
 [NOTE]
 ====
-The Cluster Baremetal Operator is an optional cluster capability that can be disabled by cluster administrators during installation. For more information about optional cluster capabilities, see "Cluster capabilities" in _Post-installation configuration_.
+The Cluster Baremetal Operator is an optional cluster capability that can be disabled by cluster administrators during installation. For more information about optional cluster capabilities, see "Cluster capabilities" in _Installing_.
 ====
 
 endif::operator-ref[]
@@ -37,9 +37,9 @@ endif::cluster-caps[]
 The Cluster Baremetal Operator (CBO) deploys all the components necessary to take a bare-metal server to a fully functioning worker node ready to run {product-title} compute nodes. The CBO ensures that the metal3 deployment, which consists of the Bare Metal Operator (BMO) and Ironic containers, runs on one of the control plane nodes within the {product-title} cluster. The CBO also listens for {product-title} updates to resources that it watches and takes appropriate action. 
 
 ifdef::cluster-caps[]
-The bare-metal capability is required for installer provisioned installation (IPI) deployments. Disabling the bare-metal capability can result in unexpected problems with IPI deployments.
+The bare-metal capability is required for deployments using installer-provisioned infrastructure. Disabling the bare-metal capability can result in unexpected problems with these deployments.
 
-It is recommended that cluster adminstrators only disable the bare-metal capability during user-provisioned installations (UPI) that do not have any `BareMetalHost` resources in the cluster. 
+It is recommended that cluster administrators only disable the bare-metal capability during installations with user-provisioned infrastructure that do not have any `BareMetalHost` resources in the cluster. 
 
 [IMPORTANT]
 ====

modules/cluster-csi-snapshot-controller-operator.adoc

@@ -1,16 +1,54 @@
 // Module included in the following assemblies:
 //
 // * operators/operator-reference.adoc
+// * installing/cluster-capabilities.adoc
 
+ifeval::["{context}" == "cluster-operators-ref"]
+:operator-ref:
+endif::[]
+
+ifeval::["{context}" == "cluster-capabilities"]
+:cluster-caps:
+endif::[]
+
+:_content-type: REFERENCE
 [id="cluster-csi-snapshot-controller-operator_{context}"]
-= Cluster CSI Snapshot Controller Operator
+ifdef::operator-ref[= Cluster CSI Snapshot Controller Operator]
+ifdef::cluster-caps[= CSI snapshot controller capability]
+
+ifdef::operator-ref[]
+
+[NOTE]
+====
+The Cluster CSI Snapshot Controller Operator is an optional cluster capability that can be disabled by cluster administrators during installation. For more information about optional cluster capabilities, see "Cluster capabilities" in _Installing_.
+====
+
+endif::operator-ref[]
 
 [discrete]
 == Purpose
 
+ifdef::cluster-caps[]
+
+The Cluster CSI Snapshot Controller Operator provides the features for the `CSISnapshot` capability.
+
+endif::cluster-caps[]
+
 The Cluster CSI Snapshot Controller Operator installs and maintains the CSI Snapshot Controller. The CSI Snapshot Controller is responsible for watching the `VolumeSnapshot` CRD objects and manages the creation and deletion lifecycle of volume snapshots.
 
+ifdef::operator-ref[]
+
 [discrete]
 == Project
 
 link:https://github.com/openshift/cluster-csi-snapshot-controller-operator[cluster-csi-snapshot-controller-operator]
+
+endif::operator-ref[]
+
+ifeval::["{context}" == "cluster-operators-ref"]
+:!operator-ref:
+endif::[]
+
+ifeval::["{context}" == "cluster-caps"]
+:!cluster-caps:
+endif::[]

modules/cluster-samples-operator.adoc

@@ -1,14 +1,14 @@
 // Module included in the following assemblies:
 //
 // *  operators/operator-reference.adoc
-// *  post_installation_configuration/cluster-capabilities.adoc
+// *  installing/cluster-capabilities.adoc
 
 // operators/operator-reference.adoc
 ifeval::["{context}" == "cluster-operators-ref"]
 :operator-ref:
 endif::[]
 
-// post_installation_configuration/cluster-capabilities.adoc
+// installing/cluster-capabilities.adoc
 ifeval::["{context}" == "cluster-capabilities"]
 :cluster-caps:
 endif::[]
@@ -22,7 +22,7 @@ ifdef::operator-ref[]
 
 [NOTE]
 ====
-The Cluster Samples Operator is an optional cluster capability that can be disabled by cluster administrators during installation. For more information about optional cluster capabilities, see "Cluster capabilities" in _Post-installation configuration_.
+The Cluster Samples Operator is an optional cluster capability that can be disabled by cluster administrators during installation. For more information about optional cluster capabilities, see "Cluster capabilities" in _Installing_.
 ====
 
 endif::operator-ref[]
@@ -72,4 +72,4 @@ endif::[]
 
 ifeval::["{context}" == "cluster-caps"]
 :!cluster-caps:
-endif::[]
+endif::[]

modules/cluster-storage-operator.adoc

@@ -1,14 +1,48 @@
 // Module included in the following assemblies:
 //
 // *  operators/operator-reference.adoc
+// *  installing/cluster-capabilities.adoc
+
+ifeval::["{context}" == "cluster-operators-ref"]
+:operator-ref:
+endif::[]
+
+ifeval::["{context}" == "cluster-capabilities"]
+:cluster-caps:
+endif::[]
 
 [id="cluster-storage-operator_{context}"]
-= Cluster Storage Operator
+ifdef::operator-ref[= Cluster Storage Operator]
+ifdef::cluster-caps[= Cluster storage capability]
+
+ifdef::operator-ref[]
+
+[NOTE]
+====
+The Cluster Storage Operator is an optional cluster capability that can be disabled by cluster administrators during installation. For more information about optional cluster capabilities, see "Cluster capabilities" in _Installing_.
+====
+
+endif::operator-ref[]
 
 [discrete]
 == Purpose
 
-The Cluster Storage Operator sets {product-title} cluster-wide storage defaults. It ensures a default storage class exists for {product-title} clusters.
+ifdef::cluster-caps[]
+
+The Cluster Storage Operator provides the features for the `Storage` capability.
+
+endif::cluster-caps[]
+
+The Cluster Storage Operator sets {product-title} cluster-wide storage defaults. It ensures a default `storageclass` exists for {product-title} clusters. It also installs Container Storage Interface (CSI) drivers which enable your cluster to use various storage backends. 
+
+ifdef::cluster-caps[]
+[IMPORTANT]
+====
+If the cluster storage capability is disabled, the cluster will not have a default `storageclass` or any CSI drivers. Users with administrator privileges can create a default `storageclass` and manually install CSI drivers if the cluster storage capability is disabled. 
+====
+endif::cluster-caps[]
+
+ifdef::operator-ref[]
 
 [discrete]
 == Project
@@ -20,8 +54,17 @@ link:https://github.com/openshift/cluster-storage-operator[cluster-storage-opera
 
 No configuration is required.
 
+endif::operator-ref[]
+
 [discrete]
 == Notes
 
-* The Cluster Storage Operator supports Amazon Web Services (AWS) and {rh-openstack-first}.
-* The created storage class can be made non-default by editing its annotation, but the storage class cannot be deleted as long as the Operator runs.
+* The storage class that the Operator creates can be made non-default by editing its annotation, but this storage class cannot be deleted as long as the Operator runs.
+
+ifeval::["{context}" == "cluster-operators-ref"]
+:!operator-ref:
+endif::[]
+
+ifeval::["{context}" == "cluster-caps"]
+:!cluster-caps:
+endif::[]