kflow

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

cargo install kflow
kflow install
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.

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:

1. On the node, check that conntrack is present and readable: sudo head -n 20 /proc/net/nf_conntrack (or your distro's path).
2. 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.
3. 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).
4. 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.