Merge pull request #113505 from dfitzmau/OSDOCS-16988-3-CQA

OSDOCS-16988-3-CQA: CQA PR 3.1 for INSTALL-1: Core Installation Conce…

Author: ShaunaDiaz

installing/overview/cluster-capabilities.adoc

@@ -6,14 +6,16 @@ include::_attributes/common-attributes.adoc[]
 
 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.
+[role="_abstract"]
+As a cluster administrator, you can use cluster capabilities to enable or disable optional components before installation. Additionally, you can enable cluster capabilities at anytime after installation.
 
 [NOTE]
 ====
-Cluster administrators cannot disable a cluster capability after it is enabled.
+You cannot disable a cluster capability after it is enabled.
 ====
 
 include::modules/enabling-cluster-capabilities.adoc[leveloffset=+1]
+
 include::snippets/capabilities-table.adoc[]
 
 [role="_additional-resources"]
@@ -42,12 +44,20 @@ include::modules/build-config-capability.adoc[leveloffset=+2]
 // Cloud controller manager capability
 include::modules/cluster-cloud-controller-manager-operator.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://access.redhat.com/support/offerings/techpreview[Technology Preview]
+
+* link:https://github.com/openshift/cluster-cloud-controller-manager-operator[`cluster-cloud-controller-manager-operator`]
+
 // Cloud credential capability
 include::modules/cloud-credential-operator.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 * xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc#about-cloud-credential-operator[About the Cloud Credential Operator]
+* link:https://github.com/openshift/cloud-credential-operator[`openshift-cloud-credential-operator`]
 
 // Cluster Image Registry capability
 include::modules/cluster-image-registry-operator.adoc[leveloffset=+2]

modules/build-config-capability.adoc

@@ -6,9 +6,7 @@
 [id="build-config-capability_{context}"]
 = Build capability
 
-
-== Purpose
-
+[role="_abstract"]
 The `Build` capability enables the `Build` API. The `Build` API manages the lifecycle of `Build` and `BuildConfig` objects.
 
 [IMPORTANT]

modules/cloud-credential-operator.adoc

@@ -15,6 +15,7 @@ endif::[]
 ifdef::operators[= Cloud Credential Operator]
 ifdef::cluster-caps[= Cloud credential capability]
 
+[role="_abstract"]
 ifdef::cluster-caps[]
 The Cloud Credential Operator provides features for the `CloudCredential` capability.
 
@@ -29,21 +30,18 @@ The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubern
 By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in several different modes. If no mode is specified, or the `credentialsMode` parameter is set to an empty string (`""`), the CCO operates in its default mode.
 
 ifdef::operators[]
+Project::
 
-== Project
+See "openshift-cloud-credential-operator" in the _Additional resources_ section.
 
-link:https://github.com/openshift/cloud-credential-operator[openshift-cloud-credential-operator]
-
-
-== CRDs
+CRDs::
 
 * `credentialsrequests.cloudcredential.openshift.io`
 ** Scope: Namespaced
 ** CR: `CredentialsRequest`
 ** Validation: Yes
 
-
-== Configuration objects
+Configuration objects::
 
 No configuration required.
 endif::operators[]

modules/cluster-bare-metal-operator.adoc

@@ -16,19 +16,14 @@ endif::[]
 ifdef::operator-ref[= Cluster Baremetal Operator]
 ifdef::cluster-caps[= Bare-metal capability]
 
+[role="_abstract"]
 ifdef::operator-ref[]
+The Cluster Baremetal Operator is an optional cluster capability that can be disabled by cluster administrators during installation.
 
-[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 _Installing_.
-====
-
+For more information about optional cluster capabilities, see "Cluster capabilities".
 endif::operator-ref[]
-
 ifdef::cluster-caps[]
-
 The Cluster Baremetal Operator provides the features for the `baremetal` capability.
-
 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.
@@ -43,17 +38,14 @@ If the bare-metal capability is disabled, the cluster cannot provision or manage
 
 [NOTE]
 ====
-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.
+Red{nbsp}Hat recommends 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.
 ====
 endif::cluster-caps[]
 
 ifdef::operator-ref[]
-
-
-== Project
+Project::
 
 link:https://github.com/openshift/cluster-baremetal-operator[cluster-baremetal-operator]
-
 endif::operator-ref[]
 
 ifeval::["{context}" == "operator-reference"]

modules/cluster-cloud-controller-manager-operator.adoc

@@ -14,6 +14,7 @@ endif::[]
 ifdef::operators[= Cloud Controller Manager Operator]
 ifdef::cluster-caps[= Cloud controller manager capability]
 
+[role="_abstract"]
 ifdef::cluster-caps[]
 The Cloud Controller Manager Operator provides features for the `CloudControllerManager` capability.
 
@@ -41,7 +42,7 @@ endif::cluster-caps[]
 ====
 The status of this Operator is General Availability for {aws-first}, {gcp-first}, {ibm-cloud-name}, global {azure-full}, Microsoft Azure Stack Hub, Nutanix, {rh-openstack-first}, and {vmw-full}.
 
-The Operator is available as a link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] for {ibm-power-server-name}.
+The Operator is available as a Technology Preview for {ibm-power-server-name}.
 ====
 
 The Cloud Controller Manager Operator manages and updates the cloud controller managers deployed on top of {product-title}. The Operator is based on the Kubebuilder framework and `controller-runtime` libraries. You can install the Cloud Controller Manager Operator by using the Cluster Version Operator (CVO).
@@ -55,9 +56,9 @@ By default, the Operator exposes Prometheus metrics through the `metrics` servic
 
 ifdef::operators[]
 
-== Project
+Project::
 
-link:https://github.com/openshift/cluster-cloud-controller-manager-operator[cluster-cloud-controller-manager-operator]
+See "cluster-cloud-controller-manager-operator" in the _Additional resources_ section.
 endif::operators[]
 
 ifeval::["{context}" == "operator-reference"]

modules/enabling-cluster-capabilities.adoc

@@ -6,6 +6,7 @@
 [id="enabling-cluster-capabilities_{context}"]
 = Enabling cluster capabilities
 
+[role="_abstract"]
 If you are using an installation method that includes customizing your cluster by creating an `install-config.yaml` file, you can select which cluster capabilities you want to make available on the cluster.
 
 [NOTE]
@@ -18,21 +19,23 @@ You can use the following configuration parameters to select cluster capabilitie
 [source,yaml]
 ----
 capabilities:
-  baselineCapabilitySet: v4.11 <1>
-  additionalEnabledCapabilities: <2>
+  baselineCapabilitySet: v4.11
+  additionalEnabledCapabilities:
   - CSISnapshot
   - Console
   - Storage
 ----
-<1> Defines a baseline set of capabilities to install. Valid values are `None`, `vCurrent` and `v4.x`. If you select `None`, all optional capabilities are disabled. The default value is `vCurrent`, which enables all optional capabilities.
-+
+
+`capabilities.baselineCapabilitySet`:: Specifies a baseline set of capabilities to install. Valid values are `None`, `vCurrent` and `v4.x`. If you select `None`, all optional capabilities are disabled. The default value is `vCurrent`, which enables all optional capabilities.
+
 [NOTE]
 ====
 `v4.x` refers to any value up to and including the current cluster version.
 For example, valid values for a {product-title} 4.12 cluster are `v4.11` and `v4.12`.
 ====
-<2> Defines a list of capabilities to explicitly enable. These capabilities are enabled in addition to the capabilities specified in `baselineCapabilitySet`.
-+
+
+`capabilities.additionalEnabledCapabilities`:: Specifies a list of capabilities to explicitly enable. These capabilities are enabled in addition to the capabilities specified in `baselineCapabilitySet`.
+
 [NOTE]
 ====
 In this example, the default capability is set to `v4.11`. The `additionalEnabledCapabilities` field enables additional capabilities over the default `v4.11` capability set.

modules/explanation-of-capabilities.adoc

@@ -6,4 +6,7 @@
 [id="explanation_of_capabilities_{context}"]
 = Optional cluster capabilities in {product-title} {product-version}
 
-Currently, cluster Operators provide the features for these optional capabilities. The following summarizes the features provided by each capability and what functionality you lose if it is disabled.
+[role="_abstract"]
+Currently, cluster Operators provide the features for these optional capabilities. 
+
+The following sections summarize the features provided by each capability and what functionality you lose if you disable a functionality.