Image Building

Images are configured within the images section of the devspace.yaml.

Examples

Docker Hub

images:
  backend:
    image: my-docker-username/appbackend
  database:
    image: my-docker-company/appbackend

Custom Registry

images:
  backend:
    image: image.company.tld/appbackend
  database:
    image: image.company.tld/appbackend

Custom Tagging

images:
  backend:
    image: image.company.tld/appbackend
    tags:
    - latest
    # This will be replaced during build time with
    # something like dev-ads13as1-sA4ve. Each hashtag
    # represents a random character.
    - dev-${devspace.git.commit}-#####  
  database:
    image: image.company.tld/appbackend

BuildKit

images:
  backend:
    image: john/appbackend
    build:
      buildKit:
        inCluster: {}

What is BuildKit?

BuildKit is an open-source concurrent, cache-efficient, and Dockerfile-agnostic builder toolkit that lets you build images inside containers that run on top of Kubernetes or in your local docker daemon. To force image building using BuildKit, set build.buildKit: {}. To tell DevSpace to use in cluster building set build.buildKit.inCluster: {} as shown above. Learn more about configuring BuildKit builds.

kaniko

images:
  backend:
    image: john/appbackend
    build:
      kaniko:
        cache: true

What is kaniko?

Kaniko is an open-source tool that lets you build images inside containers that run on top of Kubernetes. DevSpace uses kaniko as automatic fallback if Docker is not installed. To force image building using kaniko, set build.kaniko.cache: true as shown above. Learn more about configuring kaniko builds.

Build Command

images:
  backend:
    image: john/appbackend
    build:
      custom:
        skipImageArg: true
        command: |-
          # Also works on windows as this is executed in a golang shell
          docker build -t ${runtime.images.backend.image}:${runtime.images.backend.tag} . -f custom/Dockerfile

Disable

images:
  frontend:
    image: john/appfrontend
    build:
      disabled: true
  backend:
    image: john/appbackend

Parallel Image Building

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).

Build Tool Priority

If you specify multiple build tools, DevSpace will try to use them in the following order:

1. disabled
2. custom
3. docker (uses kaniko as fallback if Docker host not reachable)
4. kaniko

Run Image Building

When you run one of the following commands, DevSpace will run the image building process:

• devspace build (only image building without deployment)
• devspace deploy (before deploying the application)
• devspace dev (before deploying the application and starting the development mode)

Important Flags

The following flags are available for all commands that trigger image building:

• --build-sequential build images sequentially instead of in parallel (provides more detailed logs for each image)
• -b / --force-build rebuild all images (even if they could be skipped because context and Dockerfile have not changed since the latest build)

Image Building Process

DevSpace loads the images configuration from devspace.yaml and builds all images in parallel. The multi-threaded, parallel build process of DevSpace speeds up image building drastically, especially when building many images and using remote build methods.

1. Load Dockerfile

DevSpace loads the contents of the Dockerfile specified in image[*].dockerfile (defaults to ./Dockerfile).

Use Relative Paths

Dockerfile paths used in dockerfile should be relative to the devspace.yaml.

2. Override Entrypoint (if needed)

DevSpace allows you to apply an in-memory override of a Dockerfile's ENTRYPOINT by configuring the entrypoint option for the image. Similar to the Dockerfile ENTRYPOINT, the images[*].entrypoint option should be defined as an array.

Useful for Profiles

Configuring ENTRYPOINT overrides can be particularly useful when defining different config profiles in your devspace.yaml.

3. Load Build Context

DevSpace loads the context to build this image as specified in context (defaults to ./). The context path serves as root directory for Dockerfile statements like ADD or COPY.

Use Relative Paths

Context paths used in context should be relative to the devspace.yaml.

What does "context" mean in terms of image building?

The context is archived and sent to the Docker daemon before starting to process the Dockerfile. All references of local files within the Dockerfile are relative to the root directory of the context.

That means that a Dockerfile statement such as COPY ./src /app would copy the folder src/ within the context path into the path /app within the container image. So, if the context would be /my/project/database, for example, the folder that would be copied into /app would have the absolute path /my/project/database/src on your local computer.

4. Skip Build & Push (if possible)

DevSpace tries to speed up image building by skipping images when they have not changed since the last build process. To do this, DevSpace caches the following information after building an image:

• a hash of the Dockerfile used to build the image (including ENTRYPOINT override)
• a hash over all files in the context used to build this image (excluding files in .dockerignore)

The next time you trigger the image building process, DevSpace will generate these hashes again and compare them to the hashes of the last image building process. If all newly generated hashes are equal to the old ones stored during the last image building process, then nothing has changed and DevSpace will skip this image.

Force Build

You can use the -b / --force-build flag to tell DevSpace to build all images even if nothing has changed.

5. Build Image

DevSpace uses one of the following build tools to create an image based on your Dockerfile and the provided context:

• docker for building images using a Docker daemon (default, prefers Docker daemon of local Kubernetes clusters)
• kaniko for building images directly inside Kubernetes (automatic fallback for docker)
• custom for building images with a custom build command (e.g. for using Google Cloud Build)
• disabled if this image should not be built (especially useful for config profiles)

6. Tag Image

DevSpace automatically tags all images after building them using a tagging schema that you can customize using the tag option. By default, this option is configured to generate a random string consisting of 5 characters.

Learn more about defining a custom tagging schema.

Tag Replacement

Before deploying your application, DevSpace will use the newly generated image tags and replace them in-memory in the values for your Helm charts and Kubernetes manifests, so they will be deployed using the newest image tag.

7. Push Image

DevSpace automatically pushes your images to the respective registry that should be specified as part of the image option. Just as with regular Docker images, DevSpace uses Docker Hub if no registry hostname is provided within image.

note

You can skip this step when proving the --skip-push flag. Beware that deploying your application after using --skip-push will only work when your images have already been pushed to the registry or when you are using a local Kubernetes cluster (e.g. minikube).

8. Create Pull Secrets

When deploying your application via DevSpace, Kubernetes needs to be able to pull your images from the registry that is used to store your images when pushing them. For this purpose, Kubernetes relies on so-called image pull secrets. DevSpace can automatically create these secrets for you, if you configure createPullSecret: true for the respective image in your devspace.yaml.

note

You do not need to change anything in your Kubernetes manifests or Helm charts to use the image pull secrets that DevSpace creates because DevSpace adds these secrets to the default service account in the namespace used to deploy your project.

After running devspace build, devspace deploy or devspace dev, you should be able to see the auto-generated pull secrets created by DevSpace when you run the following command:

kubectl get serviceaccount default -o yaml

Take a look at the imagePullSecrets section of the output showing the yaml definition of the service account default.

Advanced Topics

Authentication (Registry)

DevSpace uses the same credential store as Docker. So, if you already have Docker installed and you have logged in to a private registry before, DevSpace will be able to push to this registry. So, if you want to push to a registry using DevSpace, simply authenticate using this command:

docker login            # for Docker Hub
docker login [REGISTRY] # for any other registry (e.g. my-registry.tld)

note

If you do not have Docker installed, DevSpace initializes a Docker credential store for you and stores your login information just like Docker would do it.

Skip Push (Local Clusters)

If you are using a local Kubernetes cluster, DevSpace will try to build the image using the Docker deamon of this local cluster. If this process is successful, DevSpace will skip the step of pushing the image to a registry as it is not required for deploying your application.