---
title: Using port forwarding to access applications in a container
---

# Using port forwarding to access applications in a container {#nodes-containers-port-forwarding}

You can configure port forwarding to pods, which expose services in your cluster to clients outside of the cluster.

## Understanding port forwarding {#nodes-containers-port-forwarding-about_nodes-containers-port-forwarding}

You can use the OpenShift CLI (`oc`) 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.

You can use a command similar to the following to forward one or more local ports to a pod.

```terminal
$ oc port-forward <pod> [<local_port>:]<remote_port> [...[<local_port_n>:]<remote_port_n>]
```

The OpenShift CLI (`oc`) listens on each local port specified by the user, forwarding using the protocol described below.

You can specify ports by 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.

OpenShift Container Platform handles port-forward requests from clients. Upon receiving a request, OpenShift Container Platform upgrades the response and waits for the client to create port-forwarding streams. When OpenShift Container Platform 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 OpenShift Container Platform 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.

## Using port forwarding {#nodes-containers-port-forwarding-using_nodes-containers-port-forwarding}

You can use the OpenShift CLI (`oc`) to port-forward one or more local ports to a pod.

**Procedure**

- Use a command similar to the following to listen on the specified port in a pod:

  ```terminal
  $ 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:

  ```terminal
  $ oc port-forward <pod> 5000 6000
  ```

  ```terminal {title="Example output"}
  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
  ```

  For example, use the following command to listen on port `8888` locally and forward to `5000` in the pod:

  ```terminal
  $ oc port-forward <pod> 8888:5000
  ```

  ```terminal {title="Example output"}
  Forwarding from 127.0.0.1:8888 -> 5000
  Forwarding from [::1]:8888 -> 5000
  ```

  For example, use the following command to listen on a free port locally and forward to `5000` in the pod:

  ```terminal
  $ oc port-forward <pod> :5000
  ```

  ```terminal {title="Example output"}
  Forwarding from 127.0.0.1:42390 -> 5000
  Forwarding from [::1]:42390 -> 5000
  ```

  Alternatively, use the following command to listen on a free port locally and forward to `5000` in the pod:

  ```terminal
  $ oc port-forward <pod> 0:5000
  ```

## Protocol for initiating port forwarding from a client {#nodes-containers-port-forwarding-protocol_nodes-containers-port-forwarding}

A client resource in your cluster can initiate port forwarding to a pod by issuing a request to the Kubernetes API server.

Use a request in the following format:

```terminal
/proxy/nodes/<node_name>/portForward/<namespace>/<pod>
```

where:

`<node_name>`
:   Specifies the FQDN of the node.

`<namespace>`
:   Specifies the namespace of the target pod.

`<pod>`
:   Specifies the name of the target pod.

```terminal {title="Example request"}
/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)**](https://httpwg.org/specs/rfc7540.html).

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.