Skip to content

Choosing the Right Kubernetes Debugging Container: A Variant-by-Variant Guide

Most Kubernetes debugging images ship as a monolithic package. netshoot is 202 MB. That 202 MB gets pulled whether the task requires dig or tshark. On edge clusters, metered connections, or environments with registry pull rate limits, that bandwidth cost accumulates across teams and incidents.

DebugBox takes a different approach: three variants, each scoped to a specific category of debugging work.

At 50 debug pulls a week, that difference is about 10.1 GB a month on netshoot against 0.75 GB on lite. In a CI pipeline pulling a debug image per test, it is closer to 600 GB a month against 59 GB, a 90 percent reduction. The full scenario breakdown, including pull-time tables at 10, 50, and 100 Mbps and cost at AWS NAT Gateway egress rates, is in Bandwidth Savings Analysis on the docs site.

The Variant Model

Each higher variant includes everything from the lower ones. If a tool is in lite, it is in balanced and power. If a tool is only in power, it is not in balanced.

  • Lite (~15 MB): Network connectivity and data inspection
  • Balanced (~47 MB): Daily Kubernetes troubleshooting (the default)
  • Power (~91 MB): Packet analysis, firewall debugging, and forensics

All three share a common base image (Alpine 3.21, ~4 MB) with CA certificates and a colored shell prompt. All are multi-arch (amd64 and arm64), published to both GHCR and Docker Hub, and Trivy-scanned on every release with a hard-fail on HIGH or CRITICAL findings.

These sizes are not incidental. Every tool's inclusion was tested against its variant's stated purpose in a deliberate removal pass between v1.0.0 and v1.1.0, covered in Why I Removed Tools from My Container Image. The Trivy gating mentioned above, including why it hard-fails instead of just warning, is covered in Building a Multi-Arch Container CI Pipeline with Hard-Fail Security Gates.

Lite: When Pull Speed Matters

Lite covers the most common first-response checks: DNS resolution, HTTP reachability, and JSON or YAML inspection.

Tools: curl, dig, nslookup, host, ip, ping, arping, tracepath, netcat, jq, yq

Shell helpers: json() (pretty-print JSON via jq), yaml() (pretty-print YAML via yq)

How ephemeral containers share network namespaces

kubectl debug with --target shares the network namespace of the named container. DNS, routing, and network interfaces are seen from exactly the same perspective as the running application. Without it, the ephemeral container gets its own isolated namespace and the debug results do not reflect what the application actually sees.

Move to balanced when the task requires packet capture, TLS inspection, system call tracing, or Kubernetes context switching.

Balanced: The Daily Driver

Balanced covers what the majority of debugging sessions actually need.

Tools (in addition to lite): bash, bash-completion, less, vim, git, file, tar, gzip, openssl, tcpdump, socat, mtr, htop, strace, lsof, procps, psmisc, kubectx, kubens

Shell helpers (in addition to lite): ports() (listening sockets), connections() (active TCP connections), routes() (routing table), k8s-info() (current context and namespace), sniff() (tcpdump on all interfaces), sniff-http() (HTTP traffic on ports 80 and 443), sniff-dns() (DNS queries on port 53), cert-check() (TLS certificate chain via openssl)

All helpers are shell functions, not aliases. Functions work correctly in non-interactive shells and when the profile is loaded explicitly, which matters when passing commands directly to kubectl debug or using the profile in init containers.

cert-check accepts hostname and port as separate arguments with a 5-second timeout, so it does not hang on unresponsive endpoints.

Move to power when the task requires protocol-level packet dissection, port scanning, bandwidth measurement, firewall rule inspection, or connection tracking.

Power: When the Task Is Specialized

Power carries tools that most sessions never need but are critical for deep forensics, capacity testing, and firewall debugging.

Tools (in addition to balanced): tshark, ngrep, tcptraceroute, fping, nmap (plus the nmap-nping and nmap-scripts companion packages), iperf3, ethtool, iftop, iptables, nftables, conntrack-tools, ltrace

Shell helper (in addition to balanced): conntrack-watch() (snapshot of the active conntrack table)

Linux capabilities required

tshark, iptables, nftables, and conntrack all need NET_ADMIN or NET_RAW. Ephemeral containers inherit the target pod's security context, which typically does not grant these. Use a standalone debug pod instead.

I ship ready-to-use pod manifests for all three variants under examples/: lite-debug-pod.yaml, balanced-debug-pod.yaml, and power-debug-pod.yaml. The power manifest requests both NET_ADMIN and NET_RAW without enabling privileged mode, which is the minimum needed to run tshark, iptables, and conntrack inside the pod.

Comparison

Lite Balanced Power netshoot Alpine busybox
Compressed size ~15 MB ~47 MB ~91 MB ~202 MB ~7.6 MB ~1.5 MB
DNS tools Yes Yes Yes Yes No No
tcpdump No Yes Yes Yes No No
tshark No No Yes Yes No No
kubectx/kubens No Yes Yes No No No
CVE gated release Yes Yes Yes -- -- --
Multi-arch Yes Yes Yes Yes Yes Yes

Alpine and busybox are smaller, but ship with no debugging tools. Installing packages at runtime requires network access and does not work in air-gapped environments.

netshoot is more comprehensive than power, but at more than double the size. If everything netshoot provides is needed, use netshoot. DebugBox covers the specific subset the task requires.

Quick Reference

Choosing a variant

  1. DNS check, HTTP reachability, or JSON/YAML inspection? Lite.
  2. Packet capture, TLS inspection, system call tracing, or context switching? Balanced.
  3. Protocol dissection, port scanning, firewall debugging, or connection tracking? Power.

When the task is unclear, balanced is the right default. At 47 MB it handles the majority of real-world debugging sessions without the capability requirements that power tools introduce.

Hands-On Tutorial

I published a hands-on tutorial on iximiuz Labs that covers all three variants end-to-end in a live Kubernetes playground, no local cluster required:

Kubernetes Debugging with DebugBox

I walk through DNS checks, HTTP reachability, live packet capture, TLS inspection, system call tracing, protocol dissection with tshark, and connection tracking, each in the context where it actually applies. The tutorial is where the variant model moves from concept to practice.

Series: DebugBox, From Variant Design to Release Pipeline (Part 1 of 4)