Merge pull request #74265 from bburt-rh/OBSDOCS-910-clarify-what-CMO-fields-are-available-to-config

OBSDOCS-910: clarify  what CMO fields are available and supported for configuration

Author: bburt-rh

modules/monitoring-maintenance-and-support.adoc

@@ -5,7 +5,9 @@
 [id="maintenance-and-support_{context}"]
 = Maintenance and support for monitoring
 
-The supported way of configuring {product-title} Monitoring is by configuring it using the options described in this document. *Do not use other configurations, as they are unsupported.* Configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use configurations other than those described in this section, your changes will disappear because the `cluster-monitoring-operator` reconciles any differences. The Operator resets everything to the defined state by default and by design.
+Not all configuration options for the monitoring stack are exposed. The only supported way of configuring {product-title} monitoring is by configuring the Cluster Monitoring Operator using the options described in the "Config map reference for the Cluster Monitoring Operator". *Do not use other configurations, as they are unsupported.*
+
+Configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use configurations other than those described in the "Config map reference for the Cluster Monitoring Operator", your changes will disappear because the Cluster Monitoring Operator automatically reconciles any differences and resets any unsupported changes back to the originally defined state by default and by design.
 
 ifdef::openshift-dedicated,openshift-rosa[]
 [IMPORTANT]

modules/monitoring-support-considerations.adoc

@@ -6,6 +6,11 @@
 [id="support-considerations_{context}"]
 = Support considerations for monitoring
 
+[NOTE]
+====
+Backward compatibility for metrics, recording rules, or alerting rules is not guaranteed.
+====
+
 The following modifications are explicitly not supported:
 
 ifndef::openshift-dedicated,openshift-rosa[]
@@ -23,11 +28,6 @@ This procedure is a supported exception to the preceding statement.
 * *Modifying resources of the stack.* The {product-title} monitoring stack ensures its resources are always in the state it expects them to be. If they are modified, the stack will reset them.
 * *Deploying user-defined workloads to `openshift-*`, and `kube-*` projects.* These projects are reserved for Red Hat provided components and they should not be used for user-defined workloads.
 * *Enabling symptom based monitoring by using the `Probe` custom resource definition (CRD) in Prometheus Operator.*
-
-[NOTE]
-====
-Backward compatibility for metrics, recording rules, or alerting rules is not guaranteed.
-====
 endif::openshift-dedicated,openshift-rosa[]
 
 * *Installing custom Prometheus instances on {product-title}.* A custom instance is a Prometheus custom resource (CR) managed by the Prometheus Operator.

monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc

@@ -25,9 +25,11 @@ These configurations are defined by link:#userworkloadconfiguration[UserWorkload
 
 The configuration file is always defined under the `config.yaml` key in the config map data.
 
-[NOTE]
+[IMPORTANT]
 ====
-* Not all configuration parameters are exposed.
+* Not all configuration parameters for the monitoring stack are exposed.
+Only the parameters and fields listed in this reference are supported for configuration.
+For more information about supported configurations, see xref:../monitoring/configuring-the-monitoring-stack.adoc#maintenance-and-support_configuring-the-monitoring-stack[Maintenance and support for monitoring].
 * Configuring cluster monitoring is optional.
 * If a configuration does not exist or is empty, default values are used.
 * If the configuration is invalid YAML data, the Cluster Monitoring Operator stops reconciling the resources and reports `Degraded=True` in the status conditions of the Operator.
@@ -170,7 +172,7 @@ The `ClusterMonitoringConfiguration` resource defines settings that customize th
 
 [IMPORTANT]
 ====
-This setting is deprecated and is planned to be removed in a future {product-title} version. 
+This setting is deprecated and is planned to be removed in a future {product-title} version.
 In the current version, this setting still exists but has no effect.
 ====
 
@@ -244,7 +246,7 @@ Appears in: link:#clustermonitoringconfiguration[ClusterMonitoringConfiguration]
 
 [options="header"]
 |===
-| Property | Type | Description 
+| Property | Type | Description
 |nodeSelector|map[string]string|Defines the nodes on which the pods are scheduled.
 
 |tolerations|[]v1.Toleration|Defines tolerations for the pods.
@@ -653,7 +655,7 @@ link:#prometheusrestrictedconfig[PrometheusRestrictedConfig]
 
 |remoteTimeout|string|Defines the timeout value for requests to the remote write endpoint.
 
-|sendExemplars|*bool|Enables sending exemplars via remote write. When enabled, this setting configures Prometheus to store a maximum of 100,000 exemplars in memory. 
+|sendExemplars|*bool|Enables sending exemplars via remote write. When enabled, this setting configures Prometheus to store a maximum of 100,000 exemplars in memory.
 This setting only applies to user-defined monitoring and is not applicable to core platform monitoring.
 
 |sigv4|*monv1.Sigv4|Defines AWS Signature Version 4 authentication settings.

monitoring/configuring-the-monitoring-stack.adoc

@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 ifndef::openshift-dedicated,openshift-rosa[]
-The {product-title} 4 installation program provides only a low number of configuration options before installation. Configuring most {product-title} framework components, including the cluster monitoring stack, happens postinstallation.
+The {product-title} installation program provides only a low number of configuration options before installation. Configuring most {product-title} framework components, including the cluster monitoring stack, happens after the installation.
 endif::openshift-dedicated,openshift-rosa[]
 
 This section explains what configuration is supported,
@@ -19,14 +19,38 @@ shows how to configure the monitoring stack for user-defined projects,
 endif::openshift-dedicated,openshift-rosa[]
 and demonstrates several common configuration scenarios.
 
+[IMPORTANT]
+====
+Not all configuration parameters for the monitoring stack are exposed.
+Only the parameters and fields listed in the xref:../monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc#cluster-monitoring-operator-configuration-reference[Config map reference for the Cluster Monitoring Operator] are supported for configuration.
+====
+
 ifndef::openshift-dedicated,openshift-rosa[]
 == Prerequisites
 
 * The monitoring stack imposes additional resource requirements. Consult the computing resources recommendations in xref:../scalability_and_performance/recommended-performance-scale-practices/recommended-infrastructure-practices.adoc#scaling-cluster-monitoring-operator[Scaling the Cluster Monitoring Operator] and verify that you have sufficient resources.
 endif::openshift-dedicated,openshift-rosa[]
 
 // Maintenance and support for monitoring
-include::modules/monitoring-maintenance-and-support.adoc[leveloffset=+1]
+// include::modules/monitoring-maintenance-and-support.adoc[leveloffset=+1]
+
+// .Additional resources
+// xref:../monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc#cluster-monitoring-operator-configuration-reference[Config map reference for the Cluster Monitoring Operator]
+
+[id="maintenance-and-support_{context}"]
+== Maintenance and support for monitoring
+
+Not all configuration options for the monitoring stack are exposed. The only supported way of configuring {product-title} monitoring is by configuring the Cluster Monitoring Operator using the options described in the xref:../monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc#cluster-monitoring-operator-configuration-reference[Config map reference for the Cluster Monitoring Operator]. *Do not use other configurations, as they are unsupported.*
+
+Configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use configurations other than those described in the xref:../monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc#cluster-monitoring-operator-configuration-reference[Config map reference for the Cluster Monitoring Operator], your changes will disappear because the Cluster Monitoring Operator automatically reconciles any differences and resets any unsupported changes back to the originally defined state by default and by design.
+
+ifdef::openshift-dedicated,openshift-rosa[]
+[IMPORTANT]
+====
+Installing another Prometheus instance is not supported by the Red Hat Site Reliability Engineers (SRE).
+====
+endif::openshift-dedicated,openshift-rosa[]
+
 include::modules/monitoring-support-considerations.adoc[leveloffset=+2]
 ifndef::openshift-dedicated,openshift-rosa[]
 include::modules/monitoring-unmanaged-monitoring-operators.adoc[leveloffset=+2]
@@ -122,7 +146,7 @@ endif::openshift-dedicated,openshift-rosa[]
 // Configuring limits and resource requests for monitoring components
 
 [id="managing-cpu-and-memory-resources-for-monitoring-components"]
-== Managing CPU and memory resources for monitoring components 
+== Managing CPU and memory resources for monitoring components
 
 You can ensure that the containers that run monitoring components have enough CPU and memory resources by specifying values for resource limits and requests for those components.