OBSDOCS-2495 - CMO TLS/configMap updates cause Prometheus restarts

modules/monitoring-default-monitoring-components.adoc

@@ -51,9 +51,3 @@ You can use {cmo-full} config map settings to manage monitoring-plugin resources
 |===
 
 The monitoring stack monitors all components within the stack. The components are automatically updated when {product-title} is updated.
-
-[NOTE]
-====
-All components of the monitoring stack use the TLS security profile settings that are centrally configured by a cluster administrator.
-If you configure a monitoring stack component that uses TLS security settings, the component uses the TLS security profile settings that already exist in the `tlsSecurityProfile` field in the global {product-title} `apiservers.config.openshift.io/cluster` resource.
-====

modules/monitoring-tls-security-and-rotation.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assembly:
+//
+// * observability/monitoring/monitoring-stack-architecture.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="tls-security-and-rotation_{context}"]
+= TLS security and rotation in the monitoring stack
+
+[role="_abstract"]
+Learn how TLS profiles and certificate rotation work in the {product-title} monitoring stack to keep communication secure.
+
+TLS security profiles for monitoring components::
+All components of the monitoring stack use the TLS security profile settings that are centrally configured by a cluster administrator.
+The monitoring stack component uses the TLS security profile settings that already exist in the `tlsSecurityProfile` field in the global {product-title} `apiservers.config.openshift.io/cluster` resource.
+
+TLS certificate rotation and automatic restarts::
+The {cmo-full} manages the internal TLS certificate lifecycle for the monitoring components. These certificates secure the internal communication between the monitoring components.
++
+During certificate rotation, the {cmo-short} updates secrets and config maps, which triggers automatic restarts of affected pods. This is an expected behavior, and the pods recover automatically.
++
+The following example shows events that occur during certificate rotation:
++
+[source,terminal]
+----
+$ oc get events -n openshift-monitoring
+
+LAST SEEN   TYPE      REASON              OBJECT                                   MESSAGE
+2h39m       Normal    SecretUpdated       deployment/cluster-monitoring-operator   Updated Secret/grpc-tls -n openshift-monitoring because it changed
+2h39m       Normal    SecretCreated       deployment/cluster-monitoring-operator   Created Secret/prometheus-user-workload-grpc-tls -n openshift-user-workload-monitoring because it was missing
+2h39m       Normal    SecretCreated       deployment/cluster-monitoring-operator   Created Secret/thanos-querier-grpc-tls -n openshift-monitoring because it was missing
+2h39m       Normal    SecretCreated       deployment/cluster-monitoring-operator   Created Secret/thanos-ruler-grpc-tls -n openshift-user-workload-monitoring because it was missing
+2h39m       Normal    SecretCreated       deployment/cluster-monitoring-operator   Created Secret/prometheus-k8s-grpc-tls -n openshift-monitoring because it was missing
+2h38m       Warning   FailedMount         pod/prometheus-k8s-0                     MountVolume.SetUp failed for volume "secret-grpc-tls" : secret "prometheus-k8s-grpc-tls" not found
+2h39m       Normal    Created             pod/prometheus-k8s-0                     Created container kube-rbac-proxy-thanos
+2h39m       Normal    Started             pod/prometheus-k8s-0                     Started container kube-rbac-proxy-thanos
+2h39m       Normal    SuccessfulDelete    statefulset/prometheus-k8s               delete Pod prometheus-k8s-0 in StatefulSet prometheus-k8s successful
+2h39m       Normal    SuccessfulCreate    statefulset/prometheus-k8s               create Pod prometheus-k8s-0 in StatefulSet prometheus-k8s successful
+----

observability/monitoring/about-ocp-monitoring/monitoring-stack-architecture.adoc

@@ -46,6 +46,15 @@ ifdef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 * xref:../../../observability/monitoring/configuring-user-workload-monitoring/configuring-performance-and-scalability-uwm.adoc#configuring-performance-and-scalability-uwm[Configuring performance and scalability]
 endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 
+//TLS security and rotation in the monitoring stack
+include::modules/monitoring-tls-security-and-rotation.adoc[leveloffset=+1]
+
+ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../security/tls-security-profiles.adoc#tls-security-profiles[Configuring TLS security profiles]
+endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
+
 //Glossary of common terms for OCP monitoring
 include::modules/monitoring-common-terms.adoc[leveloffset=+1]
 
@@ -55,5 +64,4 @@ ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 == Additional resources
 * xref:../../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring]
 * xref:../../../observability/monitoring/configuring-user-workload-monitoring/preparing-to-configure-the-monitoring-stack-uwm.adoc#granting-users-permission-to-monitor-user-defined-projects_preparing-to-configure-the-monitoring-stack-uwm[Granting users permissions for monitoring for user-defined projects]
-* xref:../../../security/tls-security-profiles.adoc#tls-security-profiles[Configuring TLS security profiles]
 endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]