Introduction

If you want live CPU and memory usage for Pods from Python, the normal Kubernetes core API is not enough by itself. Current usage comes from the Metrics API, which is typically served by metrics-server and exposed under the metrics.k8s.io API group.

That means the Python client can retrieve the data, but only if metrics are actually available in the cluster. The basic flow is: load config, call the metrics endpoint through CustomObjectsApi, and parse the returned CPU and memory quantities.

This distinction matters because many developers first inspect Pod status and assume usage should be there. In Kubernetes, desired resources and observed resources are exposed through different APIs on purpose.

Prerequisite: Metrics Server Must Exist

Before writing Python code, confirm that the metrics API is installed:

kubectl top pods -A

If that command fails, your Python code will fail for the same reason. kubectl top and the Python client both depend on the same metrics pipeline.

Query Pod Metrics with the Python Client

The Kubernetes Python client exposes arbitrary API groups through CustomObjectsApi. Pod metrics usually live at metrics.k8s.io/v1beta1.

1from kubernetes import client, config
2
3config.load_kube_config()
4
5api = client.CustomObjectsApi()
6pod_metrics = api.list_cluster_custom_object(
7    group="metrics.k8s.io",
8    version="v1beta1",
9    plural="pods",
10)
11
12for item in pod_metrics["items"]:
13    namespace = item["metadata"]["namespace"]
14    name = item["metadata"]["name"]
15    print(namespace, name)

If your code runs inside the cluster, replace load_kube_config() with load_incluster_config().

Parse CPU and Memory Quantities

The response contains per-container usage, with values such as 25m for CPU or 128Mi for memory. You usually want to sum container usage per Pod.

1from kubernetes import client, config
2from kubernetes.utils.quantity import parse_quantity
3
4config.load_kube_config()
5api = client.CustomObjectsApi()
6
7pod_metrics = api.list_namespaced_custom_object(
8    group="metrics.k8s.io",
9    version="v1beta1",
10    namespace="default",
11    plural="pods",
12)
13
14for pod in pod_metrics["items"]:
15    cpu_total = 0
16    memory_total = 0
17
18    for container in pod["containers"]:
19        cpu_total += parse_quantity(container["usage"]["cpu"])
20        memory_total += parse_quantity(container["usage"]["memory"])
21
22    print(
23        f'{pod["metadata"]["name"]}: '
24        f'cpu={cpu_total} cores, '
25        f'memory={memory_total / (1024 * 1024):.2f} MiB'
26    )

parse_quantity converts Kubernetes quantity strings into numeric values. That is much safer than hand-parsing suffixes yourself.

Get Metrics for One Pod

If you only need one Pod, list the namespace and filter by name:

1target_name = "api-server-7d8d8f9f8b-abcde"
2
3for pod in pod_metrics["items"]:
4    if pod["metadata"]["name"] == target_name:
5        print(pod)
6        break

The Metrics API is list-oriented, so filtering in Python is common. For large clusters, you may want to reduce scope to one namespace instead of asking for the whole cluster.

Understand What This Data Represents

These metrics are near-real-time usage, not resource requests or limits. If you need declared resources from the Pod spec, use CoreV1Api:

1core_api = client.CoreV1Api()
2pod = core_api.read_namespaced_pod("api-server-7d8d8f9f8b-abcde", "default")
3
4for container in pod.spec.containers:
5    print(container.name, container.resources.requests, container.resources.limits)

That gives you the configured resource envelope, while the Metrics API gives you observed usage. In production monitoring, you usually need both.

Common Pitfalls

• Using CoreV1Api and expecting current CPU and memory usage. The core API exposes specs and status, not usage metrics.
• Forgetting to install metrics-server, which makes the metrics API unavailable.
• Summing per-container values incorrectly. Pod metrics are usually the total of all its containers.
• Confusing CPU millicores such as 250m with whole cores. Quantity parsing matters.
• Ignoring RBAC. A service account may be allowed to read Pods but not metrics endpoints.

Summary

• Live Pod usage comes from the Metrics API, not the standard core Pod API.
• Use CustomObjectsApi against metrics.k8s.io/v1beta1.
• Confirm metrics availability first with kubectl top.
• Sum container usage to compute total Pod usage.
• Use CoreV1Api separately when you need requests and limits instead of live consumption.