Select Container as Dev Container

To select a container based on the image it is running, specify the imageSelector field.

devspace.yaml

dev:
  backend:
    imageSelector: ghcr.io/org/project/image

Image Tags

If the image you provide as imageSelector is an image that has previously been built by DevSpace, DevSpace will automatically match the most recently built tag. To define a static tag for the selector, add append the tag to the imageSelector value.

Common Scenarios

It is key to make sure that your combination of selectors clearly selects one single container. If there is ambiguity because multiple pod and/or containers could be selected, DevSpace will require that you increase the specificity of your selectors. Here are a few common cases that may require you to combine multiple selectors:

Multiple Containers Use Same Image

If you are using the imageSelector but multiple containers in your namespace run the same image with different arguments or entrypoints (very common for Ruby applications), it will be easier for you to use the labelSelector and optionally specify the container field if needed.

Config Reference

Selector

imageSelector required string

ImageSelector to select a pod

labelSelector required <labelSelector_name>:string

LabelSelector to select a pod

namespace required string

Namespace where to select the pod

container required string

Container is the container name these services should get started.

arch required string

Target Container architecture to use for the devspacehelper (currently amd64 or arm64). Defaults to amd64, but devspace tries to find out the architecture by itself by looking at the node this container runs on.

containers required <container_name>:object

Selector

container required string

Container is the container name these services should get started.

arch required string

Target Container architecture to use for the devspacehelper (currently amd64 or arm64). Defaults to amd64, but devspace tries to find out the architecture by itself by looking at the node this container runs on.

Modifications

devImage required string

DevImage is the image to use for this container and will replace the existing image if necessary.

command required string[]

Command can be used to override the entrypoint of the container

args required string[]

Args can be used to override the args of the container

workingDir required string

WorkingDir can be used to override the working dir of the container

env required object[]

Env can be used to add environment variables to the container. DevSpace will not replace existing environment variables if an environment variable is defined here.

name required string

Name of the environment variable

value required string

Value of the environment variable

resources required

Resources can be used to override the resource definitions of the container

requests required <request_name>:string

Requests are the requests part of the resources

limits required <limit_name>:string

Limits are the limits part of the resources

Port Forwarding

reversePorts required object[]

ReversePorts are port mappings to make local ports available inside the container

port required string

Port is a port mapping that maps the localPort:remotePort. So if you port forward the remote port will be available at the local port. If you do reverse port forwarding, the local port will be available at the remote port in the container. If only port is specified, local and remote port are the same.

bindAddress required string

BindAddress is the address DevSpace should listen on. Optional and defaults to localhost.

File Sync

sync required object[]

Sync allows you to sync certain local paths with paths inside the container

path required string

Path is the path to sync. This can be defined in the form localPath:remotePath. You can also use '.' to specify either the local or remote working directory. This is valid for example: .:.

Exclude Paths From File Sync

excludePaths required string[]

ExcludePaths is an array of file patterns in gitignore format to exclude.

excludeFile required string

ExcludeFile loads the file patterns to exclude from a file.

downloadExcludePaths required string[]

DownloadExcludePaths is an array of file patterns in gitignore format to exclude from downloading

downloadExcludeFile required string

DownloadExcludeFile loads the file patterns to exclude from downloading from a file.

uploadExcludePaths required string[]

UploadExcludePaths is an array of file patterns in gitignore format to exclude from uploading

uploadExcludeFile required string

UploadExcludeFile loads the file patterns to exclude from uploading from a file.

Sync-Triggered Actions

startContainer required boolean false

StartContainer will start the container after initial sync is done. This will inject a devspacehelper into the pod and you need to define dev.*.command for this to work.

onUpload required

OnUpload can be used to execute certain commands on uploading either in the container or locally as well as restart the container after a file changed has happened.

restartContainer required boolean false

If true restart container will try to restart the container after a change has been made. Make sure that images.*.injectRestartHelper is enabled for the container that should be restarted or the devspace-restart-helper script is present in the container root folder.

exec required object[]

Exec will execute the given commands in order after a sync operation

####### name required string {#dev-containers-sync-onUpload-exec-name}

Name is the name to show for this exec in the logs

####### command required string {#dev-containers-sync-onUpload-exec-command}

Command is the command to execute. If no args are specified this is executed within a shell.

####### args required string[] {#dev-containers-sync-onUpload-exec-args}

Args are arguments to pass to the command

####### failOnError required boolean false {#dev-containers-sync-onUpload-exec-failOnError}

FailOnError specifies if the sync should fail if the command fails

####### local required boolean false {#dev-containers-sync-onUpload-exec-local}

Local specifies if the command should be executed locally instead of within the container

####### once required boolean false {#dev-containers-sync-onUpload-exec-once}

Once executes this command only once in the container's life. Can be used to initialize a container before starting it, but after everything was synced.

####### onChange required string[] {#dev-containers-sync-onUpload-exec-onChange}

OnChange is an array of file patterns that trigger this command execution

Initial Sync

initialSync required string

InitialSync defines the initial sync strategy to use when this sync starts. Defaults to mirrorLocal

waitInitialSync required boolean false

WaitInitialSync can be used to tell DevSpace to not wait until the initial sync is done

initialSyncCompareBy required string

InitialSyncCompareBy defines if the sync should only compare by the given type. Either mtime or size are possible

One-Directional Sync

disableDownload required boolean false

DisableDownload will disable downloading completely

disableUpload required boolean false

DisableUpload will disable uploading completely

bandwidthLimits required

BandwidthLimits can be used to limit the amount of bytes that are transferred by DevSpace with this sync configuration

download required integer

Download is the download limit in kilo bytes per second

upload required integer

Upload is the upload limit in kilo bytes per second

polling required boolean false

Polling will tell the remote container to use polling instead of inotify

noWatch required boolean false

NoWatch will terminate the sync after the initial sync is done

file required boolean false

File signals DevSpace that this is a single file that should get synced instead of a whole directory

persistPaths required object[]

PersistPaths allows you to persist certain paths within this container with a persistent volume claim

path required string

Path is the container path that should get persisted. By default, DevSpace will create an init container that will copy over the contents of this folder from the existing image.

volumePath required string

VolumePath is the sub path on the volume that is mounted as persistent volume for this path

readOnly required boolean false

ReadOnly will make the persistent path read only to the user

skipPopulate required boolean false

SkipPopulate will not create an init container to copy over the existing contents if true

initContainer required

InitContainer holds additional options for the persistent path init container

resources required

Resources are the resources used by the persistent path init container

####### requests required <request_name>:string {#dev-containers-persistPaths-initContainer-resources-requests}

Requests are the requests part of the resources

####### limits required <limit_name>:string {#dev-containers-persistPaths-initContainer-resources-limits}

Limits are the limits part of the resources

Foreground Dev Workflows

terminal required

Terminal allows you to tell DevSpace to open a terminal with screen support to this container

command required string

Command is the command that should be executed on terminal start. This command is executed within a shell.

workDir required string

WorkDir is the working directory that is used to execute the command in.

enabled required boolean false

If enabled is true, DevSpace will use the terminal. Can be also used to disable the terminal if set to false. DevSpace makes sure that within a pipeline only one dev configuration can open a terminal at a time and subsequent dev terminals will fail.

disableReplace required boolean false

DisableReplace tells DevSpace to not replace the pod or adjust its settings to make sure the pod is sleeping when opening a terminal

disableScreen required boolean false

DisableScreen will disable screen which is used by DevSpace by default to preserve sessions if connections interrupt or the session is lost.

disableTTY required boolean false

DisableTTY will disable a tty shell for terminal command execution

logs required

Logs allows you to tell DevSpace to stream logs from this container to the console

enabled required boolean false

Enabled can be used to enable printing container logs

lastLines required integer

LastLines is the amount of lines to print of the running container initially

attach required

Attach allows you to tell DevSpace to attach to this container

enabled required boolean false

Enabled can be used to enable attaching to a container

disableReplace required boolean false

DisableReplace prevents DevSpace from actually replacing the pod with modifications so that the pod starts up correctly.

disableTTY required boolean false

DisableTTY is used to tell DevSpace to not use a TTY connection for attaching

ssh required

SSH allows you to create an SSH tunnel to this container

enabled required boolean false

Enabled can be used to enable the ssh server within the container. By default, DevSpace will generate the required keys and create an entry in your ~/.ssh/config for this container that can be used via ssh dev-config-name.dev-project-name.devspace

localHostname required string

LocalHostname is the local ssh host to write to the ~/.ssh/config

localPort required integer

LocalPort is the local port to forward from, if empty will be random

remoteAddress required string

RemoteAddress is the address to listen to inside the container

useInclude required boolean false

UseInclude tells DevSpace to use a the file ~/.ssh/devspace_config for its ssh entries. DevSpace will also create an import for its own entries inside ~/.ssh/config, this is a cleaner way, but unfortunately not all SSH clients support this.

proxyCommands required object[]

ProxyCommands allow you to proxy certain local commands to the container

gitCredentials required boolean false

GitCredentials configures a git credentials helper inside the container that proxies local git credentials

command required string

Command is the name of the command that should be available in the remote container. DevSpace will create a small script for that inside the container that redirect command execution to the local computer.

localCommand required string

LocalCommand can be used to run a different command than specified via the command option. By default, this will be assumed to be the same as command.

skipContainerEnv required boolean false

SkipContainerEnv will not forward the container environment variables to the local command

env required <env_name>:string

Env are extra environment variables to set for the command

restartHelper required

RestartHelper holds restart helper specific configuration. The restart helper is used to delay starting of the container and restarting it and is injected via an annotation in the replaced pod.

path required string

Path defines the path to the restart helper that might be used if certain config options are enabled

inject required boolean false

Inject signals DevSpace to inject the restart helper