Image Building

DevSpace can build, tag and push images using a variety of build engines.

Do Not Build Images During Development

Because image building can waste a lot of time and slows down developers, we recommend that you only build images when running DevSpace in your CI/CD pipelines using devspace build/deploy but not when a developer runs devspace dev.

Instead of image building, use the following workflow for devspace dev:

1. Deploy your application using prod/stable images
2. Use the devImage feature to swap out the prod/stable images in runtime using a prebuilt dev-optimized image.
3. Use the sync feature for hot reloading your containers

Workflow

To build, tag and push images with DevSpace, you need to:

1. Define your images in the images section of devspace.yaml
2. Call the build_images function inside the pipelines section of devspace.yaml
3. Execute the respective pipeline

1. Define images

Define as many images as need in your devspace.yaml:

images:
  backend:
    dockerfile: ./Dockerfile
  frontend:
    dockerfile: ./frontend/Dockerfile
    context: ./frontend
  other: ...

2. Call build_images in Pipeline

Build All Images

pipelines:
  build:
    run: |
      build_images --all

Build Single Image

pipelines:
  build:
    run: |
      build_images backend

Build Multiple Images

pipelines:
  build:
    run: |
      build_images backend frontend

3. Run Pipeline

Any of the pipelines shown above can be executed via:

• devspace build (shortcut)
• devspace run-pipeline build (long form)

Config Reference

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