Skip to content

docs: add unified Kubernetes monitoring entry point under install-pmm#5406

Open
michaelcoburn wants to merge 1 commit into
percona:v3from
michaelcoburn:docs/k8s-observability-unified-page
Open

docs: add unified Kubernetes monitoring entry point under install-pmm#5406
michaelcoburn wants to merge 1 commit into
percona:v3from
michaelcoburn:docs/k8s-observability-unified-page

Conversation

@michaelcoburn
Copy link
Copy Markdown
Contributor

PMM-XXXXX (JIRA ticket to be filed by Percona-Lab/pmm-workshop-pl2026 maintainer; this PR is the deliverable a JIRA ticket will reference)

Link to the Feature Build: SUBMODULES-0

Why

PMM Server can act as the centralized observability backend for both your databases and the Kubernetes clusters they run on — the integration with the Victoria Metrics Kubernetes monitoring stack already works and is documented in all four Percona operator docs repos:

  • docs.percona.com/percona-operator-for-mysql/ps/monitor-kubernetes.html
  • docs.percona.com/percona-operator-for-mysql/pxc/monitor-kubernetes.html
  • docs.percona.com/percona-operator-for-mongodb/monitor-kubernetes.html
  • docs.percona.com/percona-operator-for-postgresql/2.0/monitor-kubernetes.html

But PMM's own docs only mention this feature in passing on a dashboard reference page (reference/dashboards/kubernetes_monitor_operators.md), which is unlikely to be reached by a user searching for "how do I monitor Kubernetes with PMM."

This is a discoverability gap. A user reading PMM docs to plan their monitoring strategy has no entry point that says "yes, PMM can be your K8s observability backend too — here's how to plug it in."

What

Adds a single new page under install-pmm/install-pmm-client/connect-database/ that:

  • Frames the use case (correlating DB-level and cluster-level signals in one PMM).
  • Lists what gets captured by the stack (cAdvisor / kubelet / CoreDNS / kube-state-metrics / node-exporter / apiserver / control plane) in a table.
  • Cross-links to the operator-specific monitor-kubernetes pages for the actual Helm walkthrough, rather than duplicating ~250 lines of procedure that would drift across five separate locations.
  • Cross-links to existing PMM pages: service-account token, VictoriaMetrics reference, the Kubernetes overview dashboard, Helm-based PMM Server install.
  • Marks the feature Technical Preview, matching the framing already on the dashboard-reference page.

Also:

  • Adds the new page to the "connect-database" overview list (connect-database/index.md).
  • Adds a "Kubernetes monitoring" subsection to the "Configure monitoring" nav in mkdocs-base.yml, alongside the existing Database / Cloud / System / Proxy / External-services subsections.

What this PR does NOT do

  • It does not modify or remove the existing reference/dashboards/kubernetes_monitor_operators.md page — that page is left in place as the dashboard-reference entry point.
  • It does not duplicate the operator-side Helm walkthroughs. Future improvements (e.g. consolidating to a single canonical procedure that the operator repos cross-link to, rather than each having their own copy) are out of scope for this PR.
  • No code changes, no API changes — pure docs.

Test plan

  • mkdocs build -f documentation/mkdocs.yml passes (couldn't validate locally — no mkdocs installed; relying on CI)
  • All inter-doc relative links resolve to existing files (verified manually: api/authentication.md, reference/glossary.md, reference/third-party/victoria.md, reference/dashboards/kubernetes_monitor_operators.md, install-pmm-server/deployment-options/helm/index.md)
  • Nav renders correctly: "Install PMM → Install PMM Client → Configure monitoring → Kubernetes monitoring → Connect Kubernetes cluster"
  • Reviewer confirms the cross-links to operator docs are the most current canonical URLs (paths use docs.percona.com/percona-operator-for-*/monitor-kubernetes.html)

Context

This PR was generated as the deliverable for a docs audit performed for the upcoming Percona Live 2026 PMM 3 hands-on tutorial workshop. The audit confirmed that 7 out of 8 originally-suspected PMM 3 doc gaps had already been resolved by the docs team's PMM 3 refactor — this is the remaining one.

  • API Docs updated (no API surface affected — docs-only)

Adds a discoverable PMM-side page documenting Kubernetes cluster
monitoring with PMM Server as the destination for the Victoria Metrics
Kubernetes monitoring stack (cAdvisor / kubelet / CoreDNS /
kube-state-metrics / node-exporter / apiserver / control-plane).

The integration already works — the Helm walkthroughs live in each
of the four operator docs repos (`monitor-kubernetes.md` in
`k8sps-docs`, `k8spxc-docs`, `k8spsmdb-docs`, `k8spg-docs`). PMM's
own docs only mention K8s monitoring in passing on a dashboard
reference page (`reference/dashboards/kubernetes_monitor_operators.md`)
which is unlikely to be reached by users searching for "how do I
monitor Kubernetes with PMM."

This change:

- adds `install-pmm/install-pmm-client/connect-database/kubernetes.md`
  — a short use-case framing + what-gets-captured table +
  cross-links to the four operator monitor-kubernetes pages for the
  Helm walkthroughs (avoids duplicating ~250 lines of procedure
  across five places that would drift apart over time)
- adds the new page to the connect-database overview list
- adds a "Kubernetes monitoring" nav section under
  "Configure monitoring" in `mkdocs-base.yml`
- marks the feature Technical Preview to match the existing
  framing on the dashboard reference page

No content from the operator repos is duplicated; the new page is
purely a navigation / discoverability improvement.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@michaelcoburn michaelcoburn requested a review from a team as a code owner May 22, 2026 08:16
@github-actions github-actions Bot added the documentation Documentation changes label May 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant