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 (POD | TYPE/NAME) [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [options]

kubectl port-forward my-pod 8080:80

kubectl port-forward service/my-service 8080

kubectl port-forward deployment/my-deployment 5000:5000 -n my-namespace

POD | TYPE/NAME
    Specifies the target resource. This can be the name of a pod (e.g., my-pod) or a resource type followed by its name (e.g., service/my-service, deployment/my-deployment). When a resource type other than a pod is used, kubectl will automatically select an available pod associated with that resource.

[LOCAL_PORT:]REMOTE_PORT
    Defines the port mapping. LOCAL_PORT is the port on your local machine. If omitted, an available random local port will be chosen. REMOTE_PORT is the port inside the target pod to which traffic will be forwarded. Multiple port mappings can be specified.

-n, --namespace
    Specifies the Kubernetes namespace where the target pod or resource resides.

--address
    Specifies the local IP address(es) to bind to. By default, it binds to 127.0.0.1. Use 0.0.0.0 to bind to all network interfaces. Can be specified multiple times for multiple addresses.

--pod-running-timeout
    The maximum time kubectl will wait for the target pod to be in a running state before attempting to establish the port-forward connection. (e.g., 5s, 2m).

--kubeconfig
    Path to the kubeconfig file to use for authentication and cluster details.

--context
    The name of the kubeconfig context to use for this command.

The `kubectl port-forward` command creates a secure, temporary tunnel between a local port on your machine and a port on a specific pod within a Kubernetes cluster. This utility is invaluable for developers and operators who need to access services running inside a pod for debugging, testing, or local development, without exposing these services externally through Kubernetes Services or Ingresses. It establishes a direct connection, bypassing the cluster's network policies, service mesh, and load balancers, making it ideal for isolated access to individual pod instances. The command listens on a specified local port and forwards all traffic to the corresponding port on the target pod, enabling direct interaction with applications, databases, or other services confined within the cluster network from your workstation.

Ephemeral Connection: The port-forward connection is temporary and active only for the duration the kubectl port-forward command is running. It must be manually restarted if the command exits.
Single Pod Targeting: Even when targeting a resource like a deployment or service, kubectl port-forward will pick one available pod backing that resource. If that specific pod restarts or is rescheduled, the connection will break.
No Load Balancing: This command bypasses Kubernetes Services and their load balancing capabilities. It provides a direct, one-to-one tunnel to a specific pod instance.
Security and RBAC: Users require appropriate Kubernetes Role-Based Access Control (RBAC) permissions to get pods and create port-forward requests (pods/portforward).
Network Policies: While it bypasses Kubernetes Services, internal pod network policies that restrict traffic within the cluster still apply to the forwarded connection.
Local Port Conflicts: If you specify a LOCAL_PORT that is already in use on your machine, the command will fail unless you omit the LOCAL_PORT for automatic assignment.

To run kubectl port-forward in the background and continue using your terminal, append & to the command (e.g., kubectl port-forward my-pod 8080:80 &). To ensure it continues running even if your terminal session is closed, use nohup (e.g., nohup kubectl port-forward my-pod 8080:80 > /dev/null 2>&1 &).

To stop a backgrounded port-forward process, you need to find its process ID (PID) using ps aux | grep 'kubectl port-forward' and then terminate it with kill . Alternatively, if run in the foreground, simply press Ctrl+C.

The kubectl port-forward command is a foundational utility within the Kubernetes command-line interface, kubectl. It was introduced early in Kubernetes' development lifecycle as a crucial tool for debugging and interacting with applications inside the cluster without needing to expose them publicly. While kubectl itself originated from Google's Borg project and was open-sourced as part of Kubernetes in 2014, the port-forward functionality has remained a consistent and stable feature. Its design reflects the need for secure, on-demand, and direct access to individual pod instances, which is essential for developers working on microservices architectures. The core functionality has seen few major changes, emphasizing its stable and vital role in the Kubernetes ecosystem.

kubectl exec(1), kubectl logs(1), kubectl expose(1), ssh(1), netcat(1)