kflow — node-local network "top"
kflow is like top for Kubernetes networking.
It finds connections through conntrack on your nodes and identifies point to point connections across those nodes. It is a tool for debugging and diagnostics.
Coming soon: Throughput metrics to rank connections
Installation
Via Krew (kubectl plugin)
kubectl krew install kflow
kubectl kflow install -n monitoring # Deploy DaemonSet
kubectl kflow # Open TUI
Via Homebrew
brew install AlexsJones/kflow/kflow
kflow install -n monitoring
kflow
Via Cargo
cargo install kflow
kflow install # Installs the daemonset
kflow # opens tui
Press h for keybinding information
Privileges
The agent intentionally requires elevated privileges on the node. The DaemonSet mounts the host /proc into each pod, runs the container as root, and requests NET_ADMIN/NET_RAW capabilities so it can read live conntrack state. Applying the provided Kubernetes manifest therefore requires a user with permission to create DaemonSets and hostPath mounts in the target namespace (cluster-admin or equivalent RBAC is usually needed).
Build yourself
Build the CLI and daemon locally with Cargo. The repository contains a multi-stage Dockerfile.daemon and a k8s/daemonset.yaml manifest; the CLI provides install and uninstall subcommands that call kubectl for convenience.
To build and run the CLI (the binary is named kflow):
cargo build --bin kflow
./target/debug/kflow
Installing the Daemonset
Install the DaemonSet into the current cluster context (may require cluster-admin). The installer accepts an optional --conntrack value to override the path the daemon reads from inside the pod:
kflow install -n <namespace>
kflow install --conntrack /proc/net/ip_conntrack -n <namespace>
Remove the DaemonSet:
kflow uninstall -n <namespace>
Notes: some environments (for example kind) may not expose conntrack entries by default or may use a different proc path. If pods show no connections, verify conntrack is present on the node (sudo head -n 20 /proc/net/nf_conntrack) and that the manifest is mounting /proc into /host/proc inside the pod.
Conntrack requirement and path locations
kflow relies on the kernel conntrack table being available on each node so the node-local daemon can read active connections. Many Linux distributions expose conntrack under /proc/net/ but the exact filename and location can vary by kernel/module and distribution.
Common paths you may encounter:
/proc/net/nf_conntrack (modern kernels, common on many distros)/proc/net/ip_conntrack (older kernels or different module naming)/proc/net/nf_conntrack6 (IPv6 conntrack on some systems)
If you run the provided DaemonSet the manifest mounts the host /proc into the pod at /host/proc and sets the default CONNTRACK_PATH to /host/proc/net/nf_conntrack. If you have a different host path, supply a container-visible path to the installer using --conntrack.
Examples:
-
Node exposes the file at /proc/net/nf_conntrack (default):
kflow install -n monitoring
-
Node exposes the file at /proc/net/ip_conntrack (override):
kflow install --conntrack /proc/net/ip_conntrack -n monitoring
-
You mounted host /proc at a different location inside the pod (advanced):
Edit k8s/daemonset.yaml so the volumeMount and CONNTRACK_PATH agree, or pass the exact path the daemon can see inside the container with --conntrack.
Enable conntrack accounting (bytes)
To see non-zero per-connection byte counters and throughput in kflow, you must enable conntrack accounting on each node. This is a kernel setting and must be configured on the host (we do not change it from inside the pod).
For kind clusters:
# Enable on control-plane
docker exec kind-control-plane sh -c 'echo 1 > /proc/sys/net/netfilter/nf_conntrack_acct'
# Enable on each worker node
docker exec kind-worker sh -c 'echo 1 > /proc/sys/net/netfilter/nf_conntrack_acct'
docker exec kind-worker2 sh -c 'echo 1 > /proc/sys/net/netfilter/nf_conntrack_acct'
# repeat for all workers
For regular nodes:
sudo sh -c 'echo 1 > /proc/sys/net/netfilter/nf_conntrack_acct'
Make it persistent across reboots via sysctl:
echo 'net.netfilter.nf_conntrack_acct=1' | sudo tee /etc/sysctl.d/99-kflow.conf
sudo sysctl --system
Verify bytes are recorded:
On the node:
sudo head -5 /proc/net/nf_conntrack
Or from a kflow pod:
kubectl exec -n <namespace> <kflow-pod> -- head -5 /host/proc/net/nf_conntrack
If bytes= fields are present and increasing (e.g., bytes=1234 packets=10), kflow will compute per-connection throughput automatically. Note: Only NEW connections created after enabling accounting will show byte counters.
Troubleshooting bytes=0:
If you see bytes: 0 and throughput_bytes_per_sec: 0 in kflow even after enabling nf_conntrack_acct:
- Verify accounting is enabled:
cat /proc/sys/net/netfilter/nf_conntrack_acct should return 1
- Check if bytes appear in conntrack output:
sudo cat /proc/net/nf_conntrack | grep bytes
- The setting only affects new connections. Existing connections won't show bytes retroactively. Generate new traffic or wait for connections to be re-established.
- Check daemon logs for sample conntrack lines:
kubectl logs -n <namespace> <pod-name> (with KFLOW_DEBUG=true)
Auto-detect mode
The daemon can attempt to auto-detect the correct conntrack file path if you don't want to pick an exact path.
This is enabled by default.
Use the installer to embed a custom path into the manifest (the installer will translate /proc/... to /host/proc/... when needed):
`kflow install --conntrack <whatever> -n monitoring`
If auto-detection fails the daemon will log a message and fall back to the configured path; using KFLOW_DEBUG will emit helpful debug messages about which candidate paths were tested.
Quick debugging checklist if pods show no connections:
- On the node, check that conntrack is present and readable:
sudo head -n 20 /proc/net/nf_conntrack (or your distro's path).
- Check the pod sees the same file:
kubectl exec -n <ns> <pod> -- ls -l /host/proc/net and kubectl exec -n <ns> <pod> -- head -n 5 /host/proc/net/nf_conntrack.
- If the file is at a different path on the host, use
kflow install --conntrack <path> where <path> is the host's path (our installer translates /proc/... to the mounted /host/proc/... for you).
- Some lightweight clusters (kind, k3s default configurations) may not enable conntrack by default; enable the kernel module or use a cluster that supports conntrack for full visibility.
