kubectl port-forward: Kubernetes Port Forwarding Guide

February 25, 2020


The kubectl port-forward  command allows you to access internal Kubernetes cluster processes within your local network. This method helps troubleshoot issues and set up services locally without exposing them.

Kubectl is the principal command-line tool for managing Kubernetes clusters. The tool is essential for deploying applications, administering cluster resources, and building complex frameworks.

This concise tutorial shows you how to use kubectl port-forward to connect to a Kubernetes cluster resource.

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


  • A Kubernetes cluster.
  • A fully configured kubectl command-line tool.

How Does Kubernetes Port Forwarding Work?

Kubernetes port forwarding is a way to access internal cluster resources from outside the cluster. Users can map an external port to a port used by a resource such as a pod, deployment, replica set, or service. In this way, the resource becomes accessible from within the local network.

kubectl features a built-in port forwarding functionality. The following is the process of mapping local to cluster ports in Kubernetes:

  1. A user interacts with Kubernetes using the kubectl command-line tool 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 the localhost and the resource running on the cluster.
  4. The user can now directly engage that specific resource to diagnose an issue or debug if necessary.

In some cases, port-forwarding is the only way to access internal cluster resources.

Basic kubectl port-forward Commands

The port-forward command establishes a tunnel from the target resource to your localhost. The command requires you to define the resource type and name alongside local and resource port numbers.

The basic syntax is:

kubectl port-forward [resource-type]/[resource-name] [local-port]:[resource-port]

If several resources match the type/name criteria, a random one is selected by default. To avoid such inconsistencies, define resources as precisely as possible. For example, start exposing a service by listing the services available within a namespace:

kubectl -n [namespace] get svc

The list provides the names of the services in that namespace. Find the service you want to forward and make a note of its name and the service port number.

Listing the services running in the default namespace of the cluster.

kubectl port-forward to Specific Port

Use the following command to access an NGINX deployment within your cluster. For example, if the name of the service is test-nginx-svc, and the port number is 80, use the following command to expose NGINX on the local port 8080.

kubectl port-forward svc/test-nginx-svc 8080:80

The Kubernetes API now listens to port 8080 and forwards data to the service port 80.

Port forwarding of the local port 8080 to the resource port 80.

The service becomes available at localhost:8080.

A web browser window showing the NGINX test page.

Once executed, the kubectl port-forward command actively runs in the terminal window. To issue other commands while port-forwarding is running, open another terminal instance.

Note: Stop port forwarding by pressing Ctrl + C in the original terminal window.

Run kubectl port-forward in Background

Start a background port-forwarding process by adding the & symbol at the end of the command:

kubectl port-forward [resource-name] [local-port]:[resource-port] &
Starting a background port-forwarding process.

Press Ctrl + C after this command to use the command prompt while the port-forwarding process runs in the background.

To stop the background process:

1. Find the process ID (PID) by executing this command:

ps -ef|grep port-forward

2. Note the process ID number (PID) located next to the port-forward process.

Finding the PID of the port-forwarding process.

3. Kill the process by typing:

kill -9 [PID]

Random Local Port

Let Kubernetes choose a random local port to listen to and forward it to port 80 within the specified pod:

kubectl port-forward svc/test-nginx-svc :80

The port Kubernetes selected appears in the command output.

Forwarding from a random local port.

Use Same Local and Resource Ports

Listen and forward data using identical ports both locally and within the specific resource:

kubectl port-forward [resource-name] [port1] [port2]

Listen on Any Local IP Address

Use the following command to listen to the local port on any local address and forward to the resource port:

kubectl port-forward --address [resource-name] [local-port]:[resource-port]
Port forwarding by listening to any local address.

Specify Local IP Address for Port Forwarding

Listen to the local port using the defined IP and forward to the resource port by typing:

kubectl port-forward --address [local-ip-address] [resource-name] [local-port]:[resource-port]
Port forwarding by listening to a specific local address.

Use Deployment to Select port-forward Port

Listen and forward data using the same ports both locally and within the resource. The Deployment defines which pod to use:

kubectl port-forward [deployment-name] [port1] [port2]


You can now use the port-forward command to connect to a resource within your Kubernetes cluster. Port forwarding in a Kubernetes cluster is especially useful for back-end services not intended for remote exposure.

Was this article helpful?
Vladimir Kaplarevic
Vladimir is a resident Tech Writer at phoenixNAP. He has more than 7 years of experience in implementing e-commerce and online payment solutions with various global IT services providers. His articles aim to instill a passion for innovative technologies in others by providing practical advice and using an engaging writing style.
Next you should read
Introduction to Kubernetes Persistent Volumes
January 27, 2020

Persistent Volumes are used in Kubernetes orchestration when you want to preserve the data in the volume even...
Read more
6 Kubernetes Security Best Practices: Secure Your Workloads
January 23, 2020

This article presents basic security principles such as defense-in-depth and restricted privilege...
Read more
Understanding Kubernetes Architecture with Diagrams
November 12, 2019

The article explores Kubernetes Architecture and the concept of Container Deployment. All elements of a...
Read more
How to Install a Kubernetes Cluster on CentOS 7
November 8, 2019

Use Kubernetes to launch and orchestrate your applications efficiently. The steps outlined in this tutorial...
Read more