kubectl-port-forward

Forward local ports 5000 and 6000 to the pod ports 5000 and 6000

$ kubectl port-forward [[po|pods]]/[pod_name] 5000 6000

$ kubectl port-forward [[po|pods]]/[pod_name] :5000

$ kubectl port-forward [[deploy|deployment]]/[deployment_name] 5000 6000

$ kubectl port-forward [[svc|service]]/[service_name] 8443:https

$ kubectl port-forward [[po|pods]]/[pod_name] 8888:5000 --address 0.0.0.0

$ kubectl port-forward [[po|pods]]/[pod_name] 8888:5000 --address localhost,[10.19.21.23]

kubectl port-forward [<resource-type>/]<name> [<local-port>]:<remote-port> [<local-port>]:<remote-port> ...

--address string
    IP address to bind forwarded ports to. Default: 127.0.0.1 (localhost only). Use 0.0.0.0 to bind all interfaces.

--pod-running-timeout duration
    Maximum time to wait for pod to become ready before failing. Default: 5m0s.

-n, --namespace string
    Namespace of the target resource. Default: current namespace.

-l, --selector string
    Label selector to filter target resources (e.g., app=myapp).

--field-selector string
    Field selector for resources (e.g., status.phase=Running).

-L, --local
    Use pod's network namespace for forwarding (requires running inside cluster).

kubectl port-forward creates a secure tunnel from a local port on your machine to a port on a Kubernetes resource such as a pod, service, deployment, replica set, or stateful set. This enables direct access to applications inside the cluster for development, testing, or debugging without exposing services externally via Ingress or NodePort.

Specify the resource type (optional if unambiguous) and name, followed by one or more port mappings in the format [local-port:]remote-port. If the local port is omitted, it defaults to the remote port. For example, it allows accessing a pod's web server on local port 8080.

The command waits for the target pod to be running (useful for deployments) with a configurable timeout, then binds the local port and proxies traffic bidirectionally until interrupted (Ctrl+C). By default, it binds only to 127.0.0.1 for security, but can be set to 0.0.0.0 for remote access. Ideal for database connections, API testing, or UI interaction in isolated environments.

Supports label selectors to target resources dynamically. Note that for scaled resources like deployments, it forwards to a single ready pod.

Forwards to only one pod for scaled resources; restarts on pod changes. Not suitable for production traffic. Ctrl+C required to stop. Fails if no ready pod matches.

kubectl port-forward pod/mypod 8080:80
Forward pod port 80 to local 8080.

kubectl port-forward svc/mysvc 8080:80 -n prod
Forward service in namespace.

kubectl port-forward deployment/myapp 8080
Forward deployment pod port 8080 to local 8080.

Default localhost binding prevents external access. Use --address=0.0.0.0 cautiously; firewall rules advised.

Introduced in Kubernetes v1.0 (2014) as core kubectl functionality. Evolved with Kubernetes releases; pod-running-timeout added in v1.19 for better deployment handling. Widely used in dev workflows since early adoption.

kubectl(1), kubectl exec(1), kubectl proxy(1), socat(1)