Configure Image Building
Images are configured within the images
section of the devspace.yaml
.
images: # DevSpace will build these images in parallel and push them to the respective registries
{image-a}: ... # tells DevSpace how to build image-a
{image-b}: ... # tells DevSpace how to build image-b
{image-c}: ... # tells DevSpace how to build image-c
...
To speed up the build process, the images you specify under
images
will all be built in parallel (unless you use the--build-sequential
flag).
Image Definition
The images
section in devspace.yaml
is map with keys representing the name of the image and values representing the image definition including tag
, dockerfile
etc.
images: # map[string]struct | Images to be built and pushed
image1: # string | Name of the image
image: dscr.io/username/image # string | Image repository and name
tag: v0.0.1 # string | Tagging schema
dockerfile: ./Dockerfile # string | Relative path to the Dockerfile used for building (Default: ./Dockerfile)
context: ./ # string | Relative path to the context used for building (Default: ./)
createPullSecret: true # bool | Create a pull secret containing your Docker credentials (Default: false)
build: ... # struct | Build options for this image
image2: ...
images[*].image
The image
option expects a string containing the image repository including registry and image name.
- Make sure you authenticate with the image registry before using in here.
- For Docker Hub images, do not specify a registry hostname and use just the image name instead (e.g.
mysql
,my-docker-username/image
).
Example: Multiple Images
images:
backend:
image: john/appbackend
frontend:
image: dscr.io/${DEVSPACE_USERNAME}/appfrontend
Explanation:
- The first image
backend
would be tagged asappbackend:[TAG]
pushed to Docker Hub using the pathjohn
(which generally could be your Docker Hub username). - The second image
frontend
would be tagged asappfrontend:[TAG]
and pushed todscr.io
using the path${DEVSPACE_USERNAME}
which is a dynamic config variable that resolves to your username in DevSpace Cloud.
See
images[*].tag
Tagging Schema for details on how the image[TAG]
would be set in this case.
images[*].tag
Tagging Schema
The tag
option expects a string containing a custom tagging schema used to automatically tag images before pushing them to the registry. The tagging schema can contain dynamic config variables. While you can define your own config variables, DevSpace provides a set of pre-defined variables. The most commonly used variables for tagging are:
- DEVSPACE_RANDOM: A random 6 character long string
- DEVSPACE_TIMESTAMP A unix timestamp when the config was loaded
- DEVSPACE_GIT_COMMIT: A short hash of the local repos current git commit
- DEVSPACE_USERNAME: The username currently logged into devspace cloud
See also: How does DevSpace replace tags in my deployments?
Make sure tags are unique when defining a custom tagging schema. Unique tags ensure that when your application gets started with the newly built image instead of using an older, cached version.
Therefore, it is highly recommended to either use
DEVSPACE_RANDOM
orDEVSPACE_TIMESTAMP
as a suffix in your tagging schema (see example below).
tag
Default Value For tag: ${DEVSPACE_RANDOM}
Example: Custom Tagging Schema
images:
backend:
image: john/appbackend
tag: dev-${DEVSPACE_USERNAME}-backend-${DEVSPACE_GIT_COMMIT}-${DEVSPACE_RANDOM}
Explanation:
The above example would generate tags such as dev-john-backend-b6caf8a-Jak9i
which would result from concatenating the following substrings:
dev-
static stringjohn
DevSpace Cloud username-backend-
static stringb6caf8a
latest git commit hash on current local branch-
static stringJak9i
auto-generated random string
images[*].dockerfile
The dockerfile
option expects a string with a path to a Dockerfile
.
- The path in
dockerfile
should be relative to thedevspace.yaml
. - When setting the
dockerfile
option it is often useful to set thecontext
option as well. - To share your configuration with team mates, make sure
devspace.yaml
and allDockerfiles
used in theimages
section are checked into your code repository.
dockerfile
Default Value For dockerfile: ./Dockerfile
Example: Different Dockerfiles
images:
backend:
image: john/appbackend
frontend:
image: dscr.io/${DEVSPACE_USERNAME}/appfrontend
dockerfile: frontend/Dockerfile
context: frontend/
Explanation:
- The first image would be built using the Dockerfile in
./Dockerfile
and the context path./
. - The second image would be built using the Dockerfile in
./frontend/Dockerfile
and the context path./frontend/
. - Switching the
context
for imagefrontend
would assure that a statement likeADD file.txt
orCOPY file.txt .
in./frontend/Dockerfile
would use the local file./frontend/file.txt
instead of./file.txt
. - In this example, it would probably be useful to have a
./.dockerignore
file which ignores thefrontend/
folder when building the first image calledbackend
.
See Best Practices for Image Building for details on how to optimize your Dockerfiles and use
.dockerignore
for faster image building.
images[*].context
The context
option expects a string with a path to the folder used as context path when building the image. The context path serves as root directory for Dockerfile statements like ADD or COPY.a
See: What does "context" mean in terms of image building?
context
Default Value For context: ./
Example
See "Example: Different Dockerfiles"
ENTRYPOINT
& CMD
Overriding images[*].entrypoint
The entrypoint
option expects an array of strings which tells DevSpace to overrides the ENTRYPOINT
defined in the Dockerfile
during the image building process.
Learn more about how overrides are applied during image building.
Overriding
ENTRYPOINT
also works for multi-stage builds.
If you are overriding the
ENTRYPOINT
, it is often useful to also override theCMD
statement. If you want to defineentrypoint: ...
for an image and you do not want theCMD
statement from the Dockerfile, addcmd: []
to the image configuration in yourdevspace.yaml
.
If you are overriding the Dockerfile
ENTRYPOINT
using theentrypoint
option, it only affects the image but not the deployment. If a deployment using this image defines thecommand
option, it will take precedence over the DockerfileENTRYPOINT
as well as over theentrypoint
settings configured indevspace.yaml
.
entrypoint
Default Value For entrypoint: []
Example: Override ENTRYPOINT For Image
images:
backend:
image: john/appbackend
frontend:
image: dscr.io/${DEVSPACE_USERNAME}/appfrontend
entrypoint:
- npm
- run
- dev
Explanation:
- The first image
backend
will be built using the regularENTRYPOINT
(e.g.[npm, start]
) defined by the Dockerfile located in./Dockerfile
- The second image
frontend
will be built using the same Dockerfile but instead of the originalENTRYPOINT
, DevSpace would use the[npm, run, dev]
as value forENTRYPOINT
images[*].cmd
The cmd
option expects an array of strings which tells DevSpace to overrides the CMD
defined in the Dockerfile
during the image building process.
Learn more about how overrides are applied during image building.
Overriding
CMD
also works for multi-stage builds.
CMD
generally defines the arguments forENTRYPOINT
.
If you are overriding the Dockerfile
CMD
using thecmd
option, it only affects the image but not the deployment. If a deployment using this image defines either thecommand
option or theargs
option, it will take precedence over the DockerfileCMD
as well as over thecmd
settings configured indevspace.yaml
.
cmd
Default Value For cmd: []
Example: Override CMD For Image
images:
backend:
image: john/appbackend
frontend:
image: dscr.io/${DEVSPACE_USERNAME}/appfrontend
cmd:
- run
- dev
Explanation:
- The first image
backend
will be built using the regularCMD
(e.g.[start]
) forENTRYPOINT
(e.g.[npm]
) defined by the Dockerfile located in./Dockerfile
- The second image
frontend
will be built using the same Dockerfile but instead of the originalCMD
, DevSpace would use the[run, dev]
as value forCMD
Image Pull Secrets
images[*].createPullSecret
The createPullSecret
option expects a boolean that tells DevSpace if a pull secret should be created for the registry where this image will be pushed to.
- If there are multiple images with the same registry and any of the images will define
createPullSecret: true
, the pull secret will be created no matter if any of the other images using the same registry explicitly definescreatePullSecret: false
. - There is no need to change your Kubernetes manifests, Helm charts or other deployments to reference the pull secret because DevSpace will add the pull secret to the service account which deploys your project. This ensures that the pull secret is automatically considered by Kubernetes altough it is not explicitly referenced by your pods.
- After running
devspace deploy
ordevspace dev
, you should be able to see the auto-generated pull secrets created by DevSpace when you run the commandkubectl get serviceaccount default -o yaml
and take a look at theimagePullSecrets
section of this service account.
createPullSecret
Default Value For createPullSecret: false
Example: Different Dockerfiles
images:
backend:
image: john/appbackend
frontend:
image: dscr.io/${DEVSPACE_USERNAME}/appfrontend
createPullSecret: true
Explanation:
- The first image
backend
will be pushed to Docker Hub and DevSpace will not create a pull secret for Docker Hub becausecreatePullSecret
defaults tofalse
. This makes sense for public images where no login is required to pull the image or where you want to manage the pull secret yourself. - The second image
frontend
will be pushed to dscr.io and DevSpace will create a pull secret for dscr.io, so Kubernetes is able to pull the image from dscr.io.
Build Tools
The build
section defines which build tool DevSpace uses to build the image. The following build tools are currently supported:
docker
for building images using a Docker daemon (default build tool, prefers Docker daemon of local Kubernetes clusters)kaniko
for building images directly inside Kubernetes (fallback fordocker
)custom
for building images with a custom build command (e.g. for using Google Cloud Build)disabled
for disabling image building for this image
images[*].build.docker
See Build Tools for details.
images[*].build.kaniko
See Build Tools for details.
images[*].build.custom
See Build Tools for details.
images[*].build.disabled
See Build Tools for details.
Build Options
The build tools docker
and kaniko
allow you to define an options
section for the following settings:
target
defining the build target for multi-stage buildsnetwork
to define which network to use during building (e.g.docker build --network=host
)buildArgs
to pass arguments to the Dockerfile during the build process
images[*].build.*.options.target
See Build Options for details.
images[*].build.*.options.network
See Build Options for details.
images[*].build.*.options.buildArgs
See Build Options for details.
Useful Commands
DevSpace provides a couple of convenience commands for configuring the images
section in devspace.yaml
.
devspace add image
To tell DevSpace to build an additional image, simply use the devspace add image
command.
devspace add image database --image=dscr.io/username/mysql --dockerfile=./db/Dockerfile --context=./db
This would add a new image called database
to the images
section. The resulting configuration would look similar to this one:
images:
database: # from args[0]
image: dscr.io/username/image # from --image
dockerfile: ./db/Dockerfile # from --dockerfile
context: ./db # from --context
devspace remove image
Instead of manually removing an image from your configuration file, you can simply run:
devspace remove image database
This command would remove the image database
from your devspace.yaml
.