What Is Kubectl Port-Forward and How Does It Work?

Kubectl Port-ForwardKubernetes is the popular container orchestration platform for deploying and managing the containerized applications. When we deploy a containerized application to the Kubernetes cluster, it runs inside the Pod. By default, Pods are not exposed to public internet. If you want to make the applications running inside the Pod accessible outside the Kubernetes cluster, you are required to create the Service object.

However, there are many scenarios where you might not want to expose the application to the world using the Service for security reasons. For instance, when you want to test the application or do some debugging locally. This is where “kubectl port-forward” stands out.

The “kubectl port-forward” command permits you to forward the traffic from the local computer to Pod housing the containerized applications so that you can easily interact with the application and troubleshoot the issues.

In this article, we’ll know how to use “kubectl port-forward” to forward network traffic from the local computer to Pod running the “nginx” web server. So, let’s get started!

What Is Kubectl-Port-Forward and Why Do We Use It in Kubernetes?

kubectl port-forward is the command that allows you to create secure tunnel between the local computer and the Pod running in the Kubernetes cluster. This permits you to access the applications running in the Pod as it were running locally on the computer.

By using “kubectl port-forward”, you can easily access resources inside the Pod, making it convenient and useful for debugging, testing, as well as accessing the internal resources that are not yet exposed to the outside world.

How Does Kubernetes Port Forwarding Work?

Here’s how Kubernetes port forwarding works:

1. Command execution: You can execute the “kubectl port-forward” command, specifying the target Pod, target port, and local port.

2. Network connection set up: The network connection is set up between the local computer and the target Pod with the help of  Kubernetes API server.

3. Forward network traffic: Once the network connection is established, request that are made from the local computer is forwarded to the target Pod. Similarly, responses from the application running inside the Pod is forwarded back to the local computer. This permits you to interact with the applications and troubleshoot any error that may arise.

Kubectl Port-Forward Syntax

The syntax of the “kubectl port-forward” command is as follows:



Let’s break down the different components of this command:

  • kubectl: This is the command-line tool used to interact with Kubernetes clusters.
  • port-forward: This is the action that we want to perform with “kubectl”.
  • POD_NAME: This is the name of the Pod that we want to forward traffic to and from.
  • LOCAL_PORT: This is the port number on the local machine that we want to use to establish the connection.
  • REMOTE_POD_PORT: This is the port number on the Pod that we want to connect to.

Set up Port Forwarding With Kubectl

In the example below, we will walk through the process of setting up port forwarding in just two simple steps.

Step 1: Create a Deployment

Open a terminal window and run the following command to create an “nginx” deployment in your cluster. Nginx is a popular open source web server.

kubectl create deployment mynginx --image=nginx

Here, “mynginx” is the name of the deployment. You can choose any name you like for your deployment. And “–image=nginx” is the name of the Docker image (in this case, “nginx”) used to create the container that will run in the Pod you’ll be connecting to.

After executing the command, you should see an output similar to this:

kubectl create deployment mynginx

Next, verify that the deployment has been created successfully using the “kubectl get deployments” command.

kubectl get deployments

We can see that the deployment named “mynginx” has been deployed successfully and is now running. Now, let’s make sure that the Pod created by the deployment is running too. To check this, run the following command:

kubectl get pods

This command will give you info about all the Pods that are currently running in your cluster, including their names, status, and other useful details. Look for the Pod with a name starting with “mynginx” and ensure that it’s in the “Running” state.

The output below shows that the “mynginx-ff886775c-zdrfc” Pod is running successfully. Note that the name of your Pod will be different from ours. That’s because Kubernetes creates a Pod name by adding unique characters to the deployment name.

kubectl get pods

Step 2: Forward a Local Port to a Port on the Pod

Now that we have our “nginx” web server up and running inside a Pod, we need to figure out a way to access it from our local machine.

Replace the <INSERT_POD_NAME> part in the command below with your Pod’s name, then run it to create a route between your local computer and the Pod:

kubectl port-forward <INSERT_POD_NAME> 8080:80

After running the command, you’ll see an output similar to the following:

kubectl port-forward

While the terminal session is running, open a web browser and navigate to “http://localhost:8080” to access the “nginx” server running inside the Pod. You should see the default “Welcome to nginx!” page served by the “nginx” web server, indicating that the local request is being forwarded to the Pod.

Congratulations! The port forwarding is working as expected.

Remember that the terminal session where the “kubectl port-forward” command is running must remain open for the port forwarding to continue working. If you close the terminal session, the connection between your local machine and the Pod running the “nginx” web server will be lost, and you won’t be able to access the “nginx” web server anymore. If you want to continue working on the Kubernetes cluster while maintaining the open connection created by the “kubectl port-forward” command, you should open another terminal window and execute your commands on it.

What Is the Difference Between Kubectl Port-Forward and Nodeport?

The kubectl port-forward command lets you forward network traffic from a local port on your computer to a port on a Kubernetes Pod. The idea is to make the application accessible only to you (the “kubectl” user), not the outside world.

It’s also important to understand that kubectl port-forward is typically used for testing and debugging purposes. It’s not a production-ready feature.

NodePort, on the other hand, is a type of Kubernetes Service. It is a way to expose an application to external clients outside of the Kubernetes cluster.

When you create a NodePort Service, Kubernetes opens a port on each worker node in the cluster. These ports can then be used by external clients to access the application.

What Is the Difference Between Kubectl-Proxy and Kubectl Port-Forward?

Kubectl-proxy creates a proxy server between your local computer and the Kubernetes API server. This means that any requests made to the Kubernetes API server by the client are forwarded through the proxy.

The main use case of kubectl proxy is to access the Kubernetes API server.

On the other hand, the kubectl port-forward command creates a tunnel from a local port on your machine to the target port on the Pod. This is especially useful when you want to access a specific Pod directly, like when debugging an application for example.

In summary, kubectl proxy is more suitable for general cluster access, while kubectl port-forward is better for targeting specific Pods.

Note: The Kubernetes API server is a web server that exposes the Kubernetes API, which external clients use to communicate with the cluster. For example, you could use the Kubernetes API to get a list of all running Pods in the cluster.


In this blog post, we learned how to use the “kubectl port-forward” command to forward network traffic from our local computer to a specific Pod in a Kubernetes cluster. We saw how easy it is to set up port forwarding in just a couple of steps and how this can be a valuable tool for local Kubernetes development and testing purposes.

Related Posts