ferctl

A lightweight CLI for Kubernetes that shows pod CPU and memory usage alongside configured requests and limits, flagging pods that are approaching their thresholds.

Features

• Displays live CPU and memory usage per pod from metrics-server
• Shows requests and limits side by side with usage percentages
• Flags pods as WARNING (≥80% of limit) or CRITICAL (≥95% of limit)
• Supports single-namespace and cluster-wide (--all-namespaces) views
• Configurable warning threshold via --warning-percent

Prerequisites

• A running Kubernetes cluster with metrics-server installed
• A valid kubeconfig (defaults to ~/.kube/config)

Installation

Build from source

git clone https://github.com/FerRiosCosta/ferctl.git
cd ferctl
make build

This produces a ferctl binary in the current directory.

Install to /usr/local/bin

make install

Usage

ferctl top [flags]

Flags

Flag	Default	Description
-n, --namespace	default	Namespace to query
-A, --all-namespaces	false	Query all namespaces
--kubeconfig	~/.kube/config	Path to kubeconfig file
--warning-percent	80	Usage % above which to show a warning

Examples

# Show pods in the default namespace
ferctl top

# Show pods in a specific namespace
ferctl top -n kube-system

# Show pods across all namespaces
ferctl top --all-namespaces

# Use a custom warning threshold
ferctl top -n default --warning-percent 70

Sample output

NAMESPACE   NAME               CPU USE  CPU REQ  CPU LIM  CPU%  MEM USE  MEM REQ  MEM LIM  MEM%  STATUS
default     my-app-7d9f8b      45m      100m     500m     9%    128Mi    64Mi     256Mi    50%      OK
default     memory-hog         12m      0m       0m       0%    145Mi    10Mi     150Mi    96%   !! CRITICAL
kube-system coredns-5d78c9869  8m       100m     0m       0%    14Mi     70Mi     170Mi    8%       OK

Status levels

Status	Condition
OK	Usage is below the warning threshold
! WARNING	Usage is at or above --warning-percent of the limit
!! CRITICAL	Usage is at or above 95% of the limit

When no limit is set for a container, the status is always OK.

Testing

make test

Project structure

cmd/ferctl/       # main entrypoint
internal/
  kubernetes/     # Kubernetes and metrics-server client wrappers
  threshold/      # status evaluation logic (OK / WARNING / CRITICAL)
  top/            # command wiring, runner, and table output
memory-hog.yaml   # example pod manifest that exceeds its memory limit

Development

The binary embeds the current git tag at build time:

make build   # produces ./ferctl with version info embedded
make clean   # removes the built binary