Kubernetes Usage¶

DebugBox is Kubernetes-native and optimized for ephemeral debugging workflows.

Practice in a live playground

Work through real debugging scenarios with all three variants (no setup needed): Kubernetes Debugging with DebugBox →

Debug a Running Pod (Most Common)¶

Attach a debugging container to an existing pod:

# Default (balanced variant)
kubectl debug my-pod -it --image=ghcr.io/ibtisam-iq/debugbox

# Specific variant
kubectl debug my-pod -it --image=ghcr.io/ibtisam-iq/debugbox:lite
kubectl debug my-pod -it --image=ghcr.io/ibtisam-iq/debugbox:power

# Production (pinned version)
kubectl debug my-pod -it --image=ghcr.io/ibtisam-iq/debugbox:1.2.0

Shares the pod's network namespace.

Standalone Debugging Pod¶

Create a temporary debugging pod:

kubectl run debug --rm -it \
  --image=ghcr.io/ibtisam-iq/debugbox \
  --restart=Never

Exit with exit or Ctrl+C to delete the pod.

Ready-Made Pod Manifests¶

For declarative kubectl apply -f workflows, pre-made manifests are available for each variant:

Variant	Manifest	Capabilities
lite	lite-debug-pod.yaml	None
balanced	balanced-debug-pod.yaml	`NET_RAW` (for `tcpdump`)
power	power-debug-pod.yaml	`NET_ADMIN`, `NET_RAW`

kubectl apply -f \
  https://raw.githubusercontent.com/ibtisam-iq/debugbox/main/examples/lite-debug-pod.yaml
kubectl wait pod/debug-lite --for=condition=Ready --timeout=60s
kubectl exec -it debug-lite -- ash -l

kubectl apply -f \
  https://raw.githubusercontent.com/ibtisam-iq/debugbox/main/examples/balanced-debug-pod.yaml
kubectl wait pod/debug-balanced --for=condition=Ready --timeout=60s
kubectl exec -it debug-balanced -- bash -l

kubectl apply -f \
  https://raw.githubusercontent.com/ibtisam-iq/debugbox/main/examples/power-debug-pod.yaml
kubectl wait pod/debug-power --for=condition=Ready --timeout=60s
kubectl exec -it debug-power -- bash -l

Power Variant with Capabilities¶

Note: For advanced networking tools (tshark, conntrack, nft, iptables), use a manifest with capabilities:

Apply Pre-Made Manifest (Recommended)¶

kubectl apply -f \
  https://raw.githubusercontent.com/ibtisam-iq/debugbox/main/examples/power-debug-pod.yaml
kubectl wait pod/debug-power --for=condition=Ready --timeout=60s
kubectl exec -it debug-power -- bash -l

Create Manually¶

apiVersion: v1
kind: Pod
metadata:
  name: debug-power
spec:
  containers:
  - name: debugbox
    image: ghcr.io/ibtisam-iq/debugbox:power
    command: ["/bin/bash", "-l"]
    securityContext:
      capabilities:
        add:
        - NET_ADMIN
        - NET_RAW
    tty: true
    stdin: true
  restartPolicy: Never
  terminationGracePeriodSeconds: 0

Delete when done:

kubectl delete pod debug-power

Kubernetes Context Switching¶

DebugBox includes kubectx and kubens (balanced and power variants only):

# Inside the pod
kubectx                   # List contexts
kubectx minikube          # Switch context
kubens                    # List namespaces
kubens kube-system        # Switch namespace
kubectx -c                # Show current context

Note: kubectx/kubens require a kubeconfig to be available inside the pod (e.g., mounted at /root/.kube/config).

Node-Level Debugging¶

Debug the cluster node itself:

kubectl run node-debug --rm -it \
  --image=ghcr.io/ibtisam-iq/debugbox \
  --overrides='{"spec":{"hostNetwork":true}}' \
  --restart=Never

Persistent Sidecar Pattern¶

For long-running debugging alongside your application:

Standard Sidecar¶

apiVersion: v1
kind: Pod
metadata:
  name: app-with-debug
spec:
  containers:
  - name: app
    image: ghcr.io/ibtisam-iq/ibtisam-iq:latest
    ports:
    - containerPort: 8080
  - name: debugbox
    image: ghcr.io/ibtisam-iq/debugbox:1.2.0
    command: ["sleep", "infinity"]
    tty: true
    stdin: true

Power Sidecar with Capabilities¶

apiVersion: v1
kind: Pod
metadata:
  name: app-with-debug-power
spec:
  containers:
  - name: app
    image: ghcr.io/ibtisam-iq/ibtisam-iq:latest
    ports:
    - containerPort: 8080
  - name: debugbox
    image: ghcr.io/ibtisam-iq/debugbox:power
    command: ["sleep", "infinity"]
    tty: true
    stdin: true
    securityContext:
      capabilities:
        add:
        - NET_ADMIN
        - NET_RAW

Access:

kubectl exec -it app-with-debug -c debugbox -- bash -l
kubectl exec -it app-with-debug-power -c debugbox -- bash -l

→ Which variant to use?

Production Best Practices¶

Always pin versions:
```
--image=ghcr.io/ibtisam-iq/debugbox:1.2.0
```
Never use :latest in production manifests.

Delete after use:

kubectl delete pod debug-session
kubectl delete pod debug-power

Prefer ephemeral containers (kubectl debug) over persistent sidecars for minimal impact.
Only add capabilities when needed. Standard kubectl debug doesn't need them.

→ Docker Usage | Real-world Examples | Troubleshooting