Kubernetes is the defacto standard for running production containers and also for developers to use to deploy and manage applications in a cloud-native way. It includes great features, including kubectl port-forward, allowing you to access Kubernetes applications running on a remote server from their local machine. Let’s see how Kubernetes port forward works using the kubectl port-forward command and how to troubleshoot common issues. We’ll also cover specific examples where kubectl port-forwarding is useful.
A three-node Kubernetes cluster running a master and two workers
Table of Contents
How Does Kubernetes Port Forwarding Work?
Kubernetes port forwarding is known as port mapping, or port forwarding is a process that allows developers to access services running in a Kubernetes cluster from their local machine. When you run the kubectl port-forward pod command, the Kubernetes API server establishes a TCP connection between a local port on your machine and a port on a specific pod or service running within the cluster.
The port-forwarding process is a few steps for the configuration process. First, you use the kubectl command line tool to run the port forward command. You specify the name of the resource running in the Kubernetes cluster, such as a pod or service, and the local port you want to use for the connection. Then, the Kubernetes API server establishes a connection between the local port and the specified resource’s port number.
Once the connection is established to a single HTTP connection sent to the specified port on your local machine is forwarded to the specified pod or service within the Kubernetes cluster. This process allows you to quickly access Kubernetes applications running on a remote server without exposing the application to the outside world.
Testing On A Live Kubernetes Cluster
Before diving into specific examples, let’s note how you can easily access a live Kubernetes cluster to test port forwarding. You can set up a cluster on your local machine using tools like Minikube, Microk8s, K3s, or a cloud-based service like Amazon Elastic Kubernetes Service (EKS).
Running a Microk8s cluster in a lab or development environment
To test kubectl port forwarding, you must install kubectl on your local machine. You can download kubectl from the Kubernetes website, and you can verify that it’s installed correctly by running the following command in your terminal:
kubectl version
If kubectl is installed correctly, this command should return information about the kubectl you’re running and the version of the Kubernetes API it’s connected to.
Checking the version of kubectl running on a node
Kubectl port-forward to Specific Port
One of the most common use cases for kubectl port forwarding is to connect to a specific port on a pod running within the Kubernetes cluster. Simply put, port forwarding works in a basic way using the command:
kubectl port-forward <pod_name> <local_port>:<pod_port>
In this command, you’ll replace <pod_name> with the name of the pod that you want to connect to, <local_port> with the port number that you want to use on your local machine, and <pod_port> with the port number that the pod is running on within the Kubernetes cluster.
For example, if you have a pod named “webapp” running on port 8080 within the Kubernetes cluster, and you want to connect to it using port 8000 on your local machine, you would run the following command:
kubectl port-forward webapp 8000:8080
This command would establish a TCP connection between port 8000 on your local machine and port 8080 on the “webapp” pod within the Kubernetes cluster. Any HTTP traffic sent to port 8000 on your local machine would be forwarded to the “webapp” pod running on port 8080 within the cluster.
What is kubectl Port Forwarding?
kubectl port forwarding is a command that allows developers to access services running within a Kubernetes cluster from their local machine. The command establishes a TCP connection between a local port on the developer’s machine and a port on a specific pod Cluster IP service within the cluster.
This feature is handy for debugging applications or accessing resources not exposed to the outside world. With kubectl port forwarding, developers can quickly access Kubernetes applications running on a remote server without exposing the application to the internet.
Port Forwarding on EKS Cluster
Amazon Elastic Kubernetes Service (EKS) is a managed service that makes it easy to run Kubernetes on AWS. If you’re running a Kubernetes cluster on EKS, you can use kubectl port forwarding to access applications running within the Kubernetes clusters configured.
To use kubectl port forwarding on an EKS cluster, you must first configure your local machine to connect to the EKS cluster’s API server. You can do this by running the following command for the EKS kubectl port forward service:
aws eks update-kubeconfig --name <cluster_name>
In this command, you’ll replace <cluster_name> with the name of your EKS cluster. This command will configure kubectl to use the credentials for your AWS account to connect to the EKS cluster’s API server.
Once you’ve configured kubectl to connect to your EKS cluster, you can use the kubectl port-forward command to access applications running within the cluster. For example, if you have a pod name “webapp” running on port 8080 within the EKS cluster, and you want to connect to it using port 8000 on your local machine, you would run the following command:
kubectl port-forward webapp 8000:8080
This command would establish a TCP connection between port 8000 on your local machine and port 8080 on the “webapp” pod within the EKS cluster. Any HTTP traffic sent to port 8000 on your local machine would be forwarded to the “webapp” pod running on port 8080 within the EKS cluster.
Random Local Port
You can use a random local port instead if you don’t want to specify a specific port on your local machine for the port forwarding connection. To do this, you’ll omit the <local_port> parameter when running the kubectl port-forward command:
kubectl port-forward <pod_name> :<pod_port>
When you omit the <local_port> parameter, kubectl will choose a random port on your local machine for the connection. This can be useful to avoid conflicts with other services running on your local machine.
What Port Does kubectl Use?
When you run the kubectl port-forward command, kubectl uses a random port locally on your machine to establish the connection between your device and the pod or service running within the Kubernetes cluster. By default, kubectl will choose a port number between 49152 and 65535.
If you want to specify a specific port range for kubectl to use when establishing port forwarding connections, you can set the –random-port-range parameter when running the kubectl command:
kubectl port-forward <pod_name> <local_port>:<pod_port> --random-port-range=<min_port>:<max_port>
In this command, you’ll replace <min_port> and <max_port> with the minimum and maximum port numbers you want kubectl to use when selecting a random port on your local machine.
Deploy the Node.js Application
Let’s look at a real-world example of using kubectl port forwarding to access a Kubernetes application. Suppose you have a Node.js application running in a Kubernetes cluster, and you want to debug the application by connecting to a specific port on the application from your local machine.
You’ll first need to deploy the Node.js application to the Kubernetes cluster to do this. You can do this using a deployment or a pod. Once the application is deployed, you can use kubectl port forwarding to access it.
Assuming that you have already deployed the Node.js application to the Kubernetes cluster, you can use the following command to forward traffic from port 8000 on your local machine to port 3000 on the pod running the Node.js application:
kubectl port-forward <pod_name> 8000:3000
In this command, you’ll replace <pod_name> with the pod’s name running the Node.js application.
Once you’ve established the port-forwarding connection, you can open your web browser and navigate to http://localhost:8000 to access the Node.js application running in the Kubernetes cluster. Any HTTP traffic sent to port 8000 (local ports) on your local workstation on the local network will forward HTTP traffic to TCP port 3000 on the pod running the Node.js application within the Kubernetes cluster back-end services.
Use the Same Local and Resource Ports
Sometimes, you may want to use the same port number on your local machine and the resource running within the Kubernetes cluster. To do this, you can omit the <local_port> parameter when running the kubectl port-forward commands:
kubectl port-forward <pod_name> <pod_port>:<pod_port>
In this command, you’ll replace <pod_name> with the name of the pod running the resource within the Kubernetes cluster and <pod_port> with the port number the resource runs on within the cluster.
This can be useful to avoid remembering multiple port numbers when accessing the Kubernetes application from your local machine.
Specify Local IP Address for Port Forwarding
By default, kubectl port forwarding binds to all network interfaces on your local machine. However, you may want to specify a specific IP address for the port forwarding connection. To do this, you can use the –address parameter when running the kubectl port-forward command:
kubectl port-forward <pod_name> <local_ip_address>:<local_port>:<pod_port>
In this command, you’ll replace <local_ip_address> with the IP address you want to use for the port forwarding connection. This can be useful if you have multiple network interfaces on your local machine and want to specify a specific interface for the connection.
Wrapping up
Using kubectl port forwarding with Kubernetes is a great way for developers to access their Kubernetes apps running in development clusters from their development workstations. While it isn’t the way you would expose production services for use in serving out business-critical workloads, it is a great way for quick testing and other debugging purposes.
When you run kubectl port-forward configuration in testing, it is a great way to keep things simple during development and easily forward traffic into your Kubernetes cluster, hitting the services you want to expose.
