benvin-utils/podgap/README.md

podgap

Shows the gap between what Kubernetes pods reserve (requests/limits) and what they actually use — live, in a terminal UI that refreshes in place and marks whether each pod's usage rose (▲) or fell (▼) since the last refresh. Use it to find over-provisioned pods (reserving cores they never touch) and under-provisioned ones (running hot against their limits).

Usage is summed across all containers in a pod; only Running pods are shown. Reads live data from the metrics.k8s.io API (same source as kubectl top).

Build

make podgap          # from the repo root → ./bin/podgap
# or: go build -o podgap ./podgap

Usage

podgap                       # live TUI, all namespaces, refresh every 3s
podgap --top 15 -i 5s        # top 15 by CPU waste, refresh every 5s
podgap -n observability -s mem-util
podgap --over                # over-provisioned pods (right-size DOWN candidates)
podgap --under               # usage over request or near limit (right-size UP)
podgap -o json               # one-shot machine output (no TUI); also -o csv

Keys

Key	Action
↑/↓, j/k	Scroll
pgup/pgdn, g/G	Page / jump to top/bottom
c / C	Sort by CPU waste / CPU utilization
m / M	Sort by memory waste / memory utilization
n	Sort by name
p / space	Pause / resume auto-refresh
r	Refresh now
q / esc	Quit

Reading the table

NAMESPACE  POD  CPU req→use/lim  ▲  CPU%  MEM req→use/lim  ▲  MEM%  CPU wst  MEM wst

• req→use/lim — configured request, live usage, configured limit (- if unset).
• ▲ / ▼ / · — usage rose / fell / held steady since the last refresh.
• CPU% / MEM% — usage as a percentage of the request; tinted amber ≥80%, red ≥100% (n/a if no request set).
• wst (waste) — request − usage. Positive = idle reserved capacity; negative = over the request (a right-size-up candidate).

Flags

Flag	Default	Description
-n, --namespace	all	Namespace to inspect
-s, --sort	cpu-waste	cpu-waste, mem-waste, cpu-util, mem-util, cpu-use, mem-use, name
--top	0 (all)	Show only the top N rows
-i, --interval	3s	TUI refresh interval
-o, --output	tui	tui, json, csv
--over	off	Only over-provisioned pods (util < --threshold)
--under	off	Only under-provisioned pods
--threshold	0.5	Utilization fraction defining "over-provisioned"
--kubeconfig	—	Path to kubeconfig (default: in-cluster, then $KUBECONFIG, then ~/.kube/config)

Requirements

• A cluster with metrics-server / the metrics.k8s.io/v1beta1 API (check with kubectl top pods).
• RBAC: list on pods and on pods.metrics.k8s.io.