Kubernetes • Networking & Access
How to Port-Forward a Kubernetes Pod or Service to Localhost
The `kubectl port-forward` command establishes an encrypted tunnel between your local workstation and a target Pod or Service inside the cluster. It allows developers to test internal microservices, databases (Postgres, Redis), or private APIs locally.
Port-Forward Pod or Service Command
Safe • Read-Only / Non-Destructive
kubectl port-forward svc/my-app 8080:80 -n defaultCustomize:
Namespace:
Resource Name:
Flags & Parameter Breakdown
svc/<service-name>Target service to forward traffic to (or pod/<pod-name>)8080:80<local-port>:<remote-cluster-port>-n <namespace>Kubernetes namespace where service resides--address 0.0.0.0Optional: Listen on all network interfaces instead of localhost onlyStep-by-Step Execution Workflow
1Identify target service and cluster port
Find the service name and its internal targetPort:
kubectl get svc -n default2Initiate the port-forward tunnel
Run the command to bind local port 8080 to cluster port 80:
kubectl port-forward svc/my-service 8080:80 -n default3Test connection in another terminal or browser
Send an HTTP request or open in your browser at http://localhost:8080:
curl http://localhost:8080/healthzCommon Pitfalls & Troubleshooting Advice
- If you get "bind: address already in use", check if another process is using port 8080 (e.g. `lsof -i :8080` or `netstat -ano`).
- Port-forward connections drop automatically if the target pod restarts or during rolling deployments.
Prerequisites & Cluster Access
- Active kubeconfig context connected to the cluster.
- Read/get permissions for pods and services in the target namespace.
Frequently Asked Questions About Port-Forward Pod or Service
Frequently Asked Questions
Frequently Asked Questions
Everything you need to know regarding specifications, syntax, and security best practices.
Yes, running `kubectl port-forward deployment/my-app 8080:80` will automatically route to one of the active replica pods managed by that deployment.
Related Kubernetes & DevOps Recipes
View All RecipesDebug & Inspection
How to Exec into a Kubernetes Pod with an Interactive Bash Shell
execGuide →
Troubleshooting
How to Debug and Fix CrashLoopBackOff Pods in Kubernetes
logsGuide →
Troubleshooting
How to Force Delete a Kubernetes Pod Stuck in Terminating State
deleteGuide →
Deployments & Workloads
How to Restart a Kubernetes Deployment with Zero Downtime
rolloutGuide →
Monitoring & Resources
How to Check CPU and Memory Resource Usage of Pods and Nodes
topGuide →
Config & Secrets
How to Create a Kubernetes Generic Secret from an .env File
createGuide →