RHDEVDOCS-3667 - Improve tlsConfig monitoring docs

Author: bburt-rh

modules/monitoring-specifying-how-a-service-is-monitored.adoc

@@ -6,20 +6,21 @@
 [id="specifying-how-a-service-is-monitored_{context}"]
 = Specifying how a service is monitored
 
+[role="_abstract"]
 To use the metrics exposed by your service, you must configure {product-title} monitoring to scrape metrics from the `/metrics` endpoint. You can do this using a `ServiceMonitor` custom resource definition (CRD) that specifies how a service should be monitored, or a `PodMonitor` CRD that specifies how a pod should be monitored. The former requires a `Service` object, while the latter does not, allowing Prometheus to directly scrape metrics from the metrics endpoint exposed by a pod.
 
-[NOTE]
-====
-In {product-title} {product-version}, you can use the `tlsConfig` property for a `ServiceMonitor` resource to specify the TLS configuration to use when scraping metrics from an endpoint. The `tlsConfig` property is not yet available for `PodMonitor` resources. If you need to use a TLS configuration when scraping metrics, you must use `ServiceMonitor` resource.
-====
-
 This procedure shows you how to create a `ServiceMonitor` resource for a service in a user-defined project.
 
 .Prerequisites
 
 * You have access to the cluster as a user with the `cluster-admin` role or the `monitoring-edit` role.
 * You have enabled monitoring for user-defined projects.
 * For this example, you have deployed the `prometheus-example-app` sample service in the `ns1` project.
++
+[NOTE]
+====
+The `prometheus-example-app` sample service does not support TLS authentication.
+====
 
 .Procedure
 
@@ -75,7 +76,3 @@ $ oc -n ns1 get servicemonitor
 NAME                         AGE
 prometheus-example-monitor   81m
 ----
-
-.Additional resources
-
-* See the link:https://github.com/openshift/prometheus-operator/blob/release-4.5/Documentation/api.md[Prometheus Operator API documentation] for more information on `ServiceMonitor` and `PodMonitor` resources.

modules/monitoring-understanding-metrics.adoc

@@ -6,11 +6,12 @@
 [id="understanding-metrics_{context}"]
 = Understanding metrics
 
-In {product-title} {product-version}, cluster components are monitored by scraping metrics exposed through service endpoints. You can also configure metrics collection for user-defined projects. Metrics enable you to monitor how cluster components and your own workloads are performing.
+[role="_abstract"]
+In {product-title} {product-version}, cluster components are monitored by scraping metrics exposed through service endpoints. You can also configure metrics collection for user-defined projects.
 
 You can define the metrics that you want to provide for your own workloads by using Prometheus client libraries at the application level.
 
-In {product-title}, metrics are exposed through an HTTP service endpoint under the `/metrics` canonical name. You can list all available metrics for a service by running a `curl` query against `\http://<endpoint>/metrics`. For instance, you can expose a route to the `prometheus-example-app` example application and then run the following to view all of its available metrics:
+In {product-title}, metrics are exposed through an HTTP service endpoint under the `/metrics` canonical name. You can list all available metrics for a service by running a `curl` query against `\http://<endpoint>/metrics`. For instance, you can expose a route to the `prometheus-example-app` example service and then run the following to view all of its available metrics:
 
 [source,terminal]
 ----

monitoring/managing-metrics.adoc

@@ -6,6 +6,9 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
+You can collect metrics to monitor how cluster components and your own workloads are performing.
+
 // Understanding metrics
 include::modules/monitoring-understanding-metrics.adoc[leveloffset=+1]
 
@@ -14,7 +17,12 @@ include::modules/monitoring-setting-up-metrics-collection-for-user-defined-proje
 include::modules/monitoring-deploying-a-sample-service.adoc[leveloffset=+2]
 include::modules/monitoring-specifying-how-a-service-is-monitored.adoc[leveloffset=+2]
 
+.Additional resources
+
 * xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects]
+* link:https://access.redhat.com/articles/6675491[How to scrape metrics using TLS in a ServiceMonitor configuration in a user-defined project]
+* xref:../rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc[PodMonitor API]
+* xref:../rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc[ServiceMonitor API]
 
 // Querying metrics
 include::modules/monitoring-querying-metrics.adoc[leveloffset=+1]