Forward Ports In Kubernetes

In Kubernetes, port forwarding is a mechanism that allows access to a specific port of a container running inside a Pod, which is particularly useful for troubleshooting and debugging services that are not exposed externally.

The short answer

To forward a port in Kubernetes, you can use the kubectl port-forward command as follows:

$ kubectl port-forward <resource_type>/<resource_name> <host_port>:<resource_port>

Run in Warp

Where:

• resource_type is a type of Kubernetes resource (e.g., pod, service, deployment).
• resource_name is the name of the resource.
• host_port is the port number on your local machine.
• resource_port is the port number of the resource to which the traffic will be forwarded to.

For example, the following command will forward all the traffic received on the port 3000 of the host to the port 8000 of the Pod named my-pod:

$ kubectl port-forward pod/my-pod 3000:8000
Forwarding from 127.0.0.1:3000 -> 8000
Forwarding from [::1]:3000 -> 8000
Handling connection for 3000

Run in Warp

Note that once launched, you can stop the port forwarding by pressing the CTRL+C key combination.

Easily retrieve this command using Warp’s AI Command Suggestions

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Suggestions feature:

Entering kubectl forward port in the AI Command Suggestions will prompt a kubectl  command that can then quickly be inserted into your shell by doing CMD+ENTER .

Forwarding multiple ports

To forward multiple ports at once, you can use the kubectl port-forward command as follows:

$ kubectl port-forward <resource_type>/<resource_name> <host_port>:<resource_port>[<host_port>:<resource_port> ...]

Run in Warp

Where:

• <host_port>:<resource_port>... is an optional list of host and resource ports pairs.

For example, the following command will respectively map the ports 3000 and 3001 of the host to the ports 8000 and 8001 of the Pod named my-pod:

$ kubectl port-forward pod/my-pod 3000:8000 3001:8001
Forwarding from 127.0.0.1:3000 -> 8000
Forwarding from [::1]:3000 -> 8000
Forwarding from 127.0.0.1:3001 -> 8001
Forwarding from [::1]:3001 -> 8001
Handling connection for 3001

Run in Warp

Listing the active forwarded ports

To get the list of all the forwarded ports in activity, you can use the following ps command:

$ ps -ef | grep "port-forward"

Run in Warp

Where:

• ps -ef lists all the processes running on the system with detailed information, including the process ID, command line arguments, and user.
• grep "port-forward" filters the results to only show lines containing the port-forward expression.

Running port forwarding in the background

By default, the kubectl port-forward command runs in the foreground, thus blocking the use of the terminal until it is manually stopped using CTRL+C or it times out.

To run this command in the background, you can add the & operator at the end of your command as follows:

$ kubectl port-forward <resource_type>/<resource_name><host_port>:<resource_port> &

Run in Warp

Upon execution, the shell will immediately return the control back to you, enabling you to enter more commands or perform other operations in the same terminal session.

For example, the following command will map the port 8000 of the host to the port 80 of the Service named my-service and run it as a background job:

$ kubectl port-forward svc/my-service 8000:80 &
[1] 654
Forwarding from 127.0.0.1:8000 -> 80
Forwarding from [::1]:8000 -> 80

Run in Warp

Stopping the background process

To stop the kubectl port-forward command running in the background, you can first find its process ID using the following ps command:

$ ps aux | grep "kubectl port-forward"

Run in Warp

Where:

• ps aux displays information about all active processes from all users.
• grep "kubectl port-forward" filters the results to only show lines containing the kubectl port-forward expression.

Then kill the process using the kill command as follows:

bash $ kill  <pid>

Run in Warp

Where:

• pid is the process ID of the kubectl port-forward command.

Forwarding ports in a specific namespace

To forward the port(s) of a resource in a specified namespace, you can use the -n flag (short for --namespace) as follows:

$ kubectl port-forward -n  <namespace> <resource_type>/<resource_name> <host_port>:<resource_port> &

Run in Warp

Forwarding ports to a Service

Forwarding ports to Services instead of Pods can be useful for testing service-level features such as load balancing or failover. For example, forwarding a local port to a Service that load balances across multiple Pods can help developers verify the distribution of network traffic without directly having to interact with each Pod.

To forward a port to a specific Service, you can use the following kubectl port-forward command:

$ kubectl port-forward svc/ <service_name><host_port>:<service_port>

Run in Warp

Where:

• svc specifies that the port forwarding is done for a Service.

For example, the following command will map the port 8000 of the host to the port 80 of the Service named my-service:

$ kubectl port-forward svc/my-service 8000:80

Run in Warp

Note that, unlike with Pods, forwarding an invalid Service port will result in the following error:

error: Service my-service does not have a service port 8002

Run in Warp

Forwarding ports for specific IP addresses

By default, the forwarded ports are only accessible from the local machine where the command is executed.

To allows other machine from the network to access these ports, you can use the --address flag as follows:

$ kubectl port-forward --address  <ip_addresses> <resource_type >/<resource_name> <host_port>:<resource_port>

Run in Warp

Where:

• ip_addresses is a list of comma-separated IPv4 or IPv6 addresses.

For example, the following command will forward all the traffic from the port 3000 on the local host and the machine located at 10.19.21.23 to the port 8000 of the Pod named my-pod:

$ kubectl port-forward --address localhost,10.19.21.23 pod/my-pod 3000:8000

Run in Warp

Forwarding ports for all IP addresses

To make the forwarded ports accessible from all the network interfaces of the machine, you can use the 0.0.0.0 IPv4 address or the :: IPv6 address as follows:

$ kubectl port-forward --address 0.0.0.0  <resource_type>/<resource_name> <host_port>:<resource_port>

Run in Warp

Forwarding ports to random host ports

To map a Kubernetes resource port to any random port on the local host, you can use the following syntax:

$ kubectl port-forward<resource_type>/<resource_name>:<resource_port>

Run in Warp

For example, the kubectl command will automatically map the randomly chosen port 38961 on the host to the specified port 80 of the Service named my-service:

$ kubectl port-forward svc/my-service :80
Forwarding from 127.0.0.1:38961 -> 80
Forwarding from [::1]:38961 -> 80

Run in Warp

Understanding port forwarding persistence

By default, Kubernetes will timeout and close all the forwarded ports if the connection between the local machine and the Kubernetes cluster remains idle for a certain period of time.

To change the timeout settings, you can either add the following property to the Kubelet configuration file located at $HOME/.kube/config:

streamingConnectionIdleTimeout:  <timeout>

Run in Warp

Or you can add the following property to the Kubelet service file, typically located at /etc/systemd/system/kubelet.service.d/10-kubeadm.conf:

Environment="KUBELET_SYSTEM_PODS_ARGS=--pod-manifest-path=/etc/kubernetes/manifests --allow-privileged=true --streaming-connection-idle-timeout= <timeout>"

Run in Warp

Where:

• timeout is a duration expressed in the #h#m#s format (e.g., 5m for 5 minutes).

Limitations of the kubectl port-forward command

In Kubernetes, port forwarding has certain limitations:

• Reverse port forward is not supported.
• Port forwarding to ingress resources is not supported.
• UDP is not supported (only TCP).
• Port forwarding at the container-level is not supported (lower is Pod-level).

The difference between kubectl port-forward and kubectl proxy

The kubectl proxy command is used to set up a proxy server between the local host and the Kubernetes API server.

It allows access to Kubernetes resources, such as Services, Pods, and Deployments, through a local HTTP or HTTPS proxy to perform operations like reading logs or querying metrics.