kubectl port-forward

When to Use kubectl port-forward

kubectl port-forward creates a network tunnel between your local machine and a resource inside the cluster. It is the standard way to access internal services during development, run database queries against cluster databases, and test services before exposing them externally.

Basic Port Forwarding

The command maps a local port to a port on a cluster resource:

# Forward local 8080 to pod port 80
kubectl port-forward pod/my-pod 8080:80

# Now access the pod at http://localhost:8080
# Press Ctrl+C to stop forwarding

When you specify only one port number, the same port is used locally and remotely:

# Forward port 3000 to local port 3000
kubectl port-forward pod/my-pod 3000

Forwarding to Services and Deployments

Forwarding to a Service is more resilient than forwarding to a specific pod, because the service selects an available pod:

# Forward to a service — survives pod restarts
kubectl port-forward svc/my-api 8080:80

# Forward to a deployment
kubectl port-forward deployment/my-app 8080:80

When forwarding to a service, kubectl selects one of the backing pods. If that pod terminates, the forward breaks and must be restarted. However, the next time you restart, it picks a new healthy pod.

Common Development Workflows

# Access a web application dashboard
kubectl port-forward svc/grafana 3000:3000 -n monitoring
# Open http://localhost:3000

# Connect to a database
kubectl port-forward svc/postgresql 5432:5432 -n databases
# psql -h localhost -U admin -d mydb

# Access Redis
kubectl port-forward svc/redis 6379:6379
# redis-cli -h localhost

# Test an internal API
kubectl port-forward svc/internal-api 9090:8080 -n backend
# curl http://localhost:9090/api/v1/health

# Access Kubernetes dashboard
kubectl port-forward svc/kubernetes-dashboard 8443:443 -n kubernetes-dashboard
# Open https://localhost:8443

Multiple Ports

Forward several ports simultaneously:

# Forward both HTTP and HTTPS ports
kubectl port-forward pod/my-pod 8080:80 8443:443

# Forward application and debug ports
kubectl port-forward pod/my-pod 8080:80 5005:5005
# Access the app at localhost:8080 and attach a debugger to localhost:5005

Background Forwarding

Run port-forward in the background for long sessions:

# Run in background
kubectl port-forward svc/my-api 8080:80 &

# Note the PID for later cleanup
PF_PID=$!

# When done, kill the background process
kill $PF_PID

Listening on All Interfaces

By default, port-forward only listens on localhost. To make it accessible from other machines:

# Listen on all interfaces
kubectl port-forward --address 0.0.0.0 svc/my-api 8080:80

# Listen on a specific IP
kubectl port-forward --address 192.168.1.100 svc/my-api 8080:80

# Listen on both localhost and a specific IP
kubectl port-forward --address localhost,192.168.1.100 svc/my-api 8080:80

Be cautious with 0.0.0.0 as it exposes the tunnel to your entire network.

Reliability and Limitations

Port-forward has several limitations to be aware of:

• Connection drops: The tunnel can break due to network issues, pod restarts, or API server timeouts. It does not automatically reconnect.
• Single connection: The tunnel uses a single TCP connection through the API server. It is not suitable for high-throughput or production traffic.
• No UDP support: Only TCP traffic is forwarded.
• Authentication required: Port-forward requires API server credentials and RBAC permissions.

For development environments, consider wrapping port-forward in a script that reconnects on failure:

# Auto-reconnecting port-forward
while true; do
  kubectl port-forward svc/my-api 8080:80
  echo "Port-forward disconnected, reconnecting in 2s..."
  sleep 2
done

Best Practices

Use port-forward for development and debugging only. For production access, configure proper Ingress resources, LoadBalancer services, or a VPN. Prefer forwarding to services over pods for resilience. Always specify the namespace explicitly. When sharing access with team members, document which port-forward commands are needed to work with the application.