Kubectl port-forward allows you to access and interact with internal Kubernetes cluster processes from your localhost. You can use this method to investigate issues and adjust your services locally without the need to expose them beforehand.
Kubectl is the principal command-line tool for managing Kubernetes clusters. It is essential for deploying applications, administering cluster resources, and building complex frameworks.
This concise tutorial shows you how to use kubectl to port-forward to a pod in a Kubernetes cluster.
- A Kubernetes cluster
- A fully configured kubectl command-line tool
How Does Kubernetes Port Forwarding Work?
Even though Kubernetes is a highly automated orchestration system, the port forwarding process requires direct and recurrent user input. A connection terminates once the pod instance fails, and it’s necessary to establish a new forwarding by entering the same command manually.
The whole process is simplified by the fact that kubectl already has a built-in port forwarding functionality.
- A user interacts with Kubernetes using the kubectl command-line on their local machine.
port-forwardcommand specifies the cluster resource name and defines the port number to port-forward to.
- As a result, the Kubernetes API server establishes a single HTTP connection between your localhost and the resource running on your cluster.
- The user is now able to engage that specific pod directly, either to diagnose an issue or debug if necessary.
Port forwarding is a work-intensive method. However, in some cases, it is the only way to access internal cluster resources.
Note: Port forwarding is practical only when working with individual pods, and cannot be utilized for services.
Basic kubectl port-forward Commands
port-forward command establishes a tunnel from the target pod to your localhost. The command requires you to define the type or name of the resource as well as local and remote port numbers:
kubectl port-forward TYPE/NAME [options] LOCAL_PORT:REMOTE_PORT
If several pods match the type/name criteria, a random one is selected by default. To avoid such inconsistencies, define a pod as precisely as possible. You can find the exact pod name by manually listing pods within a namespace by typing:
kubectl -n yournamespace get pods
The list provides the names of the pods within that namespace.
kubectl port-forward to a Specific Pod
For instance, the following command would allow you to access a MongoDB deployment within your cluster. The name of the pod is mongo-db-r3pl1ka3, and port number is 5762:
kubectl port-forward pod/mongo-db-r3pl1ka3 8080:5762
The Kubernetes API now listens on local port 8080 and forwards data to port 5762 on the defined pod.
Random Local Port
Listen on a random port locally, and forward to port 5762 within the specified pod:
kubectl port-forward pod/mongo-db-r3pl1ka3 :5762
Corresponding Local and Remote Port
Listen and forward data using identical ports (8080, 5762) both locally and within the specific pod:
kubectl port-forward pod/mongo-db-r3pl1ka3 8080 5762
Random Local IP Address
Listen on port 8080 on any local address, forward to port 5762 in the specified pod:
kubectl port-forward --address 0.0.0.0 pod/mongo-db-r3pl1ka3 8888:5762
Specify Local IP Address for Port Forwarding
Listen on port 8080 on the localhost using the defined IP, forward to port 5762 in the pod:
kubectl port-forward --address localhost,10.153.40.102 pod/mongo-db-r3pl1ka3 8080:5762
Use Deployment to Select port-forward Pod
Listen and forward data using the same ports (8080 5762) both locally and within the pod. The Deployment defines which pod is to be used:
kubectl port-forward deployment/mydeployment 8080 5762
Allow Service to Define port-forward Pod
Listen and forward data using the same ports (8080 5762) both locally and within the pod. The Service selects which pod is to be used:
kubectl port-forward service/myservice 8080 5762
You can now use the
port-forward command to connect to any pod within your Kubernetes cluster. If a single pod starts failing, you are prepared to access that service and correct any issues.
Port forwarding in a Kubernetes cluster is especially useful for back-end services not intended for remote exposure.