12 CLI Tools for Kubernetes Troubleshooting by Symptom

12 Kubernetes troubleshooting CLI tools mapped to symptoms: k9s, stern, kubectx, krew, kubectl debug, netshoot, Popeye, kube-capacity, Kubeshark and more.

Dec 29, 2025 - 18:10
Nov 10, 2026 - 02:23
 0  61
12 CLI Tools for Kubernetes Troubleshooting by Symptom

The most useful CLI tools for Kubernetes troubleshooting are k9s for a live terminal view, stern for multi-pod logs, kubectx and kubens for context safety, krew for plugins, kubectl debug with netshoot for in-pod network checks, Popeye and kube-capacity for cluster health, and Kubeshark or Inspektor Gadget for eBPF-level traffic and system tracing. This guide maps each tool to the symptom it helps with.

Plain kubectl can answer every question these tools answer. The difference is speed during an incident. If you have not yet learned the built-in commands, start with our list of 15 Kubernetes troubleshooting commands and the Kubernetes architecture components guide, because every tool below sits on top of the same API server, kubelet and container runtime. This page covers the add-on tools, not the commands.

Key takeaways

  • Pick tools by symptom. Log problems, network problems, capacity problems and configuration drift each have a different best tool.
  • kubectl debug is built into kubectl. Ephemeral containers became stable in Kubernetes 1.25, so most clusters support it without extra installs.
  • k9s, stern, kubectx/kubens and Popeye are all open source and actively maintained on GitHub as of November 2026.
  • eBPF tools such as Kubeshark and Inspektor Gadget see traffic and system calls that logs never show, but they run privileged agents on nodes. Get approval before installing them in production.
  • Install plugins through krew where possible so the whole team gets the same versions.

The 12 tools at a glance

#ToolBest forRuns where
1k9sLive view of every resource in one terminalYour workstation
2sternTailing logs across many pods and containersYour workstation
3kubectx and kubensSwitching cluster and namespace without mistakesYour workstation
4krewInstalling and updating kubectl pluginsYour workstation
5kubectl debugShell into distroless pods, debug nodesBuilt into kubectl
6netshootDNS, TCP and HTTP checks from inside the clusterContainer image
7PopeyeFinding misconfigurations and unused objectsWorkstation or in-cluster job
8kube-capacityRequests, limits and real usage per nodekubectl plugin
9kubectl treeFollowing ownership chains (Deployment to Pod)kubectl plugin
10KubesharkSeeing L4/L7 traffic between servicesAgents in cluster, CLI locally
11Inspektor GadgetTracing file opens, DNS, exec and more with eBPFAgents in cluster, CLI locally
12TelepresenceReproducing a bug with local code against the clusterTraffic manager in cluster, CLI locally

Tools for seeing what is happening

1. k9s: a terminal UI for the whole cluster

k9s gives you a full-screen, keyboard-driven view of pods, deployments, events and logs that refreshes as the cluster changes. You can describe, view logs, open a shell, port-forward or delete a resource without typing the full kubectl command each time.

k9s                       # start in the current context
k9s -n payments           # start in one namespace
k9s --context staging     # start against another context
k9s info                  # show config and log file locations

Inside k9s, type : followed by a resource name (for example :pods or :deploy) to jump between views, and ? to see the key bindings. It is the fastest way to spot a pod stuck in CrashLoopBackOff or a rollout that has stopped moving.

Watch out for one thing: k9s can delete and edit resources with a single key press. For production, many teams start it with read-only mode enabled in its configuration.

2. stern: logs from many pods at once

kubectl logs reads one pod (or one label selector with limits). stern follows every pod that matches a query, adds new pods as they start and colour-codes the output by pod and container. That makes it the right tool when a Deployment has ten replicas and only some of them fail.

stern frontend --selector release=canary          # pods with a label, matching "frontend"
stern auth -t --since 15m                         # last 15 minutes, with timestamps
stern -n staging --exclude-container istio-proxy . # skip sidecar logs
stern --all-namespaces -l run=nginx               # one label across all namespaces

The default --since window is 48 hours, so set it explicitly when a pod has a long history. stern can also be installed as a kubectl plugin with kubectl krew install stern.

3. kubectx and kubens: context and namespace safety

A surprising number of incidents start with a command run against the wrong cluster. kubectx switches contexts and kubens switches the default namespace, both with short commands and a quick way to jump back.

kubectx                  # list contexts, current one highlighted
kubectx prod-eu          # switch context
kubectx -                # go back to the previous context
kubens payments          # set default namespace
kubens -                 # previous namespace

Pair them with a shell prompt that shows the current context. The project's README also documents krew installs: kubectl krew install ctx and kubectl krew install ns.

4. krew: the plugin manager

krew is a Kubernetes SIG project that installs, updates and lists kubectl plugins from a shared index. Several tools on this list ship as krew plugins, so installing krew first saves time and keeps versions consistent across a team.

kubectl krew update
kubectl krew search capacity
kubectl krew install resource-capacity tree
kubectl krew list
kubectl krew upgrade

Plugins run with your kubeconfig credentials. Read a plugin's source repository before installing it on a machine that has production access.

Tools for getting inside pods and nodes

5. kubectl debug: ephemeral containers and node shells

Many production images are distroless and have no shell. kubectl debug attaches an ephemeral container with the tools you need, sharing the target container's process namespace. The Kubernetes documentation gives these forms:

# Add a debug container to a running pod and see its processes
kubectl debug -it myapp --image=busybox:1.28 --target=myapp

# Make a copy of the pod with shared process namespace
kubectl debug myapp -it --image=ubuntu --share-processes --copy-to=myapp-debug

# Copy the pod but swap every container image for ubuntu
kubectl debug myapp --copy-to=myapp-debug --set-image=*=ubuntu

# Open a shell on a node; the node's root filesystem is at /host
kubectl debug node/mynode -it --image=ubuntu

The --profile flag controls the security settings of the debug container. Documented values are legacy (the default), general, baseline, restricted, netadmin and sysadmin. Use netadmin for packet-level work and sysadmin only when you need root on a node. Clean up copied pods afterwards because they keep running.

6. netshoot: a network toolbox image

netshoot is a container image packed with network tools such as dig, curl, tcpdump, iperf3 and nmap. Use it as the image for kubectl debug so you test from inside the same network namespace as the failing pod.

# Ephemeral netshoot container next to the app
kubectl debug -it myapp --image=nicolaka/netshoot --target=myapp

# Inside it: is DNS working, and can we reach the service?
dig my-svc.payments.svc.cluster.local
curl -sv http://my-svc.payments:8080/healthz

This answers the common question "is it the app, DNS, or a NetworkPolicy?" in a few minutes. Remove the debug pod when you are done, and do not leave a privileged toolbox running in a shared namespace.

Tools for cluster health and capacity

7. Popeye: a cluster sanitizer

Popeye scans a live cluster and reports problems such as containers without resource limits, missing probes, unused ConfigMaps and Secrets, and services with no endpoints. It gives each namespace a score, which makes it useful for clean-up work and for reviews before an audit.

popeye                      # scan the current namespace
popeye -A                   # all namespaces
popeye -n ns1 -s pod,svc    # only pods and services
popeye --context olive      # another context
popeye -f spinach.yaml      # with a custom config (spinach)

Popeye is less helpful in the middle of an outage. Run it on a schedule and treat the report as a backlog.

8. kube-capacity: requests, limits and usage in one table

Pending pods and OOMKilled containers often come back to resource requests. kube-capacity prints requests, limits and (with metrics-server) live utilisation per node and per pod.

kube-capacity                       # node totals
kube-capacity --pods --util         # per pod, with real usage
kube-capacity --util --sort cpu.util
kube-capacity --available           # free capacity per node
# If installed via krew, the command is:
kubectl resource-capacity --pods

For tuning requests and limits over time, see our guide to Kubernetes resource optimization tools.

9. kubectl tree: who owns what

When a pod keeps coming back after you delete it, something owns it. kubectl tree follows ownerReferences and prints the hierarchy, for example Deployment to ReplicaSet to Pod, or a custom resource down to the objects its operator created.

kubectl tree deployment my-app
kubectl tree --help

It is especially handy with operators and Cluster API objects, where the chain is deep and not obvious from names.

Tools for traffic and kernel-level tracing

10. Kubeshark: API traffic between services

Kubeshark uses eBPF to capture and index L4 and L7 traffic with Kubernetes context (pod, namespace, service). It helps when two services disagree about what was sent, for example an HTTP 500 that appears in one log but not the other.

kubeshark tap        # deploy capture agents and open the dashboard

Captured traffic can include tokens and personal data. Limit captures to the namespaces you need, keep them short and follow your data-handling policy.

11. Inspektor Gadget: eBPF gadgets for nodes and pods

Inspektor Gadget runs eBPF programs ("gadgets") that trace events such as file opens, DNS queries, process execution and TCP connections, and labels the results with pod and namespace names. It is the tool to reach for when logs are empty but something is clearly wrong at the system level.

kubectl gadget deploy                     # install the agents
kubectl gadget run trace_open:latest      # which files are being opened, by which pod

Like Kubeshark, it needs privileged agents on each node. Treat it as an approved operational tool, not something one engineer installs on a whim.

12. Telepresence: reproduce with local code

Some bugs only appear with real cluster dependencies. Telepresence connects your laptop to the cluster network and can intercept traffic for a workload so your local process receives it. That lets you attach a debugger to code that is talking to real services.

telepresence connect
telepresence intercept my-service --port 8080

Use it in development and staging clusters. Intercepting production traffic sends real user requests to a laptop.

A troubleshooting flow using these tools

  1. Confirm where you are: kubectx and kubens.
  2. Look at the big picture in k9s: which pods are not Ready, which events are new.
  3. Read logs across replicas with stern, using --since to match the incident window.
  4. If the image has no shell, attach kubectl debug with netshoot and test DNS and service reachability.
  5. If pods are Pending or OOMKilled, check kube-capacity for requests against node allocatable.
  6. If objects keep reappearing, run kubectl tree to find the owner.
  7. If the cause is still hidden, use Kubeshark (traffic) or Inspektor Gadget (system calls) with approval.
  8. After the incident, run Popeye and fix the misconfigurations it lists so the same class of problem is less likely.

For the pod-level side of this flow (CrashLoopBackOff, ImagePullBackOff, probes), see 10 Kubernetes pod troubleshooting techniques.

Symptom to tool cheat sheet

SymptomFirst toolThen
Some replicas fail, others are finesternk9s events view
Distroless pod, need a shellkubectl debugnetshoot image
Service unreachable or DNS errorsnetshoot via kubectl debugKubeshark
Pods stuck Pendingkube-capacityk9s (describe, events)
Deleted pod keeps returningkubectl treek9s
Ran a command in the wrong clusterkubectx (prevention)Shell prompt context display
App fails with no useful logsInspektor Gadgetkubectl debug node/
Bug only reproduces with real dependenciesTelepresence (non-prod)Debugger in your IDE
Slow drift of bad configurationPopeyePolicy tools in CI

Safety rules for troubleshooting tools

  • Give engineers read-only RBAC by default and a separate, audited role for kubectl debug and exec.
  • Keep debug images in your own registry so they are scanned like any other image.
  • Delete copied debug pods and node debug pods after use. They are ordinary pods and keep consuming resources.
  • Agree in advance which eBPF tools are approved for production, and who can deploy them.
  • Write what you ran into the incident notes. The tools are fast, which makes it easy to forget what changed.

How to practise

A local kind or minikube cluster is enough. Break things on purpose: set a wrong image tag, remove a Service selector, set a memory limit far below what the app needs, or add a NetworkPolicy that blocks DNS. Then use the tools above to find each fault. The same exercises appear in the hands-on labs of our CKA training, available in the Kharadi, Pune classroom and live online. Note that the CKA exam itself gives you kubectl and the official docs, not these add-on tools, so learn the built-in commands first. Our list of daily kubectl commands covers that base, and the most asked Kubernetes interview questions show how troubleshooting is tested in interviews.

FAQ

Which Kubernetes troubleshooting tool should I learn first?

Learn plain kubectl first, then k9s and stern. Those two cover most day-to-day debugging: seeing which resources are unhealthy and reading logs across replicas.

Is kubectl debug available in every cluster?

It is part of kubectl, and ephemeral containers are stable since Kubernetes 1.25. Your RBAC role still needs permission to update the pods/ephemeralcontainers subresource.

What is the difference between stern and kubectl logs?

kubectl logs reads from a named pod or a limited label selection. stern follows every matching pod and container, picks up new pods as they start and colour-codes the output.

Are eBPF tools like Kubeshark safe in production?

They run privileged agents on nodes and can capture sensitive data. Use them only with approval, scoped to the namespaces you need, and for short captures.

Does Popeye fix problems automatically?

No. Popeye only reports issues and scores namespaces. You fix the findings yourself, usually through manifests or Helm values.

Can I use k9s in read-only mode?

Yes. k9s supports a read-only setting in its configuration, which disables commands that change resources. It is a sensible default for production contexts.

How is this list different from a list of kubectl commands?

This list covers add-on tools and plugins. For built-in commands such as describe, logs, get events and top, read the companion post on Kubernetes troubleshooting commands.

Official references

What's Your Reaction?

Like Like 0
Dislike Dislike 0
Love Love 0
Funny Funny 0
Angry Angry 0
Sad Sad 0
Wow Wow 0
Mridul I am a passionate technology enthusiast with a strong focus on DevOps, Cloud Computing, and Cybersecurity. Through my blogs at DevOps Training Institute, I aim to simplify complex concepts and share practical insights for learners and professionals. My goal is to empower readers with knowledge, hands-on tips, and industry best practices to stay ahead in the ever-evolving world of DevOps.