port forwarding

kftray handles port forwarding for both TCP and UDP protocols, with automatic reconnection when connections drop. this addresses the main limitations developers hit with kubectl port-forward.

when port forwarding comes up

port forwarding becomes necessary when local development needs access to services running in kubernetes clusters. this happens during feature development, debugging sessions, database access, or integration testing against cluster services.

kubectl port-forward works fine for simple TCP connections, but it has limitations: connections drop when pods restart, UDP services don't work at all, and managing multiple forwards requires multiple terminal windows.

how kftray handles tcp differently

standard TCP port forwarding works similar to kubectl but with automatic reconnection:

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

the main difference is resilience: when a pod restarts or the network hiccups, kftray automatically reconnects to a new pod instance. kubectl requires manual restart of the port-forward command.

this matters especially for long-running development sessions where infrastructure changes (deployments, pod evictions, cluster maintenance) would normally interrupt work.

udp forwarding requires proxy architecture

UDP port forwarding works differently because kubernetes doesn't support UDP forwarding natively:

{
  "service": "dns-service",
  "namespace": "default",
  "local_port": 53,
  "remote_port": 53,
  "context": "my-cluster",
  "workload_type": "service",
  "protocol": "udp",
  "alias": "dns"
}

for UDP services, kftray deploys a small proxy server (kftray-server) in the cluster that acts as a bridge. local UDP traffic goes to this proxy, which forwards it to the target service. this proxy deployment requires cluster permissions and adds a network hop.

automatic reconnection mechanics

kftray monitors port forward health and handles several failure scenarios automatically. when pods restart, the tool detects the connection drop and establishes a new forward to the replacement pod. network interruptions trigger retry logic with exponential backoff.

context switches (when switching between kubernetes clusters) automatically restart forwards against the new cluster. cluster reconnections after laptop sleep or network changes re-establish all active forwards.

this reliability becomes important for developers who don't want to manually restart port forwards throughout the day.

realistic usage patterns

web application development

someone building a web application typically forwards the frontend service and its database:

{
  "service": "frontend",
  "local_port": 3000,
  "remote_port": 80,
  "alias": "web"
}

the local development server can access the frontend at localhost:3000, and the frontend can connect to other cluster services normally.

database access for development

database forwarding enables local development against cluster data:

{
  "service": "postgres",
  "local_port": 5432,
  "remote_port": 5432,
  "alias": "db"
}

local applications connect to localhost:5432 and access the cluster database. this works for development, testing, or debugging against production data.

microservices debugging

when debugging issues across multiple services, someone might forward several components:

{
  "service": "api-gateway",
  "local_port": 8080,
  "remote_port": 8080,
  "alias": "gateway"
}

this allows testing the local service against the full cluster environment, or accessing cluster services from local debugging tools.

configuration considerations

the service field targets kubernetes services by name, which must exist in the specified namespace. the workload_type can be "service" (forwards to any pod behind the service) or "pod" (forwards to a specific pod instance).

services work better for stable connections because kubernetes handles load balancing and pod selection. pod targeting helps for debugging specific instances but breaks when that pod restarts.

the context field determines which kubernetes cluster receives the forward. this must match a context name from kubeconfig.

local and remote ports can differ, allowing multiple environments to use different port schemes while maintaining consistent local development setups.

limitations and considerations

TCP forwarding works reliably for most HTTP, database, and API services. UDP forwarding adds complexity with the proxy requirement and an extra network hop that may affect latency-sensitive applications.

port conflicts happen when multiple configurations use the same local port. kftray detects this during startup and reports binding errors.

network security policies in some corporate environments may restrict the proxy server deployment required for UDP forwarding.

very high-throughput applications may hit bandwidth limits since all traffic routes through the developer's machine. for these cases, direct cluster access or VPN connections might perform better.

troubleshooting common issues

port binding problems

when the local port is already in use, kftray reports a binding error. check what's using the port with lsof -i :PORT on unix systems or netstat -an | findstr PORT on windows. either stop the conflicting process or choose a different local port.

service connectivity issues

if the forward starts but connections fail, verify the target service exists and responds. use kubectl get service SERVICE -n NAMESPACE to check service status and kubectl get pods -n NAMESPACE to verify backing pods are running.

network policies in the cluster might block connections to the target service. test connectivity from within the cluster using a debug pod.

context and authentication problems

forwards fail when kubernetes context doesn't exist or credentials are expired. verify available contexts with kubectl config get-contexts and test cluster access with kubectl get nodes.

for custom kubeconfig files, ensure the path is correct and the file contains valid credentials for the target cluster.

workflow integration

port forwarding fits into the development cycle when local code needs to interact with cluster services. this happens during active development, integration testing, debugging sessions, and database operations.

the tool doesn't replace normal kubernetes development workflows -- developers still deploy code with kubectl, debug with logs, and manage resources through standard tools. port forwarding specifically addresses the "local access to cluster services" use case.

teams often standardize port assignments across configurations to avoid conflicts and simplify documentation. microservices teams might use port ranges (8080-8089 for APIs, 5432-5439 for databases) for consistent local environments.