docs(monitoring): style pass on fleet monitoring phase 1 docs

djwfyi · djwfyi · commit f6708f8efc24 · 2026-07-09T18:29:26.000-04:00
Fix missing .mdx suffixes on relative links, remaining virtual/host
cluster terminology, contractions, Flow step verbs, run-on sentences,
and the vClusters trademark plural in a dashboard panel table.
diff --git a/platform/maintenance/monitoring/central-hostpath-mapper.mdx b/platform/maintenance/monitoring/central-hostpath-mapper.mdx
@@ -17,9 +17,9 @@ import FeatureTable from '@site/src/components/FeatureTable';
 
 You can install a common logging solution such as Fluentd or the ELK stack on the Control Plane Cluster and use it within the tenant cluster. However, in some scenarios, installing these tools directly on the tenant cluster is preferred.
 
-These logging solutions access pod and container logs by mounting node host paths and using specific filename formats to associate logs with the correct pods. This approach doesn’t work in a vCluster because the vCluster rewrites pod names to a vCluster-specific format when syncing them to the Control Plane Cluster.
+These logging solutions access pod and container logs by mounting node host paths and using specific filename formats to associate logs with the correct pods. This approach doesn't work in a tenant cluster because vCluster rewrites pod names to a vCluster-specific format when syncing them to the Control Plane Cluster.
 
-The HostPath Mapper collects logs from tenant clusters. It works by matching virtual pod and container names to their physical names on the host and does this through symbolic links.
+The HostPath Mapper collects logs from tenant clusters. It works by matching virtual pod and container names to their physical names on the host through symbolic links.
 
 To enable HostPath Mapper for a tenant cluster, install a DaemonSet in the same namespace. This setup works well for small environments with few nodes and tenant clusters.
 
@@ -32,7 +32,7 @@ To use this feature, install the Central HostPath Mapper on the Control Plane Cl
 :::
 
 :::warning Templates
-This feature is only configurable from the UI for tenant clusters created without a template. When using a custom template that has the feature enabled, the UI does not display the configuration in **Advanced Options** as described below. In this case, configure the feature using the CLI or by modifying the manifests.
+This feature is only configurable from the UI for tenant clusters created without a template. When using a custom template that has the feature enabled, the UI doesn't display the configuration in **Advanced Options** as described below. In this case, configure the feature using the CLI or by modifying the manifests.
 :::
 
 <Tabs
@@ -45,28 +45,28 @@ This feature is only configurable from the UI for tenant clusters created withou
   <TabItem value="creation">
     <Flow id="enable-central-hpm-virtualcluster-creation">
       <Step>
-        From the project drop-down menu, select the project you'd like to create
-        the tenant cluster in.
+        From the project drop-down menu, click the project where you want to
+        create the tenant cluster.
       </Step>
       <Step>
-        Click the <Button>New Tenant Cluster</Button> button above the list of tenant clusters
+        Click the <Button>New Tenant Cluster</Button> button above the list of tenant clusters.
       </Step>
       <Step>
-        <b>[Optional]</b> select the cluster in which to create the tenant
+        <b>[Optional]</b> Click the cluster where you want to create the tenant
         cluster.
       </Step>
       <Step>
         Leave the <Label>Select a template</Label> section blank and click the <Button>Configure</Button> to continue.
       </Step>
       <Step>
         Click the <Label>Advanced Options</Label> configuration tab and expand
-        the 'Host Path Mapper' section.
+        the **Host Path Mapper** section.
       </Step>
       <Step>
-        Toggle the slider <Label>Enable</Label>. This will add the
-        'loft.sh/hpm-enabled' annotation to the template metadata which will be
-        automatically synced to the tenant cluster on creation. Secondly, it
-        will add `enabled: true` & `central: true` under the '[controlPlane.hostPathMapper](/docs/vcluster/configure/vcluster-yaml/control-plane/components/host-path-mapper)' field in the vcluster.yaml.
+        Toggle the slider <Label>Enable</Label>. This adds the
+        `loft.sh/hpm-enabled` annotation to the template metadata, which syncs
+        automatically to the tenant cluster on creation. It also sets
+        `enabled: true` and `central: true` under the [controlPlane.hostPathMapper](/docs/vcluster/configure/vcluster-yaml/control-plane/components/host-path-mapper) field in the vcluster.yaml.
       </Step>
       <Step>
         Finish configuring anything else on your tenant cluster,
@@ -78,21 +78,22 @@ This feature is only configurable from the UI for tenant clusters created withou
   <TabItem value="existing">
     <Flow id="enable-central-hpm-virtualcluster-existing">
       <Step>
-        Select the project that contains the tenant cluster you want to enable Central HostPath Mapper on from the project drop-down menu.
+        From the project drop-down menu, click the project that contains the
+        tenant cluster where you want to enable Central HostPath Mapper.
       </Step>
       <Step>
-        Hover over the tenant cluster you would like to enable Central HostPath Mapper on to see an <Label>Edit</Label> button displayed.
+        Hover over the tenant cluster where you want to enable Central HostPath Mapper to reveal the <Label>Edit</Label> button.
         Click <Label>Edit</Label>.
       </Step>
       <Step>
         Click the <Label>Advanced Options</Label> configuration tab and expand
         the **Host Path Mapper** section.
       </Step>
       <Step>
-        Toggle the slider <Label>Enable</Label>. This will add the
-        'loft.sh/hpm-enabled' annotation to the template metadata which will be
-        automatically synced to the tenant cluster on creation. Secondly, it
-        will add `enabled: true` & `central: true` under the '[controlPlane.hostPathMapper](/docs/vcluster/configure/vcluster-yaml/control-plane/components/host-path-mapper)' field in the vcluster.yaml.
+        Toggle the slider <Label>Enable</Label>. This adds the
+        `loft.sh/hpm-enabled` annotation to the template metadata, which syncs
+        automatically to the tenant cluster on creation. It also sets
+        `enabled: true` and `central: true` under the [controlPlane.hostPathMapper](/docs/vcluster/configure/vcluster-yaml/control-plane/components/host-path-mapper) field in the vcluster.yaml.
       </Step>
       <Step>
         Finish configuring anything else on your tenant cluster,
diff --git a/platform/maintenance/monitoring/fleet-monitoring-otel.mdx b/platform/maintenance/monitoring/fleet-monitoring-otel.mdx
@@ -122,7 +122,7 @@ The architecture comprises the following:
 - Collector architecture:
   - A central Prometheus with the remote write receiver enabled.
   - One OTel Collector Deployment with Target Allocator per Control Plane Cluster (scrapes shared-nodes tenant clusters and their control planes using ServiceMonitors).
-  - One OTel Collector DaemonSet per private-nodes vCluster (scrapes local kubelet, cAdvisor, and API server metrics from inside the vCluster).
+  - One OTel Collector DaemonSet per private-nodes tenant cluster (scrapes local kubelet, cAdvisor, and API server metrics from inside the tenant cluster).
 
 ## How it works
 
@@ -170,7 +170,7 @@ which also prevents duplicate series with any existing Prometheus scrapes.
 
 ### Private nodes
 
-The private-nodes collector runs inside each vCluster as a DaemonSet with one
+The private-nodes collector runs inside each tenant cluster as a DaemonSet with one
 pod per node. Each pod scrapes only its local node's kubelet `/metrics`,
 cAdvisor `/metrics/cadvisor`, and API server `/metrics` endpoints.
 
@@ -188,14 +188,14 @@ prometheus receiver (kubelet, cAdvisor, API server)
                             pod → vcluster_virtual_pod)
 ```
 
-Since the collector runs inside the vCluster, it can't access host-cluster
-namespace labels. Instead, the Platform injects `{{ .Values.loft.* }}` template
+Since the collector runs inside the tenant cluster, it can't access Control
+Plane Cluster namespace labels. Instead, the Platform injects `{{ .Values.loft.* }}` template
 variables at deploy time, which are set as `external_labels` on the
-`prometheusremotewrite` exporter. These are static per-vCluster values applied
+`prometheusremotewrite` exporter. These are static per-tenant-cluster values applied
 to all exported metrics.
 
 The `metric_relabel_configs` copy `namespace` to `vcluster_virtual_namespace`
-and `pod` to `vcluster_virtual_pod`. Inside a private-nodes vCluster, the
+and `pod` to `vcluster_virtual_pod`. Inside a private-nodes tenant cluster, the
 `namespace` and `pod` labels already represent virtual names, so this copy
 ensures dashboard compatibility with the shared-nodes collector.
 
@@ -219,7 +219,7 @@ All metrics from both apps carry a consistent set of identity labels:
 `vcluster_virtual_namespace` and `vcluster_virtual_pod` are missing on some
 metrics. These are vCluster system pods (syncer, CoreDNS) that don't have the
 syncer labels and annotations because they aren't user workloads synced from
-inside the vCluster.
+inside the tenant cluster.
 :::
 
 ## Prerequisites
@@ -248,7 +248,7 @@ server:
 
 - kubelet scraping disabled in any existing kube-prometheus-stack to avoid
   duplicate cAdvisor series (`kubelet.enabled: false`).
-- Platform namespace labels present (added automatically by the vCluster Platform).
+- Platform namespace labels present (added automatically by vCluster Platform).
 
 ### Private nodes prerequisites
 
@@ -593,7 +593,7 @@ spec:
 - **`serviceMonitorSelector: app: vcluster`**: Without filtering, the Target
   Allocator discovers all ServiceMonitors in the cluster, overwhelming
   collectors with memory pressure.
-- **`operator.targetallocator.mtls: true`**: Each vCluster exposes its API
+- **`operator.targetallocator.mtls: true`**: Each tenant cluster exposes its API
   server metrics over mTLS. Without this feature gate, the Target Allocator
   redacts TLS private keys when passing scrape configs to collectors.
 - **`otel/opentelemetry-collector-contrib` image**: The default image doesn't
@@ -614,7 +614,7 @@ kubectl apply -f otel-collector-shared-nodes-app.yaml
 <Flow id="deploy-otel-shared">
   <Step>
     Go to the <NavStep>Infra</NavStep> section using the menu on the left, and
-    select the <NavStep>Clusters</NavStep> view.
+    click the <NavStep>Clusters</NavStep> view.
   </Step>
   <Step>
     Click on the cluster where you want to deploy the collector.
@@ -623,7 +623,7 @@ kubectl apply -f otel-collector-shared-nodes-app.yaml
     Navigate to the <NavStep>Apps</NavStep> tab.
   </Step>
   <Step>
-    Click <Button>Deploy App</Button> and select the
+    Click <Button>Deploy App</Button> and click the
     **OTEL Collector - Shared Nodes** app.
   </Step>
   <Step>
@@ -646,7 +646,7 @@ Repeat these steps for each Control Plane Cluster.
 ## Deploy the private nodes collector
 <!-- vale on -->
 
-Deploy one private-nodes collector into each private-nodes vCluster. All
+Deploy one private-nodes collector into each private-nodes tenant cluster. All
 vCluster identity labels are injected automatically by the Platform using
 `{{ .Values.loft.* }}`.
 
@@ -890,7 +890,7 @@ spec:
   ensures one collector per node, scraping only the local kubelet and cAdvisor
   using `${env:K8S_NODE_NAME}` filtering. No Target Allocator is needed.
 - **`external_labels` instead of `k8sattributes` for identity**: The collector
-  runs inside the vCluster, so it can't access Control Plane Cluster namespace labels.
+  runs inside the tenant cluster, so it can't access Control Plane Cluster namespace labels.
   The Platform injects `{{ .Values.loft.* }}` template variables at deploy time.
 - **`resource_to_telemetry_conversion: false`**: Setting this to `true` causes
   duplicate labels that break Grafana dashboards.
@@ -917,7 +917,7 @@ kubectl apply -f otel-collector-private-nodes-app.yaml
     Go to the <NavStep>Projects</NavStep> section using the menu on the left.
   </Step>
   <Step>
-    Select the project containing your private-nodes tenant cluster.
+    Click the project containing your private-nodes tenant cluster.
   </Step>
   <Step>
     Click on the tenant cluster, then navigate to the <NavStep>Config</NavStep>
@@ -1216,7 +1216,8 @@ with the event rate.
 
 :::note
 This section assumes Grafana is already deployed. For setup instructions, see
-[Aggregating Metrics — Deploy Grafana](./aggregating-metrics.mdx#deploy-grafana).
+the [Deploy Grafana](./aggregating-metrics.mdx#deploy-grafana) section in
+Aggregating Metrics.
 :::
 
 Two Grafana dashboards are provided for visualizing metrics collected by the
@@ -1235,14 +1236,12 @@ time, so all panels use straightforward PromQL queries without joins.
 ### vCluster projects dashboard
 <!-- vale on -->
 
-A platform admin overview of vCluster projects across shared and private node
-tenant clusters. Use this dashboard to monitor resource consumption and API health at
-the project level.
+A platform admin overview of vCluster projects across Shared Nodes and Private
+Nodes tenant clusters. Use this dashboard to monitor resource consumption and
+API health at the project level.
 
 **Dashboard JSON file:** [Download dashboard JSON](/media/dashboards/vcluster-projects.json)
 
-
-
 **Template variables:**
 
 | Variable | Description |
@@ -1256,8 +1255,8 @@ the project level.
 <!-- vale off -->
 | Section | Panels |
 |---------|--------|
-| Project summary | Total Projects, Total vClusters, Total Pods, Total CPU (cores), Total Memory, Max Error Rate (stat panels) |
-| Resource usage by project | CPU by Project (cores), Memory by Project, Pods by Project, vClusters by Project (bar charts) |
+| Project summary | Total Projects, Total tenant clusters, Total Pods, Total CPU (cores), Total Memory, Max Error Rate (stat panels) |
+| Resource usage by project | CPU by Project (cores), Memory by Project, Pods by Project, Tenant clusters by Project (bar charts) |
 | API health by project | API Request Rate, API Error Rate (5xx), API P95 Latency (time series) |
 | Resource trends | CPU Usage Trend (stacked), Memory Usage Trend (stacked) (time series) |
 <!-- vale on -->
diff --git a/platform/maintenance/monitoring/fleet/configure-edge-collectors.mdx b/platform/maintenance/monitoring/fleet/configure-edge-collectors.mdx
@@ -98,8 +98,8 @@ The `metrics-writer` key must include a matching `spec.scope.clusters` entry.
 ## Scrape custom targets
 
 Use the collector's `prometheus` receiver to scrape exporters such as kubelet,
-cAdvisor, DCGM exporter, or application endpoints. The gateway does not require a
-specific scrape receiver; it only requires OTLP metrics with valid authentication and
+cAdvisor, DCGM exporter, or application endpoints. The gateway doesn't require a
+specific scrape receiver. It only requires OTLP metrics with valid authentication and
 scope.
 
 Example DCGM scrape job:
@@ -123,7 +123,7 @@ receivers:
 
 ## Protect platform labels
 
-Do not set labels with the `vcluster_platform_*` prefix in edge collectors. The Write
+Don't set labels with the `vcluster_platform_*` prefix in edge collectors. The Write
 Gateway strips this namespace from incoming resource, scope, and datapoint attributes
 before stamping authenticated labels.
 
diff --git a/platform/maintenance/monitoring/fleet/configure-metrics-access.mdx b/platform/maintenance/monitoring/fleet/configure-metrics-access.mdx
@@ -17,8 +17,8 @@ cluster.
 | `metrics-writer` | Edge collectors | Write metrics for the access key's scoped cluster or tenant cluster. |
 | `metrics-reader` | Grafana, PromQL clients, automation | Read metrics for the access key's scoped cluster or tenant cluster. |
 
-The roles are intentionally separate. A `metrics-writer` key cannot read metrics, and
-a `metrics-reader` key cannot write metrics. A key can carry both roles when an
+The roles are intentionally separate. A `metrics-writer` key can't read metrics, and
+a `metrics-reader` key can't write metrics. A key can carry both roles when an
 integration needs both paths.
 
 ## Scope choices
@@ -30,7 +30,7 @@ Scope metrics keys as tightly as possible:
 - Use `*` only for trusted fleet-wide automation.
 
 The Platform authorization check still applies the permissions of the user or subject
-that owns the key. Scope narrows permission; it does not expand it.
+that owns the key. Scope narrows permission. It doesn't expand it.
 
 ## Create a writer key for a tenant cluster
 
diff --git a/platform/maintenance/monitoring/fleet/install-observability-gateway.mdx b/platform/maintenance/monitoring/fleet/install-observability-gateway.mdx
@@ -24,7 +24,7 @@ Before you create the connector, prepare:
 - Optional CA, gateway serving certificate, or backend client certificate Secrets.
 
 :::note
-Phase 1 does not install or size the metrics backend for you. Use your existing backend
+Phase 1 doesn't install or size the metrics backend for you. Use your existing backend
 or deploy one separately.
 :::
 
diff --git a/platform/maintenance/monitoring/fleet/labels-reference.mdx b/platform/maintenance/monitoring/fleet/labels-reference.mdx
@@ -10,7 +10,7 @@ stamped from authenticated Platform context and are safe to use for dashboards,
 recording rules, and backend queries.
 
 :::warning
-Do not set labels with the `vcluster_platform_*` prefix in collectors or applications.
+Don't set labels with the `vcluster_platform_*` prefix in collectors or applications.
 The Write Gateway strips caller-supplied platform labels before adding authenticated
 values.
 :::
@@ -32,7 +32,7 @@ Use either cluster scope or tenant scope, not both:
 
 ## Descriptive labels
 
-These labels are stamped at write time for filtering and grouping, but they do not
+These labels are stamped at write time for filtering and grouping, but they don't
 authorize reads.
 
 | Label | Meaning |
@@ -54,7 +54,7 @@ The Query Proxy restricts matchers on scope-controlling labels:
 | Negative regular expression | Rejected | `vcluster_platform_instance!~"api"` |
 | Wildcard regular expression | Rejected | `vcluster_platform_instance=~".*"` |
 
-Descriptive labels can use normal PromQL matcher forms because they do not determine
+Descriptive labels can use normal PromQL matcher forms because they don't determine
 authorization scope.
 
 ## Label examples
diff --git a/platform/maintenance/monitoring/fleet/overview.mdx b/platform/maintenance/monitoring/fleet/overview.mdx
@@ -51,13 +51,13 @@ An observability connector Secret tells Platform how to reach your metrics backe
 When the connector is present, Platform reconciles the gateway Deployment, Service,
 ServiceAccount, RBAC, collector ConfigMap, and Grafana datasource ConfigMaps.
 
-Platform does not create the metrics backend in Phase 1. You must provide a backend
+Platform doesn't create the metrics backend in Phase 1. You must provide a backend
 that can import OTLP metrics and serve the Prometheus HTTP API. You must also configure
 the edge collectors that send metrics to the gateway.
 
 ## Security model
 
-Fleet monitoring does not rely on backend tenant isolation. The gateway and query proxy
+Fleet monitoring doesn't rely on backend tenant isolation. The gateway and query proxy
 are the enforcement layer.
 
 - Metrics writers must authenticate with an access key that has the `metrics-writer`
diff --git a/platform/maintenance/monitoring/fleet/query-fleet-metrics.mdx b/platform/maintenance/monitoring/fleet/query-fleet-metrics.mdx
@@ -71,8 +71,8 @@ sum by (vcluster_platform_project, vcluster_platform_instance) (
 ```
 
 The Query Proxy rejects unsafe scope matchers such as `!=`, `!~`, `.*`, or regexes
-that are not top-level literal alternations. Descriptive labels can use normal PromQL
-matchers because they do not drive authorization.
+that aren't top-level literal alternations. Descriptive labels can use normal PromQL
+matchers because they don't drive authorization.
 
 ## Grafana datasources
 
diff --git a/platform/maintenance/monitoring/fleet/troubleshooting.mdx b/platform/maintenance/monitoring/fleet/troubleshooting.mdx
diff --git a/platform/maintenance/monitoring/metrics.mdx b/platform/maintenance/monitoring/metrics.mdx
diff --git a/platform/maintenance/monitoring/overview.mdx b/platform/maintenance/monitoring/overview.mdx
diff --git a/platform/maintenance/monitoring/prometheus-shared-nodes.mdx b/platform/maintenance/monitoring/prometheus-shared-nodes.mdx
