From 971728d104d76dde12351f384b31706351bdbeb0 Mon Sep 17 00:00:00 2001 From: Jake Berger Date: Fri, 26 Jun 2026 12:00:03 -0400 Subject: [PATCH 1/2] CQA for Observability --- _topic_maps/_topic_map_osd.yml | 2 -- _topic_maps/_topic_map_rosa.yml | 2 -- ...-user-defined-project-from-monitoring.adoc | 4 +-- .../monitoring-for-user-defined-projects.adoc | 19 +++++++++++ .../monitoring-support-considerations.adoc | 2 +- ...pport-policy-for-monitoring-operators.adoc | 6 ++-- ...sion-matrix-for-monitoring-components.adoc | 4 +-- ...-monitoring-for-user-defined-projects.adoc | 6 ++-- .../sd-monitoring-troubleshooting-issues.adoc | 4 +-- ...aintenance-and-support-for-monitoring.adoc | 2 +- ...-monitoring-for-user-defined-projects.adoc | 19 ----------- ...-monitoring-for-user-defined-projects.adoc | 12 +++++-- .../troubleshooting-monitoring-issues.adoc | 33 +++++++------------ 13 files changed, 55 insertions(+), 60 deletions(-) create mode 100644 modules/monitoring-for-user-defined-projects.adoc delete mode 100644 observability/monitoring/getting-started/sd-accessing-monitoring-for-user-defined-projects.adoc diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml index 2e43aa0740f7..c08bcf3b25ec 100644 --- a/_topic_maps/_topic_map_osd.yml +++ b/_topic_maps/_topic_map_osd.yml @@ -1140,8 +1140,6 @@ Topics: Topics: - Name: Maintenance and support for monitoring File: maintenance-and-support-for-monitoring - - Name: Accessing monitoring for user-defined projects - File: sd-accessing-monitoring-for-user-defined-projects - Name: Disabling monitoring for user-defined projects File: sd-disabling-monitoring-for-user-defined-projects - Name: Configuring user workload monitoring diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml index 20e6912a7d29..4d119bac1f89 100644 --- a/_topic_maps/_topic_map_rosa.yml +++ b/_topic_maps/_topic_map_rosa.yml @@ -1465,8 +1465,6 @@ Topics: Topics: - Name: Maintenance and support for monitoring File: maintenance-and-support-for-monitoring - - Name: Accessing monitoring for user-defined projects - File: sd-accessing-monitoring-for-user-defined-projects - Name: Disabling monitoring for user-defined projects File: sd-disabling-monitoring-for-user-defined-projects - Name: Configuring user workload monitoring diff --git a/modules/monitoring-excluding-a-user-defined-project-from-monitoring.adoc b/modules/monitoring-excluding-a-user-defined-project-from-monitoring.adoc index 24d954db9fd4..3dfdb855cc2c 100644 --- a/modules/monitoring-excluding-a-user-defined-project-from-monitoring.adoc +++ b/modules/monitoring-excluding-a-user-defined-project-from-monitoring.adoc @@ -5,10 +5,10 @@ :_mod-docs-content-type: PROCEDURE [id="excluding-a-user-defined-project-from-monitoring_{context}"] -= Excluding a user-defined project from monitoring += Exclude a user-defined project from monitoring [role="_abstract"] -Individual user-defined projects can be excluded from user workload monitoring. To do so, add the `openshift.io/user-monitoring` label to the project's namespace with a value of `false`. +You can exclude individual user-defined projects from monitoring to reduce resource consumption or when projects use custom monitoring solutions. Exclusion is controlled by applying a label to the project namespace. .Procedure diff --git a/modules/monitoring-for-user-defined-projects.adoc b/modules/monitoring-for-user-defined-projects.adoc new file mode 100644 index 000000000000..df21d74bd449 --- /dev/null +++ b/modules/monitoring-for-user-defined-projects.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * observability/monitoring/getting-started/sd-disabling-monitoring-for-user-defined-projects.adoc + +:_mod-docs-content-type: CONCEPT +[id="monitoring-for-user-defined-projects_{context}"] += Monitoring for user-defined projects + +[role="_abstract"] +You can monitor your own {product-title} projects without requiring an additional monitoring solution. {product-title} enables this capability by default when you install a cluster, allowing you to track metrics and performance for your custom workloads. + +The `dedicated-admin` user has default permissions to configure and access monitoring for user-defined projects. + +Optionally, you can disable monitoring for user-defined projects during or after a cluster installation. + +[NOTE] +==== +Custom Prometheus instances and the Prometheus Operator installed through Operator Lifecycle Manager (OLM) can cause issues with user-defined project monitoring if it is enabled. Custom Prometheus instances are not supported. +==== diff --git a/modules/monitoring-support-considerations.adoc b/modules/monitoring-support-considerations.adoc index 7f19bc43e7ba..07f1238cc270 100644 --- a/modules/monitoring-support-considerations.adoc +++ b/modules/monitoring-support-considerations.adoc @@ -7,7 +7,7 @@ = Support considerations for monitoring [role="_abstract"] -The {product-title} monitoring has configuration limitations. Understanding them is essential for avoiding automated configuration resets. +You can avoid automated configuration resets by understanding and adhering to the supported configuration options for the {product-title} monitoring stack. Unsupported modifications are automatically reverted. [NOTE] ==== diff --git a/modules/monitoring-support-policy-for-monitoring-operators.adoc b/modules/monitoring-support-policy-for-monitoring-operators.adoc index a0df411c4b46..5ae4a4d4f630 100644 --- a/modules/monitoring-support-policy-for-monitoring-operators.adoc +++ b/modules/monitoring-support-policy-for-monitoring-operators.adoc @@ -7,11 +7,11 @@ = Support policy for monitoring Operators [role="_abstract"] -Monitoring Operators ensure that {product-title} monitoring resources function as designed and tested. If Cluster Version Operator (CVO) control of an Operator is overridden, the Operator does not respond to configuration changes, reconcile the intended state of cluster objects, or receive updates. +You must not override Cluster Version Operator (CVO) control of monitoring Operators. Overriding CVO control prevents Operators from responding to configuration changes, reconciling cluster state, and receiving updates, placing your cluster in an unsupported state. -While overriding CVO control for an Operator can be helpful during debugging, this is unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades. +== Overriding the Cluster Version Operator -*Overriding the Cluster Version Operator* +While overriding CVO control for an Operator can be helpful during debugging, this is unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades. The `spec.overrides` parameter can be added to the configuration for the CVO to allow administrators to provide a list of overrides to the behavior of the CVO for a component. Setting the `spec.overrides[].unmanaged` parameter to `true` for a component blocks cluster upgrades and alerts the administrator after a CVO override has been set: diff --git a/modules/monitoring-support-version-matrix-for-monitoring-components.adoc b/modules/monitoring-support-version-matrix-for-monitoring-components.adoc index 560fc47437d4..1a0c3f6dbef6 100644 --- a/modules/monitoring-support-version-matrix-for-monitoring-components.adoc +++ b/modules/monitoring-support-version-matrix-for-monitoring-components.adoc @@ -7,7 +7,7 @@ = Support version matrix for monitoring components [role="_abstract"] -The following matrix contains information about versions of monitoring components for {product-title} 4.12 and later releases: +You can verify the supported versions of Prometheus, Alertmanager, and other monitoring components for each {product-title} release by consulting this version compatibility matrix for releases 4.12 and later. .{product-title} and component versions |=== @@ -34,5 +34,5 @@ The following matrix contains information about versions of monitoring component [NOTE] ==== -The openshift-state-metrics agent and Telemeter Client are OpenShift-specific components. Therefore, their versions correspond with the versions of {product-title}. +The openshift-state-metrics agent and Telemeter Client are {product-title}-specific components. Therefore, their versions correspond with the versions of {product-title}. ==== diff --git a/modules/sd-disabling-monitoring-for-user-defined-projects.adoc b/modules/sd-disabling-monitoring-for-user-defined-projects.adoc index 3e9b0d88b18e..8f6a83c8de1c 100644 --- a/modules/sd-disabling-monitoring-for-user-defined-projects.adoc +++ b/modules/sd-disabling-monitoring-for-user-defined-projects.adoc @@ -4,10 +4,10 @@ :_mod-docs-content-type: PROCEDURE [id="sd-disabling-monitoring-for-user-defined-projects_{context}"] -= Disabling monitoring for user-defined projects += Disable monitoring for user-defined projects [role="_abstract"] -By default, monitoring for user-defined projects is enabled. If you do not want to use the built-in monitoring stack to monitor user-defined projects, you can disable it. +You can disable the built-in monitoring for user-defined projects when you plan to use an external monitoring solution or need to reduce cluster resource consumption. .Prerequisites @@ -19,6 +19,6 @@ By default, monitoring for user-defined projects is enabled. If you do not want . Click the *Settings* tab. -. Click the *Enable user workload monitoring* checkbox to deselect the option, and then click *Save*. +. Click the *Enable user workload monitoring* checkbox to clear the option, and then click *Save*. + User workload monitoring is disabled. The Prometheus, Prometheus Operator, and Thanos Ruler components are stopped in the `openshift-user-workload-monitoring` project. diff --git a/modules/sd-monitoring-troubleshooting-issues.adoc b/modules/sd-monitoring-troubleshooting-issues.adoc index 996c28acdf4b..afccef4d811d 100644 --- a/modules/sd-monitoring-troubleshooting-issues.adoc +++ b/modules/sd-monitoring-troubleshooting-issues.adoc @@ -8,7 +8,7 @@ = Determining why user-defined project metrics are unavailable [role="_abstract"] -If metrics are not displaying when monitoring user-defined projects, follow these steps to troubleshoot the issue. +You can determine why user-defined project metrics are unavailable by checking metric endpoints, verifying monitor configurations, and validating service-to-pod label matching. .Procedure @@ -47,7 +47,7 @@ version{version="v0.1.0"} 1 + An invalid output indicates that there is a problem with the corresponding application. -. If you are using a `PodMonitor` CRD, verify that the `PodMonitor` CRD is configured to point to the correct pods using label matching. For more information, see the Prometheus Operator documentation. +. If you are using a `PodMonitor` CRD, verify that the `PodMonitor` CRD is configured to point to the correct pods using label matching. . If you are using a `ServiceMonitor` CRD, and if the `/metrics` endpoint of the pod is showing metric data, follow these steps to verify the configuration: .. Verify that the service is pointed to the correct `/metrics` endpoint. The service `labels` in this output must match the services monitor `labels` and the `/metrics` endpoint defined by the service in the subsequent steps. + diff --git a/observability/monitoring/getting-started/maintenance-and-support-for-monitoring.adoc b/observability/monitoring/getting-started/maintenance-and-support-for-monitoring.adoc index a1bed63f742e..108bebcb180a 100644 --- a/observability/monitoring/getting-started/maintenance-and-support-for-monitoring.adoc +++ b/observability/monitoring/getting-started/maintenance-and-support-for-monitoring.adoc @@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -Not all configuration options for the monitoring stack are exposed. To configure {product-title} monitoring, configure the {cmo-first} using the options described in the "Config map reference for the {cmo-full}" linked in the _Additional resources_ section. *Do not use other configurations, as they are unsupported.* +You can configure {product-title} monitoring by using supported configuration options in the {cmo-full}. Using only supported options ensures your monitoring configuration persists across cluster upgrades and Prometheus version changes. Configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use unsupported configurations, your changes will disappear because the {cmo-short} automatically reconciles any differences and resets any unsupported changes back to the originally defined state by default and by design. diff --git a/observability/monitoring/getting-started/sd-accessing-monitoring-for-user-defined-projects.adoc b/observability/monitoring/getting-started/sd-accessing-monitoring-for-user-defined-projects.adoc deleted file mode 100644 index c050c5c71fcb..000000000000 --- a/observability/monitoring/getting-started/sd-accessing-monitoring-for-user-defined-projects.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-openshift-dedicated.adoc[] -[id="sd-accessing-monitoring-for-user-defined-projects"] -= Accessing monitoring for user-defined projects -:context: sd-accessing-monitoring-for-user-defined-projects - -toc::[] - -[role="_abstract"] -When you install a {product-title} cluster, monitoring for user-defined projects is enabled by default. With monitoring for user-defined projects enabled, you can monitor your own {product-title} projects without the need for an additional monitoring solution. - -The `dedicated-admin` user has default permissions to configure and access monitoring for user-defined projects. - -[NOTE] -==== -Custom Prometheus instances and the Prometheus Operator installed through Operator Lifecycle Manager (OLM) can cause issues with user-defined project monitoring if it is enabled. Custom Prometheus instances are not supported. -==== - -Optionally, you can disable monitoring for user-defined projects during or after a cluster installation. diff --git a/observability/monitoring/getting-started/sd-disabling-monitoring-for-user-defined-projects.adoc b/observability/monitoring/getting-started/sd-disabling-monitoring-for-user-defined-projects.adoc index 4a8499a1bdf9..b74893ff6db3 100644 --- a/observability/monitoring/getting-started/sd-disabling-monitoring-for-user-defined-projects.adoc +++ b/observability/monitoring/getting-started/sd-disabling-monitoring-for-user-defined-projects.adoc @@ -1,16 +1,24 @@ :_mod-docs-content-type: ASSEMBLY include::_attributes/attributes-openshift-dedicated.adoc[] [id="sd-disabling-monitoring-for-user-defined-projects"] -= Disabling monitoring for user-defined projects += Disable monitoring for user-defined projects :context: sd-disabling-monitoring-for-user-defined-projects toc::[] [role="_abstract"] -As a `dedicated-admin`, you can disable monitoring for user-defined projects. You can also exclude individual projects from user workload monitoring. +You can disable monitoring for user-defined projects to reduce resource consumption or exclude specific projects when they have custom monitoring solutions. This provides flexibility in managing cluster monitoring resources for your workloads. + +// Monitoring for user-defined projects +include::modules/monitoring-for-user-defined-projects.adoc[leveloffset=+1] // Disabling monitoring for user-defined projects include::modules/sd-disabling-monitoring-for-user-defined-projects.adoc[leveloffset=+1] // Excluding a user-defined project from monitoring include::modules/monitoring-excluding-a-user-defined-project-from-monitoring.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources +* xref:../../../observability/monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc#cluster-monitoring-operator-configuration-reference[Config map reference for the Cluster Monitoring Operator] diff --git a/observability/monitoring/troubleshooting-monitoring-issues.adoc b/observability/monitoring/troubleshooting-monitoring-issues.adoc index f73a8b295706..5bd661aaed84 100644 --- a/observability/monitoring/troubleshooting-monitoring-issues.adoc +++ b/observability/monitoring/troubleshooting-monitoring-issues.adoc @@ -6,23 +6,12 @@ include::_attributes/common-attributes.adoc[] toc::[] -ifndef::openshift-dedicated,openshift-rosa[] -Find troubleshooting steps for common issues with core platform and user-defined project monitoring. -endif::openshift-dedicated,openshift-rosa[] -ifdef::openshift-dedicated,openshift-rosa[] -Find troubleshooting steps for common issues with user-defined project monitoring. -endif::openshift-dedicated,openshift-rosa[] +[role="_abstract"] +You can troubleshoot common monitoring issues by using the procedures in this assembly. These procedures help you resolve problems with metrics collection, Prometheus storage, and alert configuration for both platform and user-defined project monitoring. // Investigating why user-defined project metrics are unavailable (OCP/ROSA HCP) ifndef::openshift-dedicated,openshift-rosa[] include::modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc[leveloffset=+1] - -[role="_additional-resources"] -.Additional resources - -* xref:../../observability/monitoring/configuring-user-workload-monitoring/preparing-to-configure-the-monitoring-stack-uwm.adoc#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects] -* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-metrics-uwm.adoc#specifying-how-a-service-is-monitored_configuring-metrics-uwm[Specifying how a service is monitored] -* xref:../../observability/monitoring/accessing-metrics/accessing-metrics-as-an-administrator.adoc#getting-detailed-information-about-a-target_accessing-metrics-as-an-administrator[Getting detailed information about a metrics target] endif::openshift-dedicated,openshift-rosa[] // Investigating why user-defined project metrics are unavailable (OSD/ROSA Classic) @@ -33,22 +22,24 @@ endif::openshift-dedicated,openshift-rosa[] // Determining why Prometheus is consuming a lot of disk space include::modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources - -* xref:../../observability/monitoring/accessing-metrics/accessing-monitoring-apis-by-using-the-cli.adoc#accessing-monitoring-apis-by-using-the-cli[Accessing monitoring APIs by using the CLI] -* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-performance-and-scalability-uwm.adoc#setting-scrape-and-evaluation-intervals-limits-for-user-defined-projects_configuring-performance-and-scalability-uwm[Setting scrape intervals, evaluation intervals, and enforced limits for user-defined projects] -* xref:../../support/getting-support.adoc#support-submitting-a-case_getting-support[Submitting a support case] - // Resolving the KubePersistentVolumeFillingUp alert firing for Prometheus include::modules/monitoring-resolving-the-kubepersistentvolumefillingup-alert-firing-for-prometheus.adoc[leveloffset=+1] ifndef::openshift-dedicated,openshift-rosa[] // Resolving the AlertmanagerReceiversNotConfigured alert firing for Prometheus include::modules/monitoring-resolving-the-alertmanagerreceiversnotconfigured-alert.adoc[leveloffset=+1] +endif::openshift-dedicated,openshift-rosa[] [role="_additional-resources"] -.Additional resources +[id="additional-resources_{context}"] +== Additional resources +* xref:../../observability/monitoring/configuring-user-workload-monitoring/preparing-to-configure-the-monitoring-stack-uwm.adoc#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects] +* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-metrics-uwm.adoc#specifying-how-a-service-is-monitored_configuring-metrics-uwm[Specifying how a service is monitored] +* xref:../../observability/monitoring/accessing-metrics/accessing-metrics-as-an-administrator.adoc#getting-detailed-information-about-a-target_accessing-metrics-as-an-administrator[Getting detailed information about a metrics target] +* xref:../../observability/monitoring/accessing-metrics/accessing-monitoring-apis-by-using-the-cli.adoc#accessing-monitoring-apis-by-using-the-cli[Accessing monitoring APIs by using the CLI] +* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-performance-and-scalability-uwm.adoc#setting-scrape-and-evaluation-intervals-limits-for-user-defined-projects_configuring-performance-and-scalability-uwm[Setting scrape intervals, evaluation intervals, and enforced limits for user-defined projects] +* xref:../../support/getting-support.adoc#support-submitting-a-case_getting-support[Submitting a support case] +ifndef::openshift-dedicated,openshift-rosa[] * xref:../../observability/monitoring/configuring-core-platform-monitoring/configuring-alerts-and-notifications.adoc#configuring-alert-notifications_configuring-alerts-and-notifications[Configuring alert notifications for default platform monitoring] * xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-alerts-and-notifications-uwm.adoc#configuring-alert-notifications_configuring-alerts-and-notifications-uwm[Configuring alert notifications for user workload monitoring] endif::openshift-dedicated,openshift-rosa[] From f49465fcf5ca33debc92076cf426bfcd0cac735b Mon Sep 17 00:00:00 2001 From: Jake Berger Date: Fri, 26 Jun 2026 15:28:13 -0400 Subject: [PATCH 2/2] fix build errors --- observability/monitoring/troubleshooting-monitoring-issues.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/observability/monitoring/troubleshooting-monitoring-issues.adoc b/observability/monitoring/troubleshooting-monitoring-issues.adoc index 5bd661aaed84..f3802d81428f 100644 --- a/observability/monitoring/troubleshooting-monitoring-issues.adoc +++ b/observability/monitoring/troubleshooting-monitoring-issues.adoc @@ -33,7 +33,9 @@ endif::openshift-dedicated,openshift-rosa[] [role="_additional-resources"] [id="additional-resources_{context}"] == Additional resources +ifndef::openshift-dedicated,openshift-rosa[] * xref:../../observability/monitoring/configuring-user-workload-monitoring/preparing-to-configure-the-monitoring-stack-uwm.adoc#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects] +endif::openshift-dedicated,openshift-rosa[] * xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-metrics-uwm.adoc#specifying-how-a-service-is-monitored_configuring-metrics-uwm[Specifying how a service is monitored] * xref:../../observability/monitoring/accessing-metrics/accessing-metrics-as-an-administrator.adoc#getting-detailed-information-about-a-target_accessing-metrics-as-an-administrator[Getting detailed information about a metrics target] * xref:../../observability/monitoring/accessing-metrics/accessing-monitoring-apis-by-using-the-cli.adoc#accessing-monitoring-apis-by-using-the-cli[Accessing monitoring APIs by using the CLI]