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 [.inline-code]kubectl port-forward[.inline-code] command as follows:

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

Where:

• [.inline-code]resource_type[.inline-code] is a type of Kubernetes resource (e.g., [.inline-code]pod[.inline-code], [.inline-code]service[.inline-code], [.inline-code]deployment[.inline-code]).
• [.inline-code]resource_name[.inline-code] is the name of the resource.
• [.inline-code]host_port[.inline-code] is the port number on your local machine.
• [.inline-code]resource_port[.inline-code] 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 [.inline-code]3000[.inline-code] of the host to the port [.inline-code]8000[.inline-code] of the Pod named [.inline-code]my-pod[.inline-code]:

$ 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

Note that once launched, you can stop the port forwarding by pressing the [.inline-code]CTRL+C[.inline-code] key combination.

[#easily-recall-syntax-with-ai] Easily retrieve this command using Warp’s AI Command Suggestions [#easily-recall-syntax-with-ai]

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

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

[#forward-multiple-ports] Forwarding multiple ports [#forward-multiple-ports]

To forward multiple ports at once, you can use the [.inline-code]kubectl port-forward[.inline-code] command as follows:

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

Where:

• [.inline-code] <host_port>:<resource_port>...[.inline-code] is an optional list of host and resource ports pairs.

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

$ 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

[#list-forwarded-ports] Listing the active forwarded ports [#list-forwarded-ports]

To get the list of all the forwarded ports in activity, you can use the following [.inline-code]ps[.inline-code] command:

$ ps -ef | grep "port-forward"

Where:

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

[#run-port-forwarding-in-the-background] Running port forwarding in the background [#run-port-forwarding-in-the-background]

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

To run this command in the background, you can add the [.inline-code]&[.inline-code] operator at the end of your command as follows:

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

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 [.inline-code]8000[.inline-code] of the host to the port [.inline-code]80[.inline-code] of the Service named [.inline-code]my-service[.inline-code] 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

[#stop-the-background-process] Stopping the background process [#stop-the-background-process]

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

$ ps aux | grep "kubectl port-forward"

Where:

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

Then kill the process using the [.inline-code]kill[.inline-code] command as follows:

bash $ kill  <pid>

Where:

• [.inline-code]pid[.inline-code] is the process ID of the [.inline-code]kubectl port-forward[.inline-code] command.

[#forward-ports-in-a-namespace] Forwarding ports in a specific namespace [#forward-ports-in-a-namespace]

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

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

[#forward-ports-to-a-service] Forwarding ports to a Service [#forward-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 [.inline-code]kubectl port-forward[.inline-code] command:

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

Where:

• [.inline-code]svc[.inline-code] specifies that the port forwarding is done for a Service.

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

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

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

[#forward-ports-for-specific-ips] Forwarding ports for specific IP addresses [#forward-ports-for-specific-ips]

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 [.inline-code]--address[.inline-code] flag as follows:

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

Where:

• [.inline-code]ip_addresses[.inline-code] is a list of comma-separated IPv4 or IPv6 addresses.

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

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

[#forward-ports-for-all-ips] Forwarding ports for all IP addresses [#forward-ports-for-all-ips]

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

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

[#forward-ports-randomly] Forwarding ports to random host ports [#forward-ports-randomly]

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>

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

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

[#understand-port-forwarding-persistence] Understanding port forwarding persistence [#understand-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 [.inline-code]$HOME/.kube/config[.inline-code]:

streamingConnectionIdleTimeout:  <timeout>

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

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

Where:

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

[#limitations-of-port-forwarding] Limitations of the [.inline-code]kubectl port-forward[.inline-code] command [#limitations-of-port-forwarding]

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

[#differences-between-port-forward-and-proxy] The difference between [.inline-code]kubectl port-forward[.inline-code] and [.inline-code]kubectl proxy[.inline-code] [#differences-between-port-forward-and-proxy]

The [.inline-code]kubectl proxy[.inline-code] 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.