quick start

here's when someone might need kftray: when kubectl port-forward becomes annoying due to dropped connections, the need for UDP forwarding, or managing multiple terminal windows for different services.

honest disclaimer: when to skip this

kubectl port-forward works perfectly fine for simple cases. someone doing occasional debugging or working with a single TCP service probably doesn't need the complexity of kftray. the overhead isn't worth it for quick one-off connections.

this becomes useful when managing multiple forwards regularly, dealing with UDP services, or working in teams that need shared configurations.

the basic workflow

both interfaces (kftray desktop and kftui terminal) work with the same JSON configuration format and shared database. the general approach is: create configurations once, enable the forwards needed for current work, and let automatic reconnection handle network hiccups.

configuration format essentials

all port forwards use this JSON structure:

{
  "service": "my-service",
  "namespace": "default",
  "local_port": 8080,
  "remote_port": 80,
  "context": "my-cluster",
  "workload_type": "service",
  "protocol": "tcp",
  "alias": "my-service"
}

the essential fields are service name, namespace, ports, kubernetes context, and protocol. optional fields like alias make configurations easier to manage when working with many services.

getting started with the desktop interface

launch kftray and look for the system tray icon. clicking it opens the main interface where configurations appear in a list format with toggle switches for each forward.

adding a new configuration means clicking the "+" button and filling in the service details: name, namespace, local and remote ports, and protocol (TCP or UDP). saving the configuration adds it to the shared database for both interfaces to use.

starting port forwards works through toggle switches next to each configuration, or "start all" enables multiple forwards simultaneously. the interface shows real-time status for each forward and handles reconnection automatically when pods restart.

getting started with the terminal interface

launch kftui from any terminal to see the text-based interface. the layout shows available configurations in a table format with keyboard shortcuts for common operations.

adding configurations works through JSON file import -- press 'i' to import, select the configuration file, then use space bar to select which configurations to activate. the 'f' key starts or stops selected forwards.

navigation uses standard terminal patterns: arrow keys move between configurations, space bar selects items, ctrl+a selects everything, and ctrl+c quits. the help screen ('h' key) shows all available shortcuts.

verifying that forwards work

test connections by accessing the forwarded service at its local port:

curl http://localhost:8080

for database connections, use the local port with normal database client tools. web applications become accessible at localhost with the configured local port.

when something doesn't work, check that the target service exists and is running in the cluster. use kubectl get services -n <namespace> to verify service names and kubectl get pods -n <namespace> to check that backing pods are healthy.

realistic configuration examples

microservices development setup

someone working on an e-commerce platform might configure forwards for the main services:

{
  "service": "api-gateway",
  "namespace": "development",
  "local_port": 8080,
  "remote_port": 8080,
  "protocol": "tcp",
  "alias": "gateway"
}

{
  "service": "postgres-primary",
  "namespace": "data",
  "local_port": 5432,
  "remote_port": 5432,
  "protocol": "tcp",
  "alias": "database"
}

this setup allows local development code to access both the API gateway and database using standard localhost connections.

debugging production issues

when investigating production problems, someone might forward specific services temporarily:

{
  "service": "user-service",
  "namespace": "production",
  "context": "prod-cluster",
  "local_port": 9001,
  "remote_port": 8080,
  "protocol": "tcp",
  "alias": "prod-users"
}

the different local port (9001) prevents conflicts with development forwards, and the specific context ensures connection to the right cluster.

when forwards don't work

port binding errors happen when another process uses the local port. check what's running with lsof -i :PORT on unix systems and either stop the conflicting process or choose a different local port.

authentication failures usually mean kubernetes credentials are expired or the context doesn't exist. verify with kubectl config get-contexts and kubectl get nodes to test cluster access.

service connectivity problems often indicate the target service isn't running or isn't named correctly. double-check service names and namespaces with kubectl get services -n <namespace>.

what happens next

once basic forwarding works, teams often evolve toward shared configurations through JSON file export or github sync (desktop interface only). http traffic logging (also desktop only) becomes useful for debugging API integration issues.

the next step depends on whether someone wants visual management (desktop interface) or prefers staying in terminals (text interface). both work with the same configurations and handle the same port forwarding scenarios.