Rename/add intro in "Platform Operators reference" + Arch cleanup

adellape · adellape · commit 319cfc404b7d · 2022-01-26T14:56:19.000-07:00
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1391,7 +1391,7 @@ Topics:
   - Name: Migrating to Operator SDK v0.1.0
     File: osdk-migrating-to-v0-1-0
     Distros: openshift-origin
-- Name: Red Hat Operators reference
+- Name: Platform Operators reference
   File: operator-reference
 ---
 Name: CI/CD
diff --git a/architecture/control-plane.adoc b/architecture/control-plane.adoc
@@ -17,6 +17,19 @@ include::modules/architecture-machine-roles.adoc[leveloffset=+2]
 
 include::modules/operators-overview.adoc[leveloffset=+2]
 
+ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
+include::modules/arch-platform-operators.adoc[leveloffset=+3]
+.Additional resources
+
+* For an index of CVO-managed Operators, see xref:../operators/operator-reference.adoc#platform-operators-ref[Platform Operators reference].
+endif::[]
+
+include::modules/arch-olm-operators.adoc[leveloffset=+3]
+.Additional resources
+
+* For more details on running add-on Operators in {product-title}, see the _Operators_ guide sections on xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager (OLM)] and xref:../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[OperatorHub].
+* For more details on the Operator SDK, see xref:../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators].
+
 include::modules/update-service-overview.adoc[leveloffset=+3]
 
 include::modules/understanding-machine-config-operator.adoc[leveloffset=+3]
diff --git a/authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc b/authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc
@@ -89,4 +89,4 @@ To resolve insufficient credentials issues, provide a credential with sufficient
 [id="additional-resources_about-cloud-credential-operator"]
 == Additional resources
 
-* xref:../../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Red Hat Operators reference page for the Cloud Credential Operator]
+* xref:../../operators/operator-reference.adoc#cloud-credential-operator_platform-operators-ref[Platform Operators reference page for the Cloud Credential Operator]
diff --git a/modules/arch-olm-operators.adoc b/modules/arch-olm-operators.adoc
@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * architecture/control-plane.adoc
+
+[id="olm-operators_{context}"]
+= Add-on Operators
+
+Operator Lifecycle Manager (OLM) and OperatorHub are default components in {product-title} that help manage Kubernetes-native applications as Operators. Together they provide the system for discovering, installing, and managing the optional add-on Operators available on the cluster.
+
+Using OperatorHub in the {product-title} web console, cluster administrators and authorized users can select Operators to install from catalogs of Operators. After installing an Operator from OperatorHub, it can be made available globally or in specific namespaces to run in user applications.
+
+Default catalog sources are available that include Red Hat Operators, certified Operators, and community Operators. Cluster administrators can also add their own custom catalog sources, which can contain a custom set of Operators.
+
+Developers can use the Operator SDK to help author custom Operators that take advantage of OLM features, as well. Their Operator can then be bundled and added to a custom catalog source, which can be added to a cluster and made available to users.
+
+[NOTE]
+====
+OLM does not manage the platform Operators that comprise the {product-title} architecture.
+====
diff --git a/modules/arch-platform-operators.adoc b/modules/arch-platform-operators.adoc
@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * architecture/control-plane.adoc
+
+[id="platform-operators_{context}"]
+= Platform Operators
+
+In {product-title}, all cluster functions are divided into a series of default _platform Operators_, also known as cluster Operators. Platform Operators manage a particular area of cluster functionality, such as cluster-wide application logging, management of the Kubernetes control plane, or the machine provisioning system.
+
+Platform Operators are defined by a `ClusterOperator` object, which cluster administrators can view in the {product-title} web console from the *Administration* -> *Cluster Settings* page. Each platform Operator provides a simple API for determining cluster functionality. The Operator hides the details of managing the lifecycle of that component. Operators can manage a single component or tens of components, but the end goal is always to reduce operational burden by automating common actions.
diff --git a/modules/installation-aws-config-yaml.adoc b/modules/installation-aws-config-yaml.adoc
@@ -260,7 +260,7 @@ endif::gov,china[]
 ifdef::gov,china[]
 <1> Required.
 endif::gov,china[]
-<2> Optional: Add this parameter to force the Cloud Credential Operator (CCO) to use the specified mode, instead of having the CCO dynamically try to determine the capabilities of the credentials. For details about CCO modes, see the _Cloud Credential Operator_ entry in the _Red Hat Operators reference_ content.
+<2> Optional: Add this parameter to force the Cloud Credential Operator (CCO) to use the specified mode, instead of having the CCO dynamically try to determine the capabilities of the credentials. For details about CCO modes, see the _Cloud Credential Operator_ entry in the _Platform Operators reference_ content.
 <3> If you do not provide these parameters and values, the installation program
 provides the default value.
 <4> The `controlPlane` section is a single mapping, but the compute section is a
diff --git a/modules/installation-configuration-parameters.adoc b/modules/installation-configuration-parameters.adoc
@@ -551,7 +551,7 @@ accounts for the dramatically decreased machine performance.
 |The Cloud Credential Operator (CCO) mode. If no mode is specified, the CCO dynamically tries to determine the capabilities of the provided credentials, with a preference for mint mode on the platforms where multiple modes are supported.
 [NOTE]
 ====
-Not all CCO modes are supported for all cloud providers. For more information on CCO modes, see the _Cloud Credential Operator_ entry in the _Red Hat Operators reference_ content.
+Not all CCO modes are supported for all cloud providers. For more information on CCO modes, see the _Cloud Credential Operator_ entry in the _Platform Operators reference_ content.
 ====
 |`Mint`, `Passthrough`, `Manual`, or an empty string (`""`).
 ifndef::openshift-origin[]
diff --git a/modules/node-tuning-operator.adoc b/modules/node-tuning-operator.adoc
@@ -4,7 +4,7 @@
 // * operators/operator-reference.adoc
 // * post_installation_configuration/node-tasks.adoc
 
-ifeval::["{context}" == "red-hat-operators"]
+ifeval::["{context}" == "platform-operators-ref"]
 :operators:
 endif::[]
 ifeval::["{context}" == "node-tuning-operator"]
diff --git a/modules/olm-architecture.adoc b/modules/olm-architecture.adoc
@@ -4,10 +4,10 @@
 // * operators/operator-reference.adoc
 
 [id="olm-architecture_{context}"]
-ifeval::["{context}" != "red-hat-operators"]
+ifeval::["{context}" != "platform-operators-ref"]
 = Component responsibilities
 endif::[]
-ifeval::["{context}" == "red-hat-operators"]
+ifeval::["{context}" == "platform-operators-ref"]
 = CRDs
 endif::[]
 
diff --git a/modules/olm-overview.adoc b/modules/olm-overview.adoc
@@ -4,10 +4,10 @@
 // * operators/operator-reference.adoc
 
 [id="olm-overview_{context}"]
-ifeval::["{context}" != "red-hat-operators"]
+ifeval::["{context}" != "platform-operators-ref"]
 = What is Operator Lifecycle Manager?
 endif::[]
-ifeval::["{context}" == "red-hat-operators"]
+ifeval::["{context}" == "platform-operators-ref"]
 = Purpose
 endif::[]
 
diff --git a/modules/operators-overview.adoc b/modules/operators-overview.adoc
@@ -1,62 +1,19 @@
 // Module included in the following assemblies:
 //
-// * architecture/architecture.adoc
+// * architecture/control-plane.adoc
 
 [id="operators-overview_{context}"]
 = Operators in {product-title}
 
-In {product-title}, Operators are the preferred method of packaging, deploying,
-and managing services on the control plane. They also provide advantages to
-applications that users run. Operators integrate with
-Kubernetes APIs and CLI tools such as `kubectl` and `oc` commands. They provide
-the means of watching over an application, performing health checks, managing
-over-the-air updates, and ensuring that the applications remain in your
-specified state.
+Operators are among the most important components of {product-title}. Operators are the preferred method of packaging, deploying, and managing services on the control plane. They can also provide advantages to applications that users run.
 
-Because CRI-O and the Kubelet run on every node, almost every other cluster
-function can be managed on the control plane by using Operators. Operators are
-among the most important components of {product-title} {product-version}.
-Components that are added to the control plane by using Operators include
-critical networking and credential services.
+Operators integrate with Kubernetes APIs and CLI tools such as `kubectl` and `oc` commands. They provide the means of monitoring applications, performing health checks, managing over-the-air (OTA) updates, and ensuring that applications remain in your specified state.
 
-The Operator that manages the other Operators in an {product-title} cluster is
-the Cluster Version Operator.
+Operators also offer a more granular configuration experience. You configure each component by modifying the API that the Operator exposes instead of modifying a global configuration file.
 
-{product-title} {product-version} uses different classes of Operators to perform
-cluster operations and run services on the cluster for your applications to use.
+Because CRI-O and the Kubelet run on every node, almost every other cluster function can be managed on the control plane by using Operators. Components that are added to the control plane by using Operators include critical networking and credential services.
 
-ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-[id="platform-operators_{context}"]
-== Platform Operators in {product-title}
+While both follow similar Operator concepts and goals, Operators in {product-title} are managed by two different systems, depending on their purpose:
 
-In {product-title} {product-version}, all cluster functions are divided into a series
-of platform Operators. Platform Operators manage a particular area of
-cluster functionality, such as cluster-wide application logging, management of
-the Kubernetes control plane, or the machine provisioning system.
-
-Each Operator provides you with a simple API for determining cluster
-functionality. The Operator hides the details of managing the lifecycle of that
-component. Operators can manage a single component or tens of components, but
-the end goal is always to reduce operational burden by automating common actions.
-Operators also offer a more granular configuration experience. You configure each
-component by modifying the API that the Operator exposes instead of modifying a
-global configuration file.
-
-endif::[]
-
-[id="OLM-operators_{context}"]
-== Operators managed by OLM
-
-The Cluster Operator Lifecycle Management (OLM) component manages Operators
-that are available for use in applications. It does not manage the Operators that
-comprise {product-title}.
-OLM is a framework that manages Kubernetes-native applications as Operators.
-Instead of managing Kubernetes manifests, it manages Kubernetes Operators.
-OLM manages two classes of Operators, Red Hat Operators and certified Operators.
-
-Some Red Hat Operators drive the cluster functions, like the scheduler and
-problem detectors. Others are provided for you to manage yourself and use in
-your applications, like etcd. {product-title} also offers certified Operators,
-which the community built and maintains. These certified Operators provide an
-API layer to traditional applications so you can manage the application through
-Kubernetes constructs.
+* Platform Operators, which are managed by the Cluster Version Operator (CVO), are installed by default to perform cluster functions.
+* Optional add-on Operators, which are managed by Operator Lifecycle Manager (OLM), can be made accessible for users to run in their applications.
diff --git a/modules/psap-node-feature-discovery-operator.adoc b/modules/psap-node-feature-discovery-operator.adoc
@@ -2,7 +2,7 @@
 //
 // * hardware_enablement/psap-node-feature-discovery-operator.adoc
 
-ifeval::["{context}" == "red-hat-operators"]
+ifeval::["{context}" == "platform-operators-ref"]
 :operators:
 endif::[]
 ifeval::["{context}" == "node-feature-discovery-operator"]
diff --git a/modules/vsphere-problem-detector-operator.adoc b/modules/vsphere-problem-detector-operator.adoc
@@ -10,7 +10,12 @@
 [discrete]
 == Purpose
 
-The {operator-name} checks the cluster for common installation and misconfiguration issues.
+The {operator-name} checks clusters that are deployed on vSphere for common installation and misconfiguration issues that are related to storage.
+
+[NOTE]
+====
+The {operator-name} is only started by the Cluster Storage Operator when the Cluster Storage Operator detects that the cluster is deployed on vSphere.
+====
 
 [discrete]
 == Configuration
diff --git a/nodes/edge/nodes-edge-remote-workers.adoc b/nodes/edge/nodes-edge-remote-workers.adoc
@@ -52,4 +52,4 @@ include::modules/nodes-edge-remote-workers-strategies.adoc[leveloffset=+1]
 
 * For more information on replication controllers, see xref:../../applications/deployments/what-deployments-are.html#deployments-replicationcontrollers_what-deployments-are[Replication controllers].
 
-* For more information on the controller manager, see xref:../../operators/operator-reference.html#kube-controller-manager-operator_red-hat-operators[Kubernetes Controller Manager Operator].
+* For more information on the controller manager, see xref:../../operators/operator-reference.html#kube-controller-manager-operator_platform-operators-ref[Kubernetes Controller Manager Operator].
diff --git a/operators/operator-reference.adoc b/operators/operator-reference.adoc
@@ -1,13 +1,22 @@
-[id="red-hat-operators"]
-= Red Hat Operators
+[id="platform-operators-ref"]
+= Platform Operators reference
 include::modules/common-attributes.adoc[]
-:context: red-hat-operators
+:context: platform-operators-ref
 
 toc::[]
 
+This reference guide indexes the _platform Operators_, also known as cluster Operators, shipped by Red Hat that serve as the architectural foundation for {product-title}. Platform Operators are installed by default, unless otherwise noted, and are managed by the Cluster Version Operator (CVO). For more details on the control plane architecture, see xref:../architecture/control-plane.adoc#operators-overview_control-plane[Operators in {product-title}].
+
+Cluster administrators can view platform Operators in the {product-title} web console from the *Administration* -> *Cluster Settings* page.
+
+[NOTE]
+====
+Platform 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].
+====
+
 include::modules/cloud-credential-operator.adoc[leveloffset=+1]
 [discrete]
-[id="red-hat-operators-cco-addtl-resources"]
+[id="platform-operators-ref-cco-addtl-resources"]
 === Additional resources
 
 * xref:../rest_api/security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[CredentialsRequest custom resource]
@@ -43,7 +52,7 @@ include::modules/node-tuning-operator.adoc[leveloffset=+1]
 include::modules/openshift-apiserver-operator.adoc[leveloffset=+1]
 include::modules/cluster-openshift-controller-manager-operators.adoc[leveloffset=+1]
 
-[id="red-hat-operators-olm"]
+[id="platform-operators-ref-olm"]
 == Operator Lifecycle Manager Operators
 [discrete]
 include::modules/olm-overview.adoc[leveloffset=+2]
@@ -56,11 +65,12 @@ include::modules/olm-arch-catalog-operator.adoc[leveloffset=+2]
 [discrete]
 include::modules/olm-arch-catalog-registry.adoc[leveloffset=+2]
 [discrete]
-[id="red-hat-operators-olm-addtl-resources"]
+[id="platform-operators-ref-olm-addtl-resources"]
 === Additional resources
 
 For more information, see the sections on xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[understanding Operator Lifecycle Manager (OLM)].
 
-include::modules/prometheus-operator.adoc[leveloffset=+1]
 include::modules/vsphere-problem-detector-operator.adoc[leveloffset=+1]
-include::modules/windows-machine-config-operator.adoc[leveloffset=+1]
+.Additional resources
+
+* For more details, see xref:../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#using-vsphere-problem-detector-operator[Using the vSphere Problem Detector Operator].
diff --git a/operators/understanding/olm-what-operators-are.adoc b/operators/understanding/olm-what-operators-are.adoc
@@ -7,7 +7,7 @@ toc::[]
 
 Conceptually, _Operators_ take human operational knowledge and encode it into software that is more easily shared with consumers.
 
-Operators are pieces of software that ease the operational complexity of running another piece of software. They act like an extension of the software vendor's engineering team, watching over a Kubernetes environment (such as {product-title}) and using its current state to make decisions in real time. Advanced Operators are designed to handle upgrades seamlessly, react to failures automatically, and not take shortcuts, like skipping a software backup process to save time.
+Operators are pieces of software that ease the operational complexity of running another piece of software. They act like an extension of the software vendor's engineering team, monitoring a Kubernetes environment (such as {product-title}) and using its current state to make decisions in real time. Advanced Operators are designed to handle upgrades seamlessly, react to failures automatically, and not take shortcuts, like skipping a software backup process to save time.
 
 More technically, Operators are a method of packaging, deploying, and managing a Kubernetes application.
 
diff --git a/post_installation_configuration/cluster-tasks.adoc b/post_installation_configuration/cluster-tasks.adoc
@@ -625,7 +625,7 @@ include::modules/nodes-pods-pod-disruption-configuring.adoc[leveloffset=+2]
 
 After installing {product-title}, some organizations require the rotation or removal of the cloud provider credentials that were used during the initial installation.
 
-To allow the cluster to use the new credentials, you must update the secrets that the xref:../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator (CCO)] uses to manage cloud provider credentials.
+To allow the cluster to use the new credentials, you must update the secrets that the xref:../operators/operator-reference.adoc#cloud-credential-operator_platform-operators-ref[Cloud Credential Operator (CCO)] uses to manage cloud provider credentials.
 
 include::modules/manually-rotating-cloud-creds.adoc[leveloffset=+2]
 
