kubectl port-forward: Kubernetes Port Forwarding Guide

Introduction

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.

Prerequisites

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

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.

The service becomes available at localhost:8080.

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.

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] &

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.

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.

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 0.0.0.0 [resource-name] [local-port]:[resource-port]

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]

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]

Conclusion

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.