$ oc port-forward <pod> [<local_port>:]<remote_port> [...[<local_port_n>:]<remote_port_n>]
Red Hat OpenShift Service on AWS supports port forwarding to pods.
You can use the CLI to forward one or more local ports to a pod. This allows you to listen on a given or random port locally, and have data forwarded to and from given ports in the pod.
Support for port forwarding is built into the CLI:
$ oc port-forward <pod> [<local_port>:]<remote_port> [...[<local_port_n>:]<remote_port_n>]
The CLI listens on each local port specified by the user, forwarding using the protocol described below.
Ports may be specified using the following formats:
5000
|
The client listens on port 5000 locally and forwards to 5000 in the pod. |
6000:5000
|
The client listens on port 6000 locally and forwards to 5000 in the pod. |
:5000 or 0:5000
|
The client selects a free local port and forwards to 5000 in the pod. |
Red Hat OpenShift Service on AWS handles port-forward requests from clients. Upon receiving a request, Red Hat OpenShift Service on AWS upgrades the response and waits for the client to create port-forwarding streams. When Red Hat OpenShift Service on AWS receives a new stream, it copies data between the stream and the pod’s port.
Architecturally, there are options for forwarding to a pod’s port. The supported Red Hat OpenShift Service on AWS implementation invokes nsenter
directly on the node host
to enter the pod’s network namespace, then invokes socat
to copy data between the stream and the pod’s port. However, a custom implementation could
include running a helper pod that then runs nsenter
and socat
, so that those binaries are not required to be installed on the host.
You can use the CLI to port-forward one or more local ports to a pod.
Use the following command to listen on the specified port in a pod:
$ oc port-forward <pod> [<local_port>:]<remote_port> [...[<local_port_n>:]<remote_port_n>]
For example:
Use the following command to listen on ports 5000
and 6000
locally and forward data to and from ports 5000
and 6000
in the pod:
$ oc port-forward <pod> 5000 6000
Forwarding from 127.0.0.1:5000 -> 5000
Forwarding from [::1]:5000 -> 5000
Forwarding from 127.0.0.1:6000 -> 6000
Forwarding from [::1]:6000 -> 6000
Use the following command to listen on port 8888
locally and forward to 5000
in the pod:
$ oc port-forward <pod> 8888:5000
Forwarding from 127.0.0.1:8888 -> 5000
Forwarding from [::1]:8888 -> 5000
Use the following command to listen on a free port locally and forward to 5000
in the pod:
$ oc port-forward <pod> :5000
Forwarding from 127.0.0.1:42390 -> 5000
Forwarding from [::1]:42390 -> 5000
Or:
$ oc port-forward <pod> 0:5000
Clients initiate port forwarding to a pod by issuing a request to the Kubernetes API server:
/proxy/nodes/<node_name>/portForward/<namespace>/<pod>
In the above URL:
<node_name>
is the FQDN of the node.
<namespace>
is the namespace of the target pod.
<pod>
is the name of the target pod.
For example:
/proxy/nodes/node123.openshift.com/portForward/myns/mypod
After sending a port forward request to the API server, the client upgrades the connection to one that supports multiplexed streams; the current implementation uses Hyptertext Transfer Protocol Version 2 (HTTP/2).
The client creates a stream with the port
header containing the target port in
the pod. All data written to the stream is delivered via the kubelet to the
target pod and port. Similarly, all data sent from the pod for that forwarded
connection is delivered back to the same stream in the client.
The client closes all streams, the upgraded connection, and the underlying connection when it is finished with the port forwarding request.