kubectl top pod metrics explained

Ops teams need real-time insight into pod resource usage. kubectl top pod fetches CPU and memory metrics per pod. It taps the metrics-server API to report current consumption. Admins can spot hotspots and balance loads swiftly.

TL;DR

• kubectl top pod shows CPU and memory usage per pod.
• Use --namespace or -A to scope across namespaces.
• Filter by label with -l flag.
• Include --containers to display per-container metrics.
• Expect a metrics delay after pod creation due to pipeline lag.

kubectl top pod overview

The kubectl top pod command retrieves live resource usage for pods running in a cluster. It relies on metrics-server, which scrapes kubelets at intervals. The API server exposes these metrics under /apis/metrics.k8s.io. Administrators use this command to track performance and detect resource bottlenecks.

kubectl top pod syntax and options

Basic syntax:

kubectl top pod [NAME | -l label] [--containers] [--namespace=NAMESPACE] [-A]

Core options:

• NAME: Specify a pod name to view metrics for that pod.
• -l, --selector: Filter pods by label selector.
• --containers: Show metrics for individual containers within pods.
• --namespace: Set target namespace.
• -A, --all-namespaces: Display pods across all namespaces.

Using kubectl top pod with containers

To inspect container-level metrics, append --containers.

kubectl top pod my-pod --containers

This command lists CPU and memory usage per container. Use this view to isolate misbehaving containers.

Metrics pipeline and delays

Metrics-server polls kubelet endpoints every 30 seconds by default. It stores data temporarily before serving API requests. After pod creation, a short delay may occur before metrics appear. Plan workflows accordingly to avoid null results.

Use-cases for kubectl top pod

• Alerting: Spot pods exceeding CPU or memory thresholds.
• Diagnostics: Identify memory leaks or CPU spikes in real time.
• Capacity planning: Gauge resource usage trends across namespaces.
• HPA tuning: Validate Horizontal Pod Autoscaler triggers based on metrics.

Common troubleshooting tips

• Ensure metrics-server runs and has RBAC permissions. Grant system:aggregated-metrics-reader role if needed.
• Check Heapster is deprecated; metrics-server replaced it in v1.8.
• Use kubectl get apiservices | grep metrics to verify API registration.
• Inspect metrics-server logs for scrape errors: kubectl logs -n kube-system deploy/metrics-server.

References

1. kubectl top pod

Suggested Reading

• What is KEDA: Kubernetes Event-Driven Autoscaling
• Monitoring Kafka Partitions
• Understanding and Managing Failed Partitions in Kafka
• Namespace Scope in Kubernetes
• Kubernetes Official CVE Feed – Consume and Process

PostHashID: 67c159ae97315eef1426d2763bfde1c74f39a93bc27c63d4e73de95068fe3ca1