kubectl port-forwardcommand 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.
- 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:
- A user interacts with Kubernetes using the kubectl command-line tool on their local machine.
port-forwardcommand specifies the cluster resource name and defines the port number to port-forward to.
- As a result, the Kubernetes API server establishes a single HTTP connection between the localhost and the resource running on the cluster.
- The user can now directly engage that specific resource to diagnose an issue or debug if necessary.
Basic kubectl port-forward CommandsThe
port-forwardcommand 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:
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 port-forward [resource-type]/[resource-name] [local-port]:[resource-port]
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 -n [namespace] get svc
kubectl port-forward to Specific PortUse 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
The Kubernetes API now listens to port
kubectl port-forward svc/test-nginx-svc 8080:80
8080and forwards data to the service port
80. The service becomes available at
localhost:8080. Once executed, the
kubectl port-forwardcommand 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 + Cin the original terminal window.
Run kubectl port-forward in BackgroundStart a background port-forwarding process by adding the
&symbol at the end of the command:
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:
kubectl port-forward [resource-name] [local-port]:[resource-port] &
2. Note the process ID number (PID) located next to the port-forward process. 3. Kill the process by typing:
ps -ef|grep port-forward
kill -9 [PID]
Random Local PortLet Kubernetes choose a random local port to listen to and forward it to port
80within the specified pod:
The port Kubernetes selected appears in the command output.
kubectl port-forward svc/test-nginx-svc :80
Use Same Local and Resource PortsListen 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 AddressUse 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 ForwardingListen 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 PortListen 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]
ConclusionYou can now use the
port-forwardcommand 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.