[OSDOCS-19702]: HCP control plane metrics overview

hosted_control_planes/hcp-observability.adoc

@@ -9,10 +9,31 @@ toc::[]
 [role="_abstract"]
 You can gather metrics for {hcp} by configuring metrics sets. Monitoring dashboards are created in the management cluster for each hosted cluster that it manages.
 
+// Metrics sets
 include::modules/hosted-control-planes-metrics-sets.adoc[leveloffset=+1]
 
 include::modules/hosted-control-planes-monitoring-dashboard.adoc[leveloffset=+1]
 
+// Monitoring CP metrics from the hosted cluster
+include::modules/hcp-cp-metrics-overview.adoc[leveloffset=+1]
+
+// include::modules/hcp-cp-metrics-enable.adoc[leveloffset=+2]
+
+// include::modules/hcp-query-cp-metrics.adoc[leveloffset=+1]
+
+// [role="_additional-resources"]
+// .Additional resources
+
+// * xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-metrics[Exposed metrics]
+
+// include::modules/hcp-query-cp-metrics-console.adoc[leveloffset=+1]
+
+// [role="_additional-resources"]
+// .Additional resources
+
+// * xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-metrics[Exposed metrics]
+
+//Connectivity metrics
 include::modules/hcp-connectivity-metrics.adoc[leveloffset=+1]
 
 include::modules/hcp-connect-data-plane.adoc[leveloffset=+2]

modules/hcp-cp-metrics-overview.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-observability.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="hcp-cp-metrics-overview_{context}"]
+= Control plane metrics for {hcp}
+
+[role="_abstract"]
+You can observe hosted control plane health from the hosted cluster monitoring stack when metrics forwarding is enabled.
+
+With propagated metrics, you can diagnose API server, etcd, Operator, and scheduling issues from the hosted cluster web console and CLI without management cluster credentials.
+
+This capability is available in {product-title} 4.22 and later.
+
+Before {product-title} 4.22, control plane components for {hcp} ran on the management cluster and were invisible to the Cluster Monitoring Operator stack in the hosted cluster. Hosted cluster administrators could not query metrics such as `apiserver_request_total`, `etcd_mvcc_db_total_size_in_bytes`, or `csv_succeeded` from the hosted cluster Prometheus.
+
+With metrics forwarding, selected control plane metrics are propagated from the management cluster into the hosted cluster platform Prometheus.
+
+After you enable forwarding on the `HostedCluster` resource, you can use familiar PromQL queries, alerts, and dashboards.
+
+[#hcp-cp-metrics-architecture_{context}]
+== Metrics forwarding architecture
+
+When you enable metrics forwarding, {hcp} deploys components on both the management cluster and the hosted cluster.
+
+On the management cluster, in the hosted control plane namespace, the following steps take place:
+
+* The `endpoint-resolver` deployment discovers pod IP addresses for control plane components.
+* The `metrics-proxy` deployment scrapes control plane pods, applies per-component metric filters, injects {product-title}-compatible labels, and serves aggregated metrics at paths, such as `/metrics/kube-apiserver` and `/metrics/etcd`, behind a TLS-passthrough Route.
+
+On the hosted cluster, in the `openshift-monitoring` namespace, the following steps take place:
+
+* The `control-plane-metrics-forwarder` deployment runs HAProxy and TCP-proxies scrape requests to the management cluster `metrics-proxy` Route.
+* A `PodMonitor` named `control-plane-metrics-forwarder` configures platform Prometheus to scrape the forwarder using mutual TLS (mTLS).
+
+The data path is as follows:
+
+. Platform Prometheus in the hosted cluster discovers the `PodMonitor` and scrapes the metrics-forwarder.
+. The metrics-forwarder forwards the scrape over mTLS to the management cluster `metrics-proxy` Route.
+. The metrics-proxy scrapes control plane pods through the endpoint-resolver and returns filtered, relabeled metrics.