Merge pull request #50830 from michaelryanpeter/osdocs-4198-optional-ocp-operators

OSDOCS-4198: Explain optional capabilities

Author: michaelryanpeter

modules/cluster-bare-metal-operator.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// *  operators/operator-reference.adoc
+// *  post_installation_configuration/cluster-capabilities.adoc
+
+ifeval::["{context}" == "cluster-operators-ref"]
+:operator-ref:
+endif::[]
+
+ifeval::["{context}" == "cluster-capabilities"]
+:cluster-caps:
+endif::[]
+
+:_content-type: REFERENCE
+[id="cluster-bare-metal-operator_{context}"]
+ifdef::operator-ref[= Cluster Baremetal Operator]
+ifdef::cluster-caps[= Bare-metal capability]
+
+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_.
+====
+
+endif::operator-ref[]
+
+[discrete]
+== Purpose
+
+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. 
+
+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.
+
+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. 
+
+[IMPORTANT]
+====
+If the bare-metal capability is disabled, the cluster cannot provision or manage bare-metal nodes. Only disable the capability if there are no `BareMetalHost` resources in your deployment.
+====
+endif::cluster-caps[]
+
+ifdef::operator-ref[]
+
+[discrete]
+== Project
+
+link:https://github.com/openshift/cluster-baremetal-operator[cluster-baremetal-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,19 +1,50 @@
 // Module included in the following assemblies:
 //
 // *  operators/operator-reference.adoc
+// *  post_installation_configuration/cluster-capabilities.adoc
 
+// operators/operator-reference.adoc
+ifeval::["{context}" == "cluster-operators-ref"]
+:operator-ref:
+endif::[]
+
+// post_installation_configuration/cluster-capabilities.adoc
+ifeval::["{context}" == "cluster-capabilities"]
+:cluster-caps:
+endif::[]
+
+:_content-type: REFERENCE
 [id="cluster-samples-operator_{context}"]
-= Cluster Samples Operator
+ifdef::operator-ref[= Cluster Samples Operator]
+ifdef::cluster-caps[= OpenShift samples capability]
+
+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_.
+====
+
+endif::operator-ref[]
 
 [discrete]
 == Purpose
 
+ifdef::cluster-caps[]
+The Cluster Samples Operator provides the features for the `openshift-samples` capability.
+endif::cluster-caps[]
+
 The Cluster Samples Operator manages the sample image streams and templates stored in the `openshift` namespace.
 
 On initial start up, the Operator creates the default samples configuration resource to initiate the creation of the image streams and templates. The configuration object is a cluster scoped object with the key `cluster` and type `configs.samples`.
 
 The image streams are the {op-system-first}-based {product-title} image streams pointing to images on `registry.redhat.io`. Similarly, the templates are those categorized as {product-title} templates.
 
+ifdef::cluster-caps[]
+If you disable the samples capability, users cannot access the image streams, samples, and templates it provides. Depending on your deployment, you might want to disable this component if you do not need it.
+endif::[]
+
+ifdef::operator-ref[]
 The Cluster Samples Operator deployment is contained within the `openshift-cluster-samples-operator` namespace. On start up, the install pull secret is used by the image stream import logic in the internal registry and API server to authenticate with `registry.redhat.io`. An administrator can create any additional secrets in the `openshift` namespace if they change the registry used for the sample image streams. If created, those secrets contain the content of a `config.json` for `docker` needed to facilitate image import.
 
 The image for the Cluster Samples Operator contains image stream and template definitions for the associated {product-title} release. After the Cluster Samples Operator creates a sample, it adds an annotation that denotes the {product-title} version that it is compatible with. The Operator uses this annotation to ensure that each sample matches the compatible release version. Samples outside of its inventory are ignored, as are skipped samples.
@@ -33,3 +64,12 @@ Upon deletion of the samples resource, the Cluster Samples Operator recreates th
 == Project
 
 link:https://github.com/openshift/cluster-samples-operator[cluster-samples-operator]
+endif::operator-ref[]
+
+ifeval::["{context}" == "cluster-operators-ref"]
+:!operator-ref:
+endif::[]
+
+ifeval::["{context}" == "cluster-caps"]
+:!cluster-caps:
+endif::[]

modules/explanation-of-capabilities.adoc

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// *post_installation_configuration/cluster-capabilities.adoc
+
+:_content-type: REFERENCE
+[id="explanation_of_capabilities_{context}"]
+= Optional cluster capabilities in {product-title} {product-version}
+
+Optional cluster capabilities are components that can be disabled during the installation process. Cluster administrators can disable optional cluster capabilities to reduce the resources consumed by a cluster. Currently, cluster Operators provide a cluster capability's features. 
+
+If you want to use the features provided by a disabled cluster capability, you can enable the capability after installation. After a cluster capability is enabled, it cannot be disabled.

modules/operator-marketplace.adoc

@@ -1,16 +1,61 @@
 // Module included in the following assemblies:
 //
 // * operators/operator-reference.adoc
+// *  post_installation_configuration/cluster-capabilities.adoc
 
+// operators/operator-reference.adoc
+ifeval::["{context}" == "cluster-operators-ref"]
+:operator-ref:
+endif::[]
+
+// post_installation_configuration/cluster-capabilities.adoc
+ifeval::["{context}" == "cluster-capabilities"]
+:cluster-caps:
+endif::[]
+
+:_content-type: REFERENCE
 [id="marketplace-operator_{context}"]
-= Marketplace Operator
+ifdef::operator-ref[= Marketplace Operator]
+ifdef::cluster-caps[= Marketplace capability]
+
+ifdef::operator-ref[]
+
+[NOTE]
+====
+The Marketplace 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_.
+====
+
+endif::operator-ref[]
 
 [discrete]
 == Purpose
 
-The Marketplace Operator is a conduit to bring off-cluster Operators to your cluster.
+ifdef::cluster-caps[]
+
+The Marketplace Operator provides the features for the `marketplace` capability.
+
+endif::cluster-caps[]
 
+The Marketplace Operator simplifies the process for bringing off-cluster Operators to your cluster by using a set of default Operator Lifecycle Manager (OLM) catalogs on the cluster. When the Marketplace Operator is installed, it creates the `openshift-marketplace` namespace. OLM ensures catalog sources installed in the `openshift-marketplace` namespace are available for all namespaces on the cluster.
+
+ifdef::cluster-caps[]
+If you disable the `marketplace` capability, the Marketplace Operator does not create the `openshift-marketplace` namespace. Catalog sources can still be configured and managed on the cluster manually, but OLM depends on the `openshift-marketplace` namespace in order to make catalogs available to all namespaces on the cluster. Users with elevated permissions to create namespaces prefixed with `openshift-`, such as system or cluster administrators, can manually create the `openshift-marketplace` namespace.
+
+If you enable the `marketplace` capability, you can enable and disable individual catalogs by configuring the Marketplace Operator.
+endif::cluster-caps[]
+
+ifdef::operator-ref[]
 [discrete]
 == Project
 
 link:https://github.com/operator-framework/operator-marketplace[operator-marketplace]
+
+endif::operator-ref[]
+
+ifeval::["{context}" == "cluster-operators-ref"]
+:!operator-ref:
+endif::[]
+
+ifeval::["{context}" == "cluster-caps"]
+:!cluster-caps:
+endif::[]

operators/operator-reference.adoc

@@ -15,7 +15,13 @@ Cluster administrators can view cluster Operators in the {product-title} web con
 Cluster Operators are not managed by Operator Lifecycle Manager (OLM) and OperatorHub. OLM and OperatorHub are part of the link:https://operatorframework.io/[Operator Framework] used in {product-title} for installing and running optional xref:../architecture/control-plane.adoc#olm-operators_control-plane[add-on Operators].
 ====
 
-Some of the following operators can be disabled prior to installation. For more information see xref:../post_installation_configuration/cluster-capabilities.adoc#viewing_the_cluster_capabilities_cluster-capabilities[Viewing the cluster capabilities].
+Some of the following cluster Operators can be disabled prior to installation. For more information see xref:../post_installation_configuration/cluster-capabilities.adoc#viewing_the_cluster_capabilities_cluster-capabilities[Viewing the cluster capabilities].
+
+include::modules/cluster-bare-metal-operator.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../post_installation_configuration/cluster-capabilities.adoc#cluster-bare-metal-operator_cluster-capabilities[Bare-metal capability]
 
 include::modules/baremetal-event-relay.adoc[leveloffset=+1]
 
@@ -47,6 +53,12 @@ include::modules/cluster-machine-approver-operator.adoc[leveloffset=+1]
 include::modules/cluster-monitoring-operator.adoc[leveloffset=+1]
 include::modules/cluster-network-operator.adoc[leveloffset=+1]
 include::modules/cluster-samples-operator.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../post_installation_configuration/cluster-capabilities.adoc#cluster-samples-operator_cluster-capabilities[OpenShift samples capability]
+
 include::modules/cluster-storage-operator.adoc[leveloffset=+1]
 include::modules/cluster-version-operator.adoc[leveloffset=+1]
 
@@ -87,6 +99,12 @@ include::modules/cluster-kube-storage-version-migrator-operator.adoc[leveloffset
 include::modules/machine-api-operator.adoc[leveloffset=+1]
 include::modules/machine-config-operator.adoc[leveloffset=+1]
 include::modules/operator-marketplace.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../post_installation_configuration/cluster-capabilities.adoc#marketplace-operator_cluster-capabilities[Marketplace capability]
+
 include::modules/node-tuning-operator.adoc[leveloffset=+1]
 
 [discrete]
@@ -127,4 +145,4 @@ include::modules/vsphere-problem-detector-operator.adoc[leveloffset=+1]
 [id="additional-resources_cluster-op-ref-vpd"]
 === Additional resources
 
-* xref:../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#using-vsphere-problem-detector-operator[Using the vSphere Problem Detector Operator]
+* xref:../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#using-vsphere-problem-detector-operator[Using the vSphere Problem Detector Operator]

post_installation_configuration/cluster-capabilities.adoc

@@ -6,26 +6,41 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Cluster administrators can use the cluster capabilities to select or deselect one or more optional components prior to installation and also enable a cluster capability anytime post installation.
+Cluster administrators can use cluster capabilities to disable one or more optional components prior to xref:../installing/index.adoc#ocp-installation-overview[installation]. Cluster administrators can enable cluster capabilities at anytime after installation.
 
 [NOTE]
 ====
-If cluster capability has been enabled before, it cannot be disabled.
+Cluster administrators cannot disable a cluster capability after it is enabled.
 ====
 
-include::modules/viewing-cluster-capabilities.adoc[leveloffset=+1]
+include::modules/explanation-of-capabilities.adoc[leveloffset=+1]
 
-include::modules/enabling-baseline-capability-set.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[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]
 
-The following are the capabilities defined in `v4.11`:
+include::modules/cluster-samples-operator.adoc[leveloffset=+2]
 
-* xref:../installing/installing_bare_metal_ipi/ipi-install-overview.adoc#ipi-install[Bare metal]
+[role="_additional-resources"]
+.Additional resources
+* xref:../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Configuring the Cluster Samples Operator]
 
-* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Marketplace]
+include::modules/operator-marketplace.adoc[leveloffset=+2]
 
-* xref:../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[OpenShift-samples]
+[role="_additional-resources"]
+.Additional resources
+* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red Hat-provided Operator catalogs]
+
+include::modules/viewing-cluster-capabilities.adoc[leveloffset=+1]
+
+include::modules/enabling-baseline-capability-set.adoc[leveloffset=+1]
 
 include::modules/enabling-additional-enabled-capabilities.adoc[leveloffset=+1]