docs: add fleet observability phase 1 guide#2371
Conversation
✅ Deploy Preview for vcluster-docs-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
cadd8da to
817cc78
Compare
|
Noticed a naming mismatch while doing a style pass on this PR's docs: The downloadable dashboard JSON itself ( Fixing that means editing the panel titles in the dashboard JSON asset, which is outside a docs style pass. Flagging so it can get tracked and fixed at the source (or the docs table reverted to match, if renaming the JSON isn't planned). |
|
I added three candidate dashboard screenshots as static assets so engineering can decide whether any are worth using in the fleet monitoring docs:
If engineering decides these screenshots should not be used, we should delete them before merging so the PR does not carry unused binary assets. |
Fix Google.Headings sentence-case, Loft.no-latinisms, and Google.WordList (ingest, regex) warnings across the fleet monitoring guides. Add TLS, mTLS, and PromQL to the accepted vocab since Google.Headings was misflagging them as improper title-case capitalization in headings.
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.
…et monitoring Add a dedicated page describing the default ArgoCDApplicationTemplate resources Platform ships (metrics backend, Grafana, edge collectors) and how to deploy them from ArgoCDApplication resources, with YAML and Platform UI tabs. Wire the new page into the overview teaser and page guide, the install note, and the edge collectors tip, and renumber the sidebar to insert it after the install page. Note the intended gap that vCluster Standalone tenant clusters can't use the Argo CD integration, so their collectors must be deployed manually.
"Phase 1" is internal roadmap jargon that leaked into the docs and doesn't mean anything to readers. Frame the scope note around the paths that actually exist today instead.
…ply snippets Static YAML with a placeholder key value left readers to generate and insert the secret themselves, which is easy to get wrong. Show a single copy-paste flow that generates the key and applies the AccessKey, driven by editable PROJECT/TENANT_CLUSTER/CLUSTER values.
…fana The bundled Grafana is the primary way most operators will read fleet metrics, but the page only covered raw PromQL. Explain sign-in, the shipped dashboards, and how the scoped datasources authorize as the signed-in user so datasource choice can't widen access.
0e26a8b to
12c3830
Compare
Thx. Included them in the new Grafana section. |
IMHO it's a bit confusing that we now have "Fleet monitoring" and "Fleet monitoring with OpenTelemetry" next to each other. Are there plans to consolidate them or at least move them further apart? cc @cbron @Stillstellung
|
75caa03 to
4d64993
Compare
4d64993 to
951cc77
Compare
I spoke w/ @djwfyi and he's going to think about which path to take, but you're right, it's a little clunky as is |
Thank you. Also, we recently switched terms from monitoring/metrics to observability. So probably a chance to introduce "Observability" under "Maintenance" and start consolidating/removing older stuff there?! |
Screenshots still go stale as the UI changes, but blocking them outright was too strict for cases like dashboard views that are hard to describe in prose.
Promotes the new gateway-based feature out of monitoring/fleet into its own Observability category alongside Monitoring and Logging under Maintenance, fixing the nav proximity confusion with the older "Fleet monitoring with OpenTelemetry" page. Also clarifies that this release covers metrics only, softens an overclaiming "full-stack observability" line, and cross-links vCluster's own logging guide for readers who land here looking for log collection.
Only Fleet Observability routes through the Write Gateway and Query Proxy; the older OpenTelemetry guides push directly to the backend. Also clarifies that bundled Grafana dashboards ship today (only their lifecycle automation is future work), and swaps "Fleet Observability data" for "fleet metrics" to keep the product name off the metrics-only payload.
|
Pushed three follow-up commits addressing feedback on the fleet monitoring section's naming and info architecture:
All three verified clean against vale, |
…racies Corrects several implementation-accuracy gaps found by comparing the docs against loft-enterprise: - The fleet connector label is platform.vcluster.com/fleet-observability-connector, not loft.sh/fleet-observability-connector. - The gateway always serves OTLP and query traffic over TLS; docs treated it as optional and used http:// in examples. - metricsBackendCaData and observabilityCaSecretName aren't read by the controller; removed them and documented metricsBackendCertSecretName's actual ca.crt/tls.crt/tls.key requirement. - Documents serviceType, serviceAnnotations, and the Grafana connector keys (grafanaUrl, grafanaCertSecretName, fleetObservabilityDashboardUid) that the controller and UI actually use. - The connector ID isn't required to be "fleet-observability"; gateway resource names derive from the connector Secret's own name. - Reframes datasource lifecycle management as already implemented today (per-VCI and per-cluster reconcilers exist); only per-tenant connector selection and access-key generation remain future work. - Adds the vCluster Platform license as an explicit prerequisite, since the controllers aren't registered at all without it. - Uses the bundled Prometheus template's exact endpoints, including the required /api/v1/otlp path. - Fixes control plane cluster casing to lowercase per house style. Left the cluster-collector template's current kube-state-metrics/node-exporter description and the otlpEndpoint default intact: loft-enterprise PRs #7526 and #7532 will change that behavior, but both are still open, so documenting the pre-merge state would be premature.
The query examples referenced $GATEWAY_CA_FILE without showing how to extract it from the gateway's serving certificate Secret.
|
Pushed two more commits fixing implementation-accuracy gaps found by comparing the docs against
One thing deliberately not changed: the
All changes verified against the actual |
|
Added a LoadBalancer exposure section for the gateway (serviceType/annotations, address retrieval, per-port endpoint table for OTLP + query), plus an OTLP wording pass. Clean against validate-glossary and the build. |
|
Added an out-of-the-box "Get started" section, switched the tabbed examples to UI-first, and reordered the observability pages for the happy path (Grafana-first querying, Argo CD grouped by deployment target, flow-ordered page guide). |
…tel guide .vale.ini and CLAUDE.md conflicts were additive on both sides; kept both blocks. In the otel guide, prefer main's UI-drift accuracy fixes (button label, nav path) and its more precise "collection time" wording, but keep this branch's "and so on" (matches the Loft.no-latinisms substitution exactly) and its "tenant cluster" terminology fix (vCluster is not the name of the cluster it creates).
* Backport: Copy platform/maintenance/monitoring/central-hostpath-mapper.mdx to platform_versioned_docs/version-4.11.0/maintenance/monitoring/central-hostpath-mapper.mdx * Backport: Copy platform/maintenance/monitoring/fleet-monitoring-otel.mdx to platform_versioned_docs/version-4.11.0/maintenance/monitoring/fleet-monitoring-otel.mdx * Backport: Copy platform/maintenance/monitoring/metrics.mdx to platform_versioned_docs/version-4.11.0/maintenance/monitoring/metrics.mdx * Backport: Copy platform/maintenance/monitoring/overview.mdx to platform_versioned_docs/version-4.11.0/maintenance/monitoring/overview.mdx * Backport: Copy platform/maintenance/monitoring/prometheus-shared-nodes.mdx to platform_versioned_docs/version-4.11.0/maintenance/monitoring/prometheus-shared-nodes.mdx * Backport: Copy platform/maintenance/observability/_category_.json to platform_versioned_docs/version-4.11.0/maintenance/observability/_category_.json * Backport: Copy platform/maintenance/observability/configure-edge-collectors.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/configure-edge-collectors.mdx * Backport: Copy platform/maintenance/observability/configure-metrics-access.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/configure-metrics-access.mdx * Backport: Copy platform/maintenance/observability/deploy-with-argocd.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/deploy-with-argocd.mdx * Backport: Copy platform/maintenance/observability/install-observability-gateway.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/install-observability-gateway.mdx * Backport: Copy platform/maintenance/observability/labels-reference.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/labels-reference.mdx * Backport: Copy platform/maintenance/observability/overview.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/overview.mdx * Backport: Copy platform/maintenance/observability/query-fleet-metrics.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/query-fleet-metrics.mdx * Backport: Copy platform/maintenance/observability/troubleshooting.mdx to platform_versioned_docs/version-4.11.0/maintenance/observability/troubleshooting.mdx


Content Description
Adds a new Fleet monitoring docs section for the Phase 1 monitoring release. The new pages document the observability gateway, Write Gateway, Query Proxy, metrics access keys, edge collector configuration, PromQL querying, platform labels, and troubleshooting.
The monitoring overview now points to this release path first, while the older OpenTelemetry pages remain available as simpler or advanced collector references.
Preview Link
https://deploy-preview-2371--vcluster-docs-site.netlify.app/docs/platform/next/maintenance/observability/overview
PR adds that file and the following to the same doc folder:
/platform/maintenance/monitoring/fleet/install-observability-gateway/platform/maintenance/monitoring/fleet/deploy-with-argocd/platform/maintenance/monitoring/fleet/configure-metrics-access/platform/maintenance/monitoring/fleet/configure-edge-collectors/platform/maintenance/monitoring/fleet/query-fleet-metrics/platform/maintenance/monitoring/fleet/labels-reference/platform/maintenance/monitoring/fleet/troubleshootingInternal Reference
Closes ENGPLAT-471
Validation:
git diff --checknpm run validate-glossarynpm run validate-mdx-links(LIVE-BROKEN: 0; existing fragment/partial warnings remain outside this change)npm run buildAI review: mention
@claudein a comment to request a review or changes. See CONTRIBUTING.md for available commands.@netlify /docs