Resource metrics API — the metrics.k8s.io surface

The metrics.k8s.io API surface is the Metrics Server’s output. The API exposes the resource usage for nodes, pods, and namespaces. This lesson walks the API surface, the queries, the integration, and the production patterns.

The API surface

The metrics.k8s.io API:

flowchart LR
    A["metrics.k8s.io API"] --> B["/nodes"]
    A --> C["/nodes/{name}"]
    A --> D["/pods"]
    A --> E["/namespaces/{namespace}/pods"]

The API endpoints are the resource metrics.

The nodes endpoint

The nodes endpoint:

kubectl get --raw=/apis/metrics.k8s.io/v1beta1/nodes

{
  "kind": "NodeMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "items": [
    {
      "metadata": {"name": "cp-1"},
      "timestamp": "2026-08-16T10:00:00Z",
      "window": "30s",
      "usage": {"cpu": "500m", "memory": "2048Mi"}
    }
  ]
}

The nodes endpoint returns all nodes.

The single node endpoint

kubectl get --raw=/apis/metrics.k8s.io/v1beta1/nodes/cp-1

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {"name": "cp-1"},
  "timestamp": "2026-08-16T10:00:00Z",
  "window": "30s",
  "usage": {"cpu": "500m", "memory": "2048Mi"}
}

The single node endpoint returns one node.

The pods endpoint

The pods endpoint:

kubectl get --raw=/apis/metrics.k8s.io/v1beta1/pods

{
  "kind": "PodMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "items": [
    {
      "metadata": {"name": "nginx-1-abc", "namespace": "default"},
      "containers": [
        {
          "name": "nginx",
          "usage": {"cpu": "100m", "memory": "128Mi"}
        }
      ]
    }
  ]
}

The pods endpoint returns all pods.

The namespace pods endpoint

kubectl get --raw=/apis/metrics.k8s.io/v1beta1/namespaces/default/pods

The namespace pods endpoint returns the pods in a specific namespace.

The API versions

The API versions:

The production version is v1.

kubectl get --raw=/apis/metrics.k8s.io/v1/nodes

The v1 API is the current version.

The fields

The fields:

metadata.name: the node or pod name
metadata.namespace: the namespace (for pods)
metadata.creationTimestamp: not used in metrics
timestamp: when the metrics were collected
window: the time window of the metrics (typically 30s)
usage.cpu: the CPU usage (in millicores, e.g., 100m = 0.1 CPU)
usage.memory: the memory usage (in bytes, e.g., 128Mi = 128 mebibytes)

The fields are stable across versions.

The resource format

The resource format:

CPU: 100m = 0.1 CPU; 1 = 1 CPU
Memory: 128Mi = 128 * 2^20 bytes; 1Gi = 2^30 bytes

The format is the Kubernetes resource format.

The HPA integration

The HPA queries the API:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

The HPA queries the metrics.k8s.io API for the CPU usage.

The kubectl top integration

The kubectl top uses the API:

kubectl top nodes
kubectl top pods -A
kubectl top pods -n default
kubectl top pods -A --containers

The kubectl top is the interactive inspection.

The custom controller integration

The custom controller can query the API:

import (
    "k8s.io/client-go/kubernetes"
    metricsv1beta1 "k8s.io/metrics/pkg/client/clientset/versioned/typed/metrics/v1beta1"
)

client, _ := metricsv1beta1.NewForConfig(config)
podMetrics, _ := client.PodMetrics("default").List(ctx, metav1.ListOptions{})

The custom controller can use the client library.

Cross-course references

• The HPA course (Part LXXXII) covers the integration.
• The Custom Metrics Adapter course covers the custom metrics.
• The Prometheus Adapter course covers the adapter.

Quiz

Production discipline

• Use the metrics.k8s.io API. The resource metrics source.
• Use kubectl top for interactive inspection. The quick query.
• Use the API for the HPA integration. The HPA controller.
• Use the API for custom controllers. The client library.
• Document the API queries. The endpoints, the format.
• Test the API. Verify the metrics are correct.

The metrics.k8s.io API is the resource metrics source. Operating it well is using the API, the kubectl top, and the client library for the integrations.