🚀 kptop

kptop (Kubernetes Top Pod per Node) is a high-performance CLI utility for real-time monitoring of pod resource consumption on a specific node. It bridges the gap between kubectl top and kubectl get pods, providing a live "dashboard" view directly in your terminal.

✨ Key Features

• Node-Centric: Defaults to the local node (hostname) but can target any node in the cluster with -n.
• Live Watch Mode: Real-time updates with the -w flag (re-runs metrics every 2 seconds).
• Diagnostic "Wide" View: Use -o wide to reveal Restart Counts and QoS Classes.
• Threshold Filtering: Silence the noise using --min-cpu or --min-mem.
• Smart Sorting: Intelligently sorts by CPU or Memory while preserving human-readable units (Mi, Gi, m).
• Lightweight: Pure Bash. No heavy binaries, just utilizes your existing kubectl and awk.

---

📥 One-Line Installation

Run this command to download, permission, and install kptop to your system path:

curl -sSL https://raw.githubusercontent.com/Automationxperts/kptop/main/kptop | sudo tee /usr/local/bin/kptop > /dev/null && sudo chmod +x /usr/local/bin/kptop

---

🛠 Usage Guide

1. The "Quick Look"

Monitor the local node, sorted by Memory usage (default):

kptop

2. Live Dashboard (Watch Mode)

Refresh every 1 second and sort by CPU usage:

kptop -w 1 -c

3. Deep Dive Diagnostic

See which pods are crashing (Restarts) and their eviction priority (QoS Class):

kptop -o wide

4. Surgical Filtering

Only show pods using more than 1 GiB of RAM on a specific worker node:

kptop -n worker-node-05 --min-mem 1Gi

---

📖 Flag Reference

Flag	Long Flag	Description
-c	--cpu	Sort by CPU usage.
-m	--memory	Sort by Memory usage (Default).
-n	--node	Target a specific node name.
-o wide		Show Restart Counts and QoS Class.
-w	--watch	Live refresh. Optional interval in seconds (default: 2).
	--min-cpu	Filter pods below value (e.g., 200m).
	--min-mem	Filter pods below value (e.g., 1Gi).
	--no-cpu	Hide the CPU column.
	--no-mem	Hide the Memory column.
	--no-node	Hide the Node Name column.
-h	--help	Show the help menu.

---

🔍 Troubleshooting Guide

When using kptop -o wide, use the following logic to diagnose pod health issues.

1. Interpreting Restart Counts

A high restart count is often more critical than high resource usage.

• Restarts > 0 + Low Resource Usage: Likely a CrashLoopBackOff. The pod is failing before it can even start consuming resources. Check kubectl logs --previous.
• Restarts > 0 + High Memory Usage: Indication of an OOMKill (Out of Memory). The pod hit its limit, the kernel killed it, and it restarted.
• Restarts = 0 + High Memory Usage: The pod is a "Memory Leaker." It is growing steadily but hasn't hit the limit yet.

2. Interpreting QoS Classes (Eviction Priority)

The QOS_CLASS determines which pod the node will "sacrifice" first when it runs out of memory or CPU.

QoS Class	Meaning	Risk Level
Guaranteed	Requests = Limits. The pod has a reserved seat.	Lowest (Last to be killed)
Burstable	Requests < Limits. The pod has a seat but might "burst" higher.	Medium
BestEffort	No Requests or Limits set. The pod is a "squatter."	Highest (First to be killed)

Pro-Tip: If your node is under pressure and you see critical services with BestEffort, they are at high risk. Update their manifest to include resource requests to promote them to Burstable or Guaranteed.

---

📝 Requirements

• Metrics Server: Must be active in your cluster.
• Permissions: You need get and list permissions for Pods and metrics.k8s.io.
• Tools: Requires kubectl, awk, and column.

---