Introduction

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.

Introductory image with the article title and a stylized Kubernetes logo.

Prerequisites

  • 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.

  1. A user interacts with Kubernetes using the kubectl command-line on their local machine.
  2. The port-forward command specifies the cluster resource name and defines the port number to port-forward to.
  3. As a result, the Kubernetes API server establishes a single HTTP connection between your localhost and the resource running on your cluster.
  4. 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

The 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.

The system has listed all the pods on the defined 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

Conclusion

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.


Next you should also read