Config Reference

Every project you want to use with DevSpace needs a devspace.yaml which defines how to build, deploy, debug and develop this project.

The devspace.yaml file supports the following fields:

version required string v2beta1
v1beta11
v1beta10
v1beta9
v1beta8
v1beta7
v1beta6
v1beta5
v1beta4
v1beta3
v1beta2
v1beta1

Version holds the config version. DevSpace will always convert older configs to the current latest config version, which makes it possible to use the newest DevSpace version also with older config versions.

name required string

Name specifies the name of the DevSpace project and uniquely identifies a project. DevSpace will not allow multiple active projects with the same name in the same Kubernetes namespace. If not provided, DevSpace will use the name of the current working directory.

imports required object[]

Imports merges specified config files into this one. This is very useful to split up your DevSpace configuration into multiple files and reuse those through git, a remote url or common local path.

enabled required boolean true

Enabled specifies if the given import should be enabled

Source: Local Filesystem

path required string

Path is the local path where DevSpace can find the artifact. This option is mutually exclusive with the git option.

Source: Git Repository

git required string

Git is the remote repository to download the artifact from. You can either use https projects or ssh projects here, but need to make sure git can pull the project. This option is mutually exclusive with the path option.

subPath required string

SubPath is a path within the git repository where the artifact lies in

branch required string

Branch is the git branch to pull

tag required string

Tag is the tag to pull

revision required string

Revision is the git revision to pull

cloneArgs required string[]

CloneArgs are additional arguments that should be supplied to the git CLI

disableShallow required boolean false

DisableShallow can be used to turn off shallow clones as these are the default used by devspace

disablePull required boolean false

DisablePull will disable pulling every time DevSpace is reevaluating this source

functions required <function_name>:string

Functions are POSIX functions that can be used within pipelines. Those functions can also be imported by imports.

pipelines required <pipeline_name>:object

Pipelines are the work blocks that DevSpace should execute when devspace dev, devspace build, devspace deploy or devspace purge is called. Pipelines are defined through a special POSIX script that allows you to use special commands such as create_deployments, start_dev, build_images etc. to signal DevSpace you want to execute a specific functionality. The pipelines dev, build, deploy and purge are special and will override the default functionality of the respective command if defined. All other pipelines can be either run via the devspace run-pipeline command or used within another pipeline through run_pipelines.

<pipeline_name> required string dev
deploy
build
purge
.*

Name of the pipeline, will be filled automatically

run required string

Run is the actual shell command that should be executed during this pipeline

flags required object[]

Flags are extra flags that can be used for running the pipeline via devspace run-pipeline.

name required string

Name is the name of the flag

short required string

Short is optional and is the shorthand name for this flag. E.g. 'g' converts to '-g'

type required string bool bool
int
string
stringArray

Type is the type of the flag. Defaults to bool

default required

Default is the default value for this flag

description required string

Description is the description as shown in devspace run-pipeline my-pipe -h

continueOnError required boolean false

ContinueOnError will not fail the whole job and pipeline if a call within the step fails.

images required <image_name>:object

Images holds configuration of how DevSpace should build images. By default, DevSpace will build all defined images. If you are using a custom pipeline, you can dynamically define which image is built at which time during the execution.

<image_name> required string

Name of the image, will be filled automatically

image required string

Image is the complete image name including registry and repository for example myregistry.com/mynamespace/myimage

tags required string[]

Tags is an array that specifies all tags that should be build during the build process. If this is empty, devspace will generate a random tag

Build Configuration

dockerfile required string ./Dockerfile

Dockerfile specifies a path (relative or absolute) to the dockerfile. Defaults to ./Dockerfile.

context required string ./

Context is the context path to build with. Defaults to the current working directory

buildArgs required <buildArg_name>:string

BuildArgs are the build args that are to the build

target required string

Target is the target that should get used during the build. Only works if the dockerfile supports this

network required string

Network is the network that should get used to build the image

rebuildStrategy required string default default
always
ignoreContextChanges

RebuildStrategy is used to determine when DevSpace should rebuild an image. By default, devspace will rebuild an image if one of the following conditions is true:

• The dockerfile has changed
• The configuration within the devspace.yaml for the image has changed
• A file within the docker context (excluding .dockerignore rules) has changed This option is ignored for custom builds.

In-Memory Overwrites

entrypoint required string[]

Entrypoint specifies an entrypoint that will be appended to the dockerfile during image build in memory. Example: ["sleep", "99999"]

cmd required string[]

Cmd specifies the arguments for the entrypoint that will be appended during build in memory to the dockerfile

appendDockerfileInstructions required string[]

AppendDockerfileInstructions are instructions that will be appended to the Dockerfile that is build at the current build target and are appended before the entrypoint and cmd instructions

Push & Pull

skipPush required boolean false

SkipPush will not push the image to a registry if enabled. Only works if docker or buildkit is chosen as build method

createPullSecret required boolean true

CreatePullSecret specifies if a pull secret should be created for this image in the target namespace. Defaults to true

Build Engines

buildKit required

BuildKit if buildKit is specified, DevSpace will build the image either in-cluster or locally with BuildKit

inCluster required

InCluster if specified, DevSpace will use BuildKit to build the image within the cluster

name required string

Name is the name of the builder to use. If omitted, DevSpace will try to create or reuse a builder in the form devspace-$NAMESPACE

namespace required string

Namespace where to create the builder deployment in. Defaults to the current active namespace.

rootless required boolean false

Rootless if enabled will create a rootless builder deployment.

image required string

Image is the docker image to use for the BuildKit deployment

nodeSelector required string

NodeSelector is the node selector to use for the BuildKit deployment

noCreate required boolean false

NoCreate. By default, DevSpace will try to create a new builder if it cannot be found. If this is true, DevSpace will fail if the specified builder cannot be found.

noRecreate required boolean false

NoRecreate. By default, DevSpace will try to recreate the builder if the builder configuration in the devspace.yaml differs from the actual builder configuration. If this is true, DevSpace will not try to do that.

noLoad required boolean false

NoLoad if enabled, DevSpace will not try to load the built image into the local docker daemon if skip push is defined

createArgs required string[]

CreateArgs are additional args to create the builder with.

preferMinikube required boolean false

PreferMinikube if false, will not try to use the minikube docker daemon to build the image

args required string[]

Args are additional arguments to call docker buildx build with

command required string[]

Command to override the base command to create a builder and build images. Defaults to ["docker", "buildx"]

docker required

Docker if docker is specified, DevSpace will build the image using the local docker daemon

disableFallback required boolean false

DisableFallback allows you to turn off kaniko building if docker isn't installed

preferMinikube required boolean false

PreferMinikube allows you to turn off using the minikube docker daemon if the minikube context is used.

useCli required boolean false

UseCLI specifies if DevSpace should use the docker cli for building

args required string[]

Args are additional arguments to pass to the docker cli

kaniko required

Kaniko if kaniko is specified, DevSpace will build the image in-cluster with kaniko

cache required boolean false

Cache tells DevSpace if a cache repository should be used. defaults to false

snapshotMode required string

SnapshotMode tells DevSpace which snapshot mode kaniko should use. defaults to time

image required string

Image is the image name of the kaniko pod to use

initImage required string

InitImage to override the init image of the kaniko pod

args required string[]

Args for additional arguments that should be passed to kaniko

command required string[]

Command to replace the starting command for the kaniko container

namespace required string

Namespace is the namespace where the kaniko pod should be run

insecure required boolean false

Insecure allows pushing to insecure registries

pullSecret required string

PullSecret is the pull secret to mount by default

skipPullSecretMount required boolean false

SkipPullSecretMount will skip mounting the pull secret

nodeSelector required <nodeSelector_name>:string

NodeSelector is the node selector to use for the kaniko pod

tolerations required object[]

Tolerations is a tolerations list to use for the kaniko pod

Key required string

Operator required string

Value required string

Effect required string

TolerationSeconds required integer

serviceAccount required string

ServiceAccount the service account to use for the kaniko pod

generateName required string

GenerateName is the optional prefix that will be set to the generateName field of the build pod

annotations required <annotation_name>:string

Annotations are extra annotations that will be added to the build pod

labels required <label_name>:string

Labels are extra labels that will be added to the build pod

initEnv required <initEnv_name>:string

InitEnv are extra environment variables that will be added to the build init container

env required <env_name>:string

Env are extra environment variables that will be added to the build kaniko container Will populate the env.value field.

envFrom required <envFrom_name>:object

EnvFrom are extra environment variables from configmap or secret that will be added to the build kaniko container Will populate the env.valueFrom field.

additionalMounts required object[]

AdditionalMounts are additional mounts that will be added to the build pod

secret required

The secret that should be mounted

name required string

Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret +optional

items required object[]

If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. +optional

####### key required string {#images-kaniko-additionalMounts-secret-items-key}

The key to project.

####### path required string {#images-kaniko-additionalMounts-secret-items-path}

The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'.

####### mode required integer {#images-kaniko-additionalMounts-secret-items-mode}

Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. +optional

defaultMode required integer

Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. +optional

configMap required

The configMap that should be mounted

name required string

Name of the configmap +optional

items required object[]

If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. +optional

####### key required string {#images-kaniko-additionalMounts-configMap-items-key}

The key to project.

####### path required string {#images-kaniko-additionalMounts-configMap-items-path}

The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'.

####### mode required integer {#images-kaniko-additionalMounts-configMap-items-mode}

Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. +optional

defaultMode required integer

Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. +optional

readOnly required boolean false

Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. +optional

mountPath required string

Path within the container at which the volume should be mounted. Must not contain ':'.

subPath required string

Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). +optional

resources required

Resources are the resources that should be set on the kaniko pod

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

custom required

Custom if custom is specified, DevSpace will build the image with the help of a custom script.

command required string

Command to execute to build the image. You can use ${runtime.images.my-image.image} and ${runtime.image.my-image.tag} to reference the image and tag that should get built.

onChange required string[]

OnChange will determine when the command should be rerun

deployments required <deployment_name>:object

Deployments holds configuration of how DevSpace should deploy resources to Kubernetes. By default, DevSpace will deploy all defined deployments. If you are using a custom pipeline, you can dynamically define which deployment is deployed at which time during the execution.

<deployment_name> required string

Name of the deployment

helm required

Helm tells DevSpace to deploy this deployment via helm

releaseName required string

ReleaseName of the helm configuration

chart required

Chart holds the chart configuration and where DevSpace can find the chart

Source: Helm Repository

name required string

Name is the name of the helm chart to deploy. Can also be a local path or an oci url

version required string

Version is the version of the helm chart to deploy

repo required string

RepoURL is the url of the repo to deploy the chart from

username required string

Username is the username to authenticate to the chart repo. When using an OCI chart, used for registry auth

password required string

Password is the password to authenticate to the chart repo, When using an OCI chart, used for registry auth

Source: Local Filesystem

path required string

Path is the local path where DevSpace can find the artifact. This option is mutually exclusive with the git option.

Source: Git Repository

git required string

Git is the remote repository to download the artifact from. You can either use https projects or ssh projects here, but need to make sure git can pull the project. This option is mutually exclusive with the path option.

subPath required string

SubPath is a path within the git repository where the artifact lies in

branch required string

Branch is the git branch to pull

tag required string

Tag is the tag to pull

revision required string

Revision is the git revision to pull

cloneArgs required string[]

CloneArgs are additional arguments that should be supplied to the git CLI

disableShallow required boolean false

DisableShallow can be used to turn off shallow clones as these are the default used by devspace

disablePull required boolean false

DisablePull will disable pulling every time DevSpace is reevaluating this source

values required object

Values are additional values that should get passed to deploying this chart

valuesFiles required string[]

ValuesFiles are additional files that hold values for deploying this chart

displayOutput required boolean false

DisplayOutput allows you to display the helm output to the console

upgradeArgs required string[]

UpgradeArgs are additional arguments to pass to helm upgrade

templateArgs required string[]

TemplateArgs are additional arguments to pass to helm template

disableDependencyUpdate required boolean false

DisableDependencyUpdate disables helm dependencies update, default to false

kubectl required

Kubectl tells DevSpace to deploy this deployment via kubectl or kustomize

manifests required string[]

Manifests is a list of files or folders that will be deployed by DevSpace using kubectl or kustomize

applyArgs required string[]

ApplyArgs are extra arguments for kubectl apply

createArgs required string[]

CreateArgs are extra arguments for kubectl create which will be run before kubectl apply

kubectlBinaryPath required string

KubectlBinaryPath is the optional path where to find the kubectl binary

inlineManifest required string

InlineManifests is a block containing the manifest to deploy

Kustomize

kustomize required boolean false

Kustomize can be used to enable kustomize instead of kubectl

kustomizeArgs required string[]

KustomizeArgs are extra arguments for kustomize build which will be run before kubectl apply

kustomizeBinaryPath required string

KustomizeBinaryPath is the optional path where to find the kustomize binary

patches required object[]

Patches are additional changes to the pod spec that should be applied

target required

Target describes where to apply a config patch

apiVersion required string

ApiVersion is the Kubernetes api of the target resource

kind required string

Kind is the kind of the target resource (eg: Deployment, Service ...)

name required string

Name is the name of the target resource

op required string

Operation is the path operation to do. Can be either replace, add or remove

path required string

Path is the config path to apply the patch to

value required

Value is the value to use for this patch.

updateImageTags required boolean true

UpdateImageTags lets you define if DevSpace should update the tags of the images defined in the images section with their most recent built tag.

namespace required string

Namespace where to deploy this deployment

dev required <dev_name>:object

Dev holds development configuration. Each dev configuration targets a single pod and enables certain dev services on that pod or even rewrites it if certain changes are requested, such as adding an environment variable or changing the entrypoint. Dev allows you to:

• sync local folders to the Kubernetes pod
• port forward remote ports to your local computer
• forward local ports into the Kubernetes pod
• configure an ssh tunnel to the Kubernetes pod
• proxy local commands to the container
• restart the container on file changes

<dev_name> required string

Name of the dev configuration

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 You can completely disable this using the initialSync: disabled option.

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

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

persistenceOptions required

PersistenceOptions are additional options for persisting paths within this pod

size required string

Size is the size of the created persistent volume in Kubernetes size notation like 5Gi

storageClassName required string

StorageClassName is the storage type DevSpace should use for this persistent volume

accessModes required string[]

AccessModes are the access modes DevSpace should use for the persistent volume

readOnly required boolean false

ReadOnly specifies if the volume should be read only

name required string

Name is the name of the PVC that should be created. If a PVC with that name already exists, DevSpace will use that PVC instead of creating one.

patches required object[]

Patches are additional changes to the pod spec that should be applied

op required string

Operation is the path operation to do. Can be either replace, add or remove

path required string

Path is the config path to apply the patch to

value required

Value is the value to use for this patch.

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.

ports required object[]

Ports defines port mappings from the remote pod that should be forwarded to your local computer

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

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

command required string

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

args required string[]

Args are arguments to pass to the command

failOnError required boolean false

FailOnError specifies if the sync should fail if the command fails

local required boolean false

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

once required boolean false

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[]

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

Requests are the requests part of the resources

limits required <limit_name>:string

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.

Background Dev Workflows

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

open required object[]

Open defines urls that should be opened as soon as they are reachable

url required string

URL is the url to open in the browser after it is available

vars required <var_name>:object

Vars are config variables that can be used inside other config sections to replace certain values dynamically

<var_name> required string

Name is the name of the variable

Static Value

value required string|integer|boolean

Value is a shortcut for using source: none and default: my-value

Value From Input (Question)

question required string

Question can be used to define a custom question if the variable was not yet used

default required string|integer|boolean

Default is the default value the variable should have if not set by the user

options required string[]

Options are options that can be selected when the variable question is asked

password required boolean false

Password signals that this variable should not be visible if entered

validationPattern required string

ValidationPattern can be used to verify the user input

validationMessage required string

ValidationMessage can be used to tell the user the format of the variable value

noCache required boolean false

NoCache can be used to prompt the user on every run for this variable

Value From Command

command required string

Command is the command how to retrieve the variable. If args is omitted, command is parsed as a shell command.

args required string[]

Args are optional args that will be used for the command

commands required object[]

Commands are additional commands that can be used to run a different command on a different operating system.

os required string

OperatingSystem is optional and defines the operating system this command should be executed on

command required string

Command is the command to use to retrieve the value for this variable. If no args are specified the command is run within a pseudo shell.

args required string[]

Args are optional arguments for the command

alwaysResolve required boolean false

AlwaysResolve makes sure this variable will always be resolved and not only if it is used somewhere. Defaults to false.

source required string all all
env
input
command
none

Source defines where the variable should be taken from

commands required <command_name>:object

Commands are custom commands that can be executed via 'devspace run COMMAND'. These commands are run within a pseudo bash that also allows executing special commands such as run_watch or is_equal.

<command_name> required string

Name is the name of a command that is used via devspace run NAME

section required string

Section can be used to group similar commands together in devspace list commands

command required string

Command is the command that should be executed. For example: 'echo 123'

args required string[]

Args are optional and if defined, command is not executed within a shell and rather directly.

appendArgs required boolean false

AppendArgs will append arguments passed to the DevSpace command automatically to the specified command.

description required string

Description describes what the command is doing and can be seen in devspace list commands

internal required boolean false

Internal commands are not show in list and are usable through run_command

after required string

After is executed after the command was run. It is executed also when the command was interrupted which will set the env variable COMMAND_INTERRUPT to true as well as when the command errored which will set the error string to COMMAND_ERROR.

dependencies required <dependency_name>:object

Dependencies are sub devspace projects that lie in a local folder or remote git repository that can be executed from within the pipeline. In contrast to imports, these projects pose as separate fully functional DevSpace projects that typically lie including source code in a different folder and can be used to compose a full microservice application that will be deployed by DevSpace. Each dependency name can only be used once and if you want to use the same project multiple times, make sure to use a different name for each of those instances.

<dependency_name> required string

Name is used internally

disabled required boolean false

Disabled excludes this dependency from variable resolution and pipeline runs

Source: Local Filesystem

path required string

Path is the local path where DevSpace can find the artifact. This option is mutually exclusive with the git option.

Source: Git Repository

git required string

Git is the remote repository to download the artifact from. You can either use https projects or ssh projects here, but need to make sure git can pull the project. This option is mutually exclusive with the path option.

subPath required string

SubPath is a path within the git repository where the artifact lies in

branch required string

Branch is the git branch to pull

tag required string

Tag is the tag to pull

revision required string

Revision is the git revision to pull

cloneArgs required string[]

CloneArgs are additional arguments that should be supplied to the git CLI

disableShallow required boolean false

DisableShallow can be used to turn off shallow clones as these are the default used by devspace

disablePull required boolean false

DisablePull will disable pulling every time DevSpace is reevaluating this source

Execution

pipeline required string deploy

Pipeline is the pipeline to deploy by default. Defaults to 'deploy'

vars required <var_name>:string

Vars are variables that should be passed to the dependency

overwriteVars required boolean false

OverwriteVars specifies if DevSpace should pass the parent variables to the dependency

ignoreDependencies required boolean false

IgnoreDependencies defines if dependencies of the dependency should be excluded

namespace required string

Namespace specifies the namespace this dependency should be deployed to

pullSecrets required <pullSecret_name>:object

PullSecrets are image pull secrets that will be created by devspace in the target namespace during devspace dev or devspace deploy. DevSpace will merge all defined pull secrets into a single one or the one specified.

<pullSecret_name> required string

Name is the pull secret name to deploy

registry required string

The registry to create the image pull secret for. Empty string == docker hub e.g. gcr.io

username required string

The username of the registry. If this is empty, devspace will try to receive the auth data from the local docker

password required string

The password to use for the registry. If this is empty, devspace will try to receive the auth data from the local docker

email required string

The optional email to use

secret required string

The secret to create

serviceAccounts required string[]

The service account to add the secret to

require required

Require defines what DevSpace, plugins and command versions are required to use this config and if a condition is not fulfilled, DevSpace will fail.

devspace required string

DevSpace specifies the DevSpace version constraint that is needed to use this config

commands required object[]

Commands specifies an array of commands that need to be installed locally to use this config

name required string

Name is the name of the command that should be installed

versionArgs required string[]

VersionArgs are the arguments to retrieve the version of the command

versionRegEx required string

VersionRegEx is the regex that is used to parse the version

version required string

Version constraint of the command that should be installed

plugins required object[]

Plugins specifies an array of plugins that need to be installed locally

name required string

Name of the plugin that should be installed

version required string

Version constraint of the plugin that should be installed

hooks required object[]

Hooks are actions that are executed at certain points within the pipeline. Hooks are ordered and are executed in the order they are specified. They are deprecated and pipelines should be used instead.

name required string

Name is the name of the hook

disabled required boolean false

Disabled can be used to disable the hook

events required string[]

Events are the events when the hook should be executed

command required string

Command is the base command that is either executed locally or in a remote container. Command is mutually exclusive with other hook actions. In the case this is defined together with where.container, DevSpace will until the target container is running and only then execute the command. If the container does not start in time, DevSpace will fail.

args required string[]

Args are additional arguments passed together with the command to execute.

os required string

If an operating system is defined, the hook will only be executed for the given os. All supported golang OS types are supported and multiple can be combined with ','.

upload required

If Upload is specified, DevSpace will upload certain local files or folders into a remote container.

localPath required string

LocalPath to sync files from

containerPath required string

ContainerPath to sync files to

download required

Same as Upload, but with this option DevSpace will download files or folders from a remote container.

localPath required string

LocalPath to sync files from

containerPath required string

ContainerPath to sync files to

logs required

If logs is defined will print the logs of the target container. This is useful for containers that should finish like init containers or job pods. Otherwise this hook will never terminate.

tailLines required integer

If set, the number of lines from the end of the logs to show. If not specified, logs are shown from the creation of the container

wait required

If wait is defined the hook will wait until the matched pod or container is running or is terminated with a certain exit code.

running required boolean false

If running is true, will wait until the matched containers are running. Can be used together with terminatedWithCode.

terminatedWithCode required integer

If terminatedWithCode is not nil, will wait until the matched containers are terminated with the given exit code. If the container has exited with a different exit code, the hook will fail. Can be used together with running.

timeout required integer

The amount of seconds to wait until the hook will fail. Defaults to 150 seconds.

background required boolean false

If true, the hook will be executed in the background.

silent required boolean false

If true, the hook will not output anything to the standard out of DevSpace except for the case when the hook fails, where DevSpace will show the error including the captured output streams of the hook.

container required

Container specifies where the hook should be run. If this is omitted DevSpace expects a local command hook.

labelSelector required <labelSelector_name>:string

LabelSelector to select a container

pod required string

Pod name to use

namespace required string

Namespace to use

imageSelector required string

ImageSelector to select a container

containerName required string

ContainerName to use

wait required boolean false

Wait can be used to disable waiting

timeout required integer 150

Timeout is how long to wait (in seconds) for the container to start. Default is 150 seconds.

once required boolean false

Once only executes an hook once in the container until it is restarted

localRegistry required

LocalRegistry specifies the configuration for a local image registry

enabled required boolean false

Enabled enables the local registry for pushing images. When unset the local registry will be used as a fallback if there are no push permissions for the registry. When true the local registry will always be used. When false the local registry will never be used.

localbuild required boolean false

LocalBuild enables use of local docker builder instead of building in the cluster

namespace required string

Namespace where the local registry is deployed. Default is the current context's namespace

name required string

Name of the deployment and service of the local registry. Default is registry

image required string

Image of the local registry. Default is registry:2.8.1

buildKitImage required string

BuildKitImage of the buildkit sidecar. Default is moby/buildkit:master-rootless

port required integer

Port that the registry image listens on. Default is 5000

persistence required

Persistence settings for the local registry

enabled required boolean false

Enable enables persistence for the local registry

size required string

Size of the persistent volume for local docker registry storage. Default is 5Gi

storageClassName required string

StorageClassName of the persistent volume. Default is your cluster's configured default storage class