allenjoey/debug-pod repository overview

⁠debug-pod

A lightweight Alpine-based Kubernetes debug container pre-loaded with common network and system troubleshooting tools. Built for quick kubectl exec diagnostics inside a cluster — including air-gapped environments where you can't just apt install on the fly.

⁠Included tools

• Network: curl, wget, dig, nslookup, nmap, nc (netcat), tcpdump, ping, netstat
• Data/inspection: jq, openssl, strace, htop

⁠Quick start

Run standalone with Docker:

docker run --rm -it \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  allenjoey/debug-pod:latest

NET_ADMIN and NET_RAW are needed for tcpdump and ping to work — the container runs as root for the same reason.

⁠Running in Kubernetes

Deploy as a one-shot debug pod in your cluster:

apiVersion: v1
kind: Namespace
metadata:
  name: debug-pod
---
apiVersion: v1
kind: Pod
metadata:
  name: debug-pod
  namespace: debug-pod
spec:
  restartPolicy: Never
  containers:
  - name: debugger
    image: allenjoey/debug-pod:latest
    command: ["/bin/bash"]
    args: ["-c", "sleep infinity"]
    securityContext:
      runAsNonRoot: false          # Root required for tcpdump / strace / ping
      allowPrivilegeEscalation: false
      capabilities:
        add:
          - NET_ADMIN              # ip, traffic shaping
          - NET_RAW                # ping, tcpdump raw sockets
    resources:
      requests:
        memory: "64Mi"
        cpu: "100m"
      limits:
        memory: "256Mi"
        cpu: "500m"

Then shell in:

kubectl apply -f debug-pod.yml
kubectl exec -it debug-pod -n debug-pod -- /bin/bash

⁠What you get on exec

The entrypoint prints a banner showing the tool list and drops a few helper aliases/functions into the shell:

• ll - List files with details
• watch - Run command periodically
• jcurl - Curl + JSON pretty print
• tcpcheck - Test TCP connectivity
• dnsinfo - Show DNS configuration
• netinfo - Show network connections and routing

⁠Notes

• Designed to be pulled once and cached (imagePullPolicy: IfNotPresent) for use in air-gapped or restricted clusters.
• restartPolicy: Never — this is a one-shot interactive tool, not a long-running service.
• The image defaults to a sleep 7200 command (2-hour self-terminating window). The Kubernetes example above overrides this with sleep infinity so the pod stays up until you delete it manually — swap that for sleep 7200 (or omit the override entirely) if you'd rather it clean itself up automatically.
• Vulnerability-scanned with Trivy⁠ as part of the build pipeline (HIGH/CRITICAL gate, unfixed CVEs excluded).