Skip to content

Document Metrics API in observability concepts #56956

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tico88612 wants to merge 2 commits into
base: dev-1.37
Choose a base branch
from
+24 −2
Open

Document Metrics API in observability concepts #56956

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b533de5
Document Metrics API in observability concepts
tico88612 Aug 12, 2026
4b3a025
Apply Suggestion
tico88612 Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion content/en/docs/concepts/cluster-administration/observability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@ weight: 55
content_type: concept
description: >
Understand how to gain end-to-end visibility of a Kubernetes cluster through the collection of metrics, logs, and traces.
api_metadata:
- apiVersion: "metrics.k8s.io/v1"
kind: "NodeMetrics"
- apiVersion: "metrics.k8s.io/v1"
kind: "PodMetrics"
no_list: true
card:
name: setup
Expand Down Expand Up @@ -72,12 +77,36 @@ For multi-cluster or multi-cloud visibility, distributed time series databases (

See [Common observability tools - metrics tools](#metrics-tools) for metrics scrapers and time series databases.

### Metrics API

{{< feature-state for_k8s_version="v1.37" state="stable" >}}

@lmktfy lmktfy Aug 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is only kind of true, I think. Could you install the v1 API into a v1.36 cluster? I think you could.

@tico88612 tico88612 Aug 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although metrics.k8s.io/v1 was introduced with Kubernetes v1.37, an independent aggregated API provider could technically serve it on an older cluster.

I removed the feature-state notice to avoid implying that v1.37 is a hard minimum cluster version.


The Kubernetes Metrics API provides CPU and memory resource usage for nodes and Pods. The
`kubectl top` command and components such as the
[HorizontalPodAutoscaler](/docs/concepts/workloads/autoscaling/horizontal-pod-autoscale/)
and [VerticalPodAutoscaler](/docs/concepts/workloads/autoscaling/vertical-pod-autoscale/)
use this API.

`kubectl top` supports both `metrics.k8s.io/v1` and `metrics.k8s.io/v1beta1`. It prefers `v1`

@lmktfy lmktfy Aug 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For simplicity, just skip this paragraph (for now). Easier to get a stub merged than a more detailed page / section perfect.

@tico88612 tico88612 Aug 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. I removed this paragraph to keep the initial Metrics API section simple and focused on the concept.

when that version is available and falls back to `v1beta1`. In Kubernetes v1.37, the
HorizontalPodAutoscaler controller supports only `metrics.k8s.io/v1beta1`; support for
`metrics.k8s.io/v1` is planned but is not available yet.

Unlike the component metrics endpoints described earlier, the Metrics API is served through the
Kubernetes [API aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).
Your cluster must run [Metrics Server](https://github.com/kubernetes-sigs/metrics-server) or another
implementation that provides the API. The Metrics API intentionally provides only the resource
metrics needed for autoscaling and basic inspection; it is not a replacement for a full monitoring
pipeline.

To learn about the API, its implementations, and the data flow from kubelets to its clients, see the

@lmktfy lmktfy Aug 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feedback is more than a nit, but given how close we are to the v1.37 release day, I don't want this feedback to block a merge.

This hyperlinking isn't quite right. If the current task page has some conceptual explanation, either move it here or copy it.

We shouldn't refer people to a task page as part of undertaking a concept; the audience for a task page is people who are moderately familiar with the concept already, and want to be walked through what to do.

(there is a separate idea of a tutorial page, but I doubt there is time to get one written)

@tico88612 tico88612 Aug 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, agreed. I added a concise explanation here that Metrics Server collects resource metrics from kubelets and makes them available through the Metrics API.

I also removed the task-page link so that this concept section is self-contained without significantly expanding the stub.

[resource metrics pipeline](/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/).

#### {{% heading "seealso" %}}

- [System metrics for Kubernetes components](/docs/concepts/cluster-administration/system-metrics/)
- [Resource usage monitoring with metrics-server](/docs/tasks/debug/debug-cluster/resource-usage-monitoring/)
- [kube-state-metrics concept](/docs/concepts/cluster-administration/kube-state-metrics/)
- [Resource metrics pipeline overview](/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/)

## Logs

Expand Down
3 changes: 2 additions & 1 deletion content/en/docs/concepts/extend-kubernetes/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,8 @@ For more about Custom Resources, see the
### API aggregation layer

You can use Kubernetes' [API Aggregation Layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)
to integrate the Kubernetes API with additional services such as for [metrics](/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/).
to integrate the Kubernetes API with additional services such as the
[Metrics API](/docs/concepts/cluster-administration/observability/#metrics-api).

### Combining new APIs with automation

Expand Down