Merge pull request #74822 from eromanova97/OBSDOCS-432

OBSDOCS-432: Documentation updates for changes to topology spread constraints for monitoring

Author: ShaunaDiaz

modules/monitoring-configuring-pod-topology-spread-constraints.adoc

@@ -0,0 +1,180 @@
+// Module included in the following assemblies:
+//
+// * observability/monitoring/configuring-the-monitoring-stack.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-pod-topology-spread-constraints_{context}"]
+= Configuring pod topology spread constraints
+
+You can configure pod topology spread constraints for 
+ifndef::openshift-dedicated,openshift-rosa[]
+all the pods deployed by the Cluster Monitoring Operator
+endif::openshift-dedicated,openshift-rosa[]
+ifdef::openshift-dedicated,openshift-rosa[]
+all the pods for user-defined monitoring
+endif::openshift-dedicated,openshift-rosa[]
+to control how pod replicas are scheduled to nodes across zones.
+This ensures that the pods are highly available and run more efficiently, because workloads are spread across nodes in different data centers or hierarchical infrastructure zones.
+
+You can configure pod topology spread constraints for monitoring pods by using 
+ifndef::openshift-dedicated,openshift-rosa[]
+the `cluster-monitoring-config` or 
+endif::openshift-dedicated,openshift-rosa[]
+the `user-workload-monitoring-config` config map.
+
+.Prerequisites
+
+ifndef::openshift-dedicated,openshift-rosa[]
+* *If you are configuring pods for core {product-title} monitoring:*
+** You have access to the cluster as a user with the `cluster-admin` cluster role.
+** You have created the `cluster-monitoring-config` `ConfigMap` object.
+* *If you are configuring pods for user-defined monitoring:*
+** A cluster administrator has enabled monitoring for user-defined projects.
+** You have access to the cluster as a user with the `cluster-admin` cluster role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project.
+endif::openshift-dedicated,openshift-rosa[]
+ifdef::openshift-dedicated,openshift-rosa[]
+* You have access to the cluster as a user with the `dedicated-admin` role.
+* The `user-workload-monitoring-config` `ConfigMap` object exists. This object is created by default when the cluster is created.
+endif::openshift-dedicated,openshift-rosa[]
+
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+ifndef::openshift-dedicated,openshift-rosa[]
+* *To configure pod topology spread constraints for core {product-title} monitoring:*
+
+. Edit the `cluster-monitoring-config` config map in the `openshift-monitoring` project:
++
+[source,terminal]
+----
+$ oc -n openshift-monitoring edit configmap cluster-monitoring-config
+----
+
+. Add the following settings under the `data/config.yaml` field to configure pod topology spread constraints:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-monitoring-config
+  namespace: openshift-monitoring
+data:
+  config.yaml: |
+    <component>: # <1>
+      topologySpreadConstraints:
+      - maxSkew: <n> # <2>
+        topologyKey: <key> # <3>
+        whenUnsatisfiable: <value> # <4>
+        labelSelector: # <5>
+          <match_option>
+----
+<1> Specify a name of the component for which you want to set up pod topology spread constraints.
+<2> Specify a numeric value for `maxSkew`, which defines the degree to which pods are allowed to be unevenly distributed.
+<3> Specify a key of node labels for `topologyKey`.
+Nodes that have a label with this key and identical values are considered to be in the same topology.
+The scheduler tries to put a balanced number of pods into each domain.
+<4> Specify a value for `whenUnsatisfiable`.
+Available options are `DoNotSchedule` and `ScheduleAnyway`.
+Specify `DoNotSchedule` if you want the `maxSkew` value to define the maximum difference allowed between the number of matching pods in the target topology and the global minimum.
+Specify `ScheduleAnyway` if you want the scheduler to still schedule the pod but to give higher priority to nodes that might reduce the skew.
+<5> Specify `labelSelector` to find matching pods. 
+Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain.
++
+.Example configuration for Prometheus
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-monitoring-config
+  namespace: openshift-monitoring
+data:
+  config.yaml: |
+    prometheusK8s:
+      topologySpreadConstraints:
+      - maxSkew: 1
+        topologyKey: monitoring
+        whenUnsatisfiable: DoNotSchedule
+        labelSelector:
+          matchLabels:
+            app.kubernetes.io/name: prometheus
+----
+
+. Save the file to apply the changes automatically.
++
+[WARNING]
+====
+When you save changes to the `cluster-monitoring-config` config map, the pods and other resources in the `openshift-monitoring` project might be redeployed.
+The running monitoring processes in that project might also restart.
+====
+
+* *To configure pod topology spread constraints for user-defined monitoring:*
+endif::openshift-dedicated,openshift-rosa[]
+
+. Edit the `user-workload-monitoring-config` config map in the `openshift-user-workload-monitoring` project:
++
+[source,terminal]
+----
+$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config
+----
+
+. Add the following settings under the `data/config.yaml` field to configure pod topology spread constraints:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: user-workload-monitoring-config
+  namespace: openshift-user-workload-monitoring
+data:
+  config.yaml: |
+    <component>: # <1>
+      topologySpreadConstraints:
+      - maxSkew: <n> # <2>
+        topologyKey: <key> # <3>
+        whenUnsatisfiable: <value> # <4>
+        labelSelector: # <5>
+          <match_option>
+----
+<1> Specify a name of the component for which you want to set up pod topology spread constraints.
+<2> Specify a numeric value for `maxSkew`, which defines the degree to which pods are allowed to be unevenly distributed.
+<3> Specify a key of node labels for `topologyKey`.
+Nodes that have a label with this key and identical values are considered to be in the same topology.
+The scheduler tries to put a balanced number of pods into each domain.
+<4> Specify a value for `whenUnsatisfiable`.
+Available options are `DoNotSchedule` and `ScheduleAnyway`.
+Specify `DoNotSchedule` if you want the `maxSkew` value to define the maximum difference allowed between the number of matching pods in the target topology and the global minimum.
+Specify `ScheduleAnyway` if you want the scheduler to still schedule the pod but to give higher priority to nodes that might reduce the skew.
+<5> Specify `labelSelector` to find matching pods. 
+Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain.
++
+.Example configuration for Thanos Ruler
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: user-workload-monitoring-config
+  namespace: openshift-user-workload-monitoring
+data:
+  config.yaml: |
+    thanosRuler:
+      topologySpreadConstraints:
+      - maxSkew: 1
+        topologyKey: monitoring
+        whenUnsatisfiable: ScheduleAnyway
+        labelSelector:
+          matchLabels:
+            app.kubernetes.io/name: thanos-ruler
+----
+
+. Save the file to apply the changes automatically.
++
+[WARNING]
+====
+When you save changes to the `user-workload-monitoring-config` config map, the pods and other resources in the `openshift-user-workload-monitoring` project might be redeployed.
+The running monitoring processes in that project might also restart.
+====