Usage with Kubernetes

Netshoot is an invaluable tool for debugging complex networking scenarios in Kubernetes.

Ephemeral Container Debugging (Kubernetes v1.23+)

Ephemeral containers are the modern, preferred way to debug a running Pod. This feature allows you to add a temporary container to an existing Pod, sharing its network namespace and other namespaces.

This is ideal because it doesn't require restarting the Pod and lets you inspect the live environment.

Command:

kubectl debug <pod_name> -it --image=nicolaka/netshoot

Example:

If you have a pod named my-app-pod-xyz, you can attach Netshoot to it like this:

kubectl debug my-app-pod-xyz -it --image=nicolaka/netshoot

This will drop you into a shell inside the my-app-pod-xyz's network namespace.

Standalone Debugging Pod

To troubleshoot general cluster networking (like DNS, service connectivity, or network policies) without targeting a specific pod, you can spin up a temporary, throw-away Netshoot pod.

Command:

kubectl run tmp-shell --rm -i --tty --image nicolaka/netshoot

This pod will be created, you'll get a shell, and when you exit, the pod will be automatically deleted.

Debugging on a Node (Host Network)

To troubleshoot node-level networking issues (e.g., CNI plugin problems, node-to-node connectivity), you can run a Netshoot pod directly on the node's host network.

Command:

kubectl run tmp-shell --rm -i --tty --overrides='{"spec": {"hostNetwork": true}}' --image nicolaka/netshoot

This pod will share the network interface, IP, and routing table of the Kubernetes node it's scheduled on.

Using the kubectl-netshoot Plugin

To streamline the process, you can use the community-created Netshoot Kubectl Plugin. This plugin provides simple, high-level commands for common debugging scenarios.

First, install the plugin.

Sample Usage:

  • Spin up a throwaway pod for troubleshooting:

    kubectl netshoot run tmp-shell

  • Debug an existing pod with an ephemeral container:

    kubectl netshoot debug my-existing-pod

  • Create a debug session on a specific node:

    kubectl netshoot debug node/my-node