How It Works
Understand the internal pipeline that kftray uses to forward traffic reliably.
How It Works
kftray's goal is to provide reliable, managed port forwarding for Kubernetes, ideally using sensible defaults that require minimal configuration.
The Forwarding Pipeline
Every port forward goes through four phases:
Configure — You define a target service, ports, and protocol in JSON (or through the GUI). Configuration is stored in a local SQLite database.
Connect — kftray authenticates with the Kubernetes API using your kubeconfig credentials and establishes a port-forward stream to the target pod or service.
Forward — Local traffic on your chosen port flows through the Kubernetes API to the cluster service. For UDP, an in-cluster proxy handles protocol conversion.
Reconnect — kftray monitors connection health. When pods restart, nodes cycle, or networks hiccup, it automatically re-establishes the forward with exponential backoff.
TCP Forwarding
For TCP services, kftray works similarly to kubectl port-forward but adds automatic reconnection and multi-forward management:
The key difference from kubectl: when that pod restarts, kftray detects the drop and reconnects to the replacement pod automatically.
UDP Forwarding
Kubernetes doesn't support UDP port forwarding natively, so kftray uses a proxy architecture:
kftray deploys a lightweight kftray-server pod in your cluster that acts as a UDP-to-TCP bridge. This adds one network hop but enables access to services like DNS, DHCP, and UDP-based message queues.
See Proxy Forwarding for deployment details and configuration.
Shared State Model
Both the desktop and terminal interfaces share the same SQLite database at ~/.kftray/kftray.db. This means:
- Configurations created in one interface appear instantly in the other.
- Runtime status (which forwards are active) is visible in both.
- However, a forward started in one interface must be stopped from that same interface — each manages its own process lifecycle.
Core Components
| Component | Role |
|---|---|
| kftray-portforward | Core forwarding logic, Kubernetes API integration, reconnection |
| kftray-tauri | Desktop GUI (Tauri framework), system tray, HTTP log viewer |
| kftui | Terminal interface, keyboard-driven management |
| kftray-server | In-cluster proxy for UDP forwarding and proxy workloads |
| kftray-commons | Shared config models, SQLite database access, utilities |
| kftray-helper | Privileged operations (hostfile edits, low-port binding) |
| kftray-http-logs | HTTP traffic interception and logging |
For a deeper architectural dive, see Architecture.