Skip to main content
Version: 5.x

Configure Port-Forwarding

Port-forwarding allows you to access your application on localhost:[PORT] by forwarding the network traffic from a localhost port to a specified port of a container.

When starting the development mode, DevSpace starts port-forwarding as configured in the dev.ports section of the devspace.yaml.

images:
  backend:
    image: john/devbackend
  backend-debugger:
    image: john/debugger
deployments:
- name: app-backend
  helm:
    componentChart: true
    values:
      containers:
      - image: john/devbackend
      - image: john/debugger
dev:
  ports:
  - imageSelector: john/devbackend
    forward:
    - port: 8080
      remotePort: 80
Unique Local Port

The port option must be unique across your entire ports section, e.g. you can only use the value 8080 once for the port option in your ports section.

Every port-forwarding configuration consists of two parts:

Configuration​

name​

The name option is optional and expects a string stating the name of this port-forwarding configuration. This can be used as a steady identifier when using profile patches or to override the log message prefix for this port configuration.

For example:

dev:
  ports:
  - name: devbackend
    imageSelector: john/devbackend
    forward:
    - port: 8080
      remotePort: 80
profiles:
- name: production
  patches:
  - op: replace
    path: dev.ports.name=devbackend.imageSelector
    value: john/prodbackend

Pod Selection​

The following config options are needed to determine the pod to which the traffic should be forwarded:

Combine Options

If you specify multiple of these config options, they will be jointly used to select the pod / container (think logical AND / &&).

Auto Reconnect

If DevSpace is unable to establish a port-forwarding connection to the selected pod or loses it after starting the port-forwarding, DevSpace will try to restart port-forwarding several times.

imageSelector​

The imageSelector option expects a string that specifies an image (e.g. my-registry.com/lib/my-image:tag) to select a target pod and container with. The newest running pod that has a container which matches this image will be selected by DevSpace.

In addition, you can also reference images from the images section in the imageSelector with:

  • If the image in imageSelector matches a images.*.image, DevSpace will automatically append the latest built tag during runtime to the imageSelector.
  • You can also let DevSpace resolve the target image and tag by using runtime variables ${runtime.images.IMAGE_NAME}, ${runtime.images.IMAGE_NAME.image} or ${runtime.images.IMAGE_NAME.tag}

For example:

images: 
  app: 
    image: my-registry.com/lib/my-image
dev:
  ...
  # DevSpace will search for the newest pod with a container that
  # uses my-registry.com/lib/other-image:latest
  - imageSelector: my-registry.com/lib/other-image:latest
  # DevSpace will search for the newest pod with a container that
  # uses my-registry.com/lib/my-image:xxxxx (latest built tag by DevSpace)
  - imageSelector: my-registry.com/lib/my-image
  # DevSpace will search for the newest pod with a container that
  # uses my-registry.com/lib/my-image:xxxxx (latest built tag by DevSpace)
  - imageSelector: ${runtime.images.app}
  # DevSpace will search for the newest pod with a container that
  # uses my-registry.com/lib/my-image:custom-tag
  - imageSelector: ${runtime.images.app.image}:custom-tag
  # DevSpace will search for the newest pod with a container that
  # uses my-registry.com/lib/my-image:xxxxx (latest built tag by DevSpace)
  - imageSelector: ${runtime.images.app.image}:${runtime.images.app.tag}
  # DevSpace will search for the newest pod with a container that
  # uses the image of app of dependency dep1 with the latest built tag by DevSpace
  - imageSelector: ${runtime.dependencies.dep1.images.app.image}:${runtime.dependencies.dep1.images.app.tag}

Example: Select Pod by Image Name​

images:
  backend:
    image: john/devbackend
  backend-debugger:
    image: john/debugger
deployments:
- name: app-backend
  helm:
    componentChart: true
    values:
      containers:
      - name: container-0
        image: john/devbackend
      - name: container-1
        image: john/debugger
dev:
  ports:
  - imageSelector: john/devbackend
    forward:
    - port: 8080
      remotePort: 80
  - imageSelector: john/debugger
    forward:
    - port: 3000

Explanation:

  • The above example defines two images that can be used as imageSelector: john/devbackend and john/debugger
  • The deployment starts two containers and each of them uses an image from the images section.
  • The imageName option of the first port-forwarding configuration in the dev.ports section references backend. That means DevSpace would select the first container for port-forwarding, as this container uses the image: john/devbackend which belongs to the backend image as defined in the images section.
  • The imageName option of the second port-forwarding configuration in the dev.ports section references backend-debugger. That means DevSpace would select the second container for port-forwarding, as this container uses the image: john/debugger which belongs to the backend-debugger image as defined in the images section.

In consequence, the following port-forwarding processes would be started when using the above config example:

  • localhost:8080 forwards to container-0:80
  • localhost:3000 forwards to container-1:3000

labelSelector​

The labelSelector option expects a key-value map of strings with Kubernetes labels. This can be used to select the correct target pod with labels instead of the image name like imageSelector or imageName. If the pod you want to select has multiple containers, make sure to use containerName as well.

Example: Select Pod by Label​

images:
  backend:
    image: john/devbackend
  backend-debugger:
    image: john/debugger
deployments:
- name: app-backend
  helm:
    componentChart: true
    values:
      containers:
      - name: container-0
        image: john/devbackend
      - name: container-1
        image: john/debugger
dev:
  ports:
  - labelSelector:
      app.kubernetes.io/name: devspace-app
      app.kubernetes.io/component: app-backend
      custom-label: custom-label-value
    forward:
    - port: 8080
      remotePort: 80

Explanation:

  • The labelSelector would select the pod created for the component deployment app-backend.
  • Because containers in the same pod share the same network stack, we do not need to specify which container should be selected.

namespace​

The namespace option expects a string with a Kubernetes namespace used to select the pod from.

danger

It is generally not needed (nor recommended) to specify the namespace option because, by default, DevSpace uses the default namespace of your current kube-context which is usually the one that has been used to deploy your containers to.

Port Mapping forward​

The forward section defines which localhost port should be forwarded to the remotePort of the selected container.

note

By default, remotePort will take the same value as port if remotePort is not explicitly defined.

port​

The port option is mandatory and expects an integer from the range of user ports [1024 - 49151].

danger

Using a port < 1024 is likely to cause problems as these ports are reserved as system ports.

Example​

See "Example: Select Pod by Image Name"

remotePort​

The remotePort option expects an integer from the range of valid ports [0 - 65535].

info

By default, remotePort has the same value as port if remotePort is not explictly defined.

Example​

See "Example: Select Pod by Image Name"

bindAddress​

The bindAddress option expects a valid IP address that the local port should be bound to.

Default Value For bindAddress​

bindAddress: "localhost" # listen on all network interfaces