netshoot

## netshoot: a Docker + Kubernetes network trouble-shooting swiss-army container

<p align="center">
  <img src="img/netshoot.jpg" alt="netshoot" width="320">
</p>

## Quick Start

```bash
# Share a running container's network namespace
docker run -it --net container:<container_name> nicolaka/netshoot

# Use the host's network namespace
docker run -it --net host nicolaka/netshoot

# Ephemeral debug container in Kubernetes
kubectl debug <pod> -it --image=nicolaka/netshoot

# Prefer a digest in production debug sessions
docker run -it --rm nicolaka/netshoot@sha256:<digest>
```

## Why netshoot

Docker and Kubernetes isolate every container in its own **network namespace** — its own interfaces, routes, and IP stack. netshoot exploits the fact that you can _enter_ any namespace without modifying what's running inside it.

- **Debug a container** without installing tools into its image
- **Debug a host** without installing anything on it
- **Debug in Kubernetes** as an ephemeral container, throwaway pod, or sidecar

## Launch Options

### Docker

```bash
# Enter a specific container's namespace
docker run -it --net container:<container_name> nicolaka/netshoot

# Enter the host's namespace
docker run -it --net host nicolaka/netshoot

# Enter a Docker bridge network's namespace via nsenter
docker run -it --rm \
  -v /var/run/docker/netns:/var/run/docker/netns \
  --privileged \
  nicolaka/netshoot
# then: nsenter --net=/var/run/docker/netns/<id> sh
```

### Docker Compose

See [`configs/netshoot-compose.yaml`](configs/netshoot-compose.yaml) for a Compose file that shares another service's network namespace and writes a pcap:

```bash
docker compose -f configs/netshoot-compose.yaml up
```

### Kubernetes

```bash
# Ephemeral container in a running pod (non-destructive)
kubectl debug <pod> -it --image=nicolaka/netshoot

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

# Throwaway pod on the host's network namespace
kubectl run tmp-shell --rm -i --tty \
  --overrides='{"spec": {"hostNetwork": true}}' \
  --image nicolaka/netshoot

# Sidecar in a Deployment
kubectl apply -f configs/netshoot-sidecar.yaml
kubectl exec -it <pod> -c netshoot -- zsh
```

#### kubectl plugin

The [kubectl-netshoot plugin](https://github.com/nilic/kubectl-netshoot) wraps the above into ergonomic subcommands:

```bash
kubectl netshoot run tmp-shell          # throwaway pod
kubectl netshoot debug my-pod           # ephemeral container
kubectl netshoot debug node/my-node     # node debug session
```

---

## Troubleshooting Scenarios

### DNS resolution failures

_Pod can't reach a service by name, or DNS lookups are slow/timing out._

```bash
# 1. Check what DNS server the container is using
cat /etc/resolv.conf

# 2. Resolve a Kubernetes service name
drill kubernetes.default.svc.cluster.local

# 3. Query the cluster DNS directly (bypass resolv.conf)
drill @10.96.0.10 kubernetes.default.svc.cluster.local

# 4. Capture DNS traffic to see what's actually