Build Images with BuildKit

Using BuildKit as build tool allows you to build images either locally or inside your Kubernetes cluster without a Docker daemon.

info

In order to use the build kit you'll either need to have docker installed locally or the buildx CLI. If you only want to use the in cluster build functionality, you won't need a running docker daemon and just need the CLI tools.

With buildKit enabled, DevSpace will use docker buildx build for building. If in cluster building is enabled, DevSpace will deploy a BuildKit deployment into the Kubernetes cluster that will function as target BuildKit daemon for docker buildx build. You can also share a single Kubernetes BuildKit daemon across multiple users to share a common build cache.

To set buildKit as default build tool, use the following configuration:

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

In Cluster Building

If the inCluster object is set, DevSpace will build the image directly in the Kubernetes cluster instead of using the local docker daemon. DevSpace will start or reuse a BuildKit deployment in the Kubernetes cluster that acts as target BuildKit daemon. For example:

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

Explanation:

• buildKit tells DevSpace to use the BuildKit engine to build the image.
• buildKit.inCluster tells DevSpace to build the image inside the target Kubernetes cluster instead of using the local docker daemon.
• By default, DevSpace will create a BuildKit daemon deployment inside the target namespace that will be used for this and all future builds.

inCluster.namespace

The option takes a string and defines the namespace where to create the BuildKit deployment in. Defaults to the current DevSpace target namespace.

info

By setting name and namespace you can share a single BuildKit deployment for multiple users. This will have the advantage that a shared build cache is used.

inCluster.name

The option takes a string and defines the name of the BuildKit builder DevSpace will use or create if it does not exist. By default, DevSpace will create a BuildKit builder with the name: devspace-NAMESPACE. For more information about what BuildKit builders are check the docker docs.

inCluster.rootless

The option takes a boolean and defines if the BuildKit deployment should deploy a non priviledged pod. By default, the BuildKit deployment will try to create a priviledged pod.

inCluster.image

The option takes a string and defines the docker image to use for the BuildKit deployment.

inCluster.nodeSelector

The option takes a string in the form of my-label=value,my-label2=value2 that will be used as node selector for the BuildKit deployment.

inCluster.noCreate

The option takes a boolean as value. By default, DevSpace will try to create a new builder if it cannot be found. If this option true, DevSpace will fail if the specified builder cannot be found.

inCluster.noRecreate

The option takes a boolean as value. 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.

inCluster.noLoad

The option takes a boolean as value. If image push is disabled (for example by flag --skip-push or via build.buildKit.skipPush), DevSpace will load the created image into the local docker daemon. If the option is true, DevSpace will not try to do that.

inCluster.createArgs

The option takes a string array as value. These arguments will be appended to the docker buildx create command.

BuildKit options

If buildKit.inCluster is omitted, DevSpace will build the image with the local docker daemon and not interact with the Kubernetes cluster. For example:

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

Explanation:

• buildKit tells DevSpace to use the BuildKit engine to build the image.
• Internally DevSpace will use docker buildx build to build the image.

skipPush

The option takes a boolean as value. If this option is enabled, DevSpace will not push the image to the registry. If in cluster build is enabled, DevSpace will try to load the image into the local docker daemon if the image is not pushed.

tip

DevSpace will automatically skip image pushing if it detects a local docker daemon such as docker-desktop or minikube. You can disable this behaviour by setting the flag --skip-push-local-kube=false

preferMinikube

The option takes a boolean as value. If this option is disabled, DevSpace will not try to use the minikube docker daemon for image building. This option only has an effect, if minikube is installed and the current kube context is minikube.

args

This option takes a string array as value. The arguments will be appended to the docker buildx build call DevSpace will run. For example:

images:
  backend:
    image: john/appbackend
    build:
      buildKit: 
        args: ["--cache-to", "user/app:cache"]

Explanation:

• buildKit tells DevSpace to use the BuildKit engine to build the image.
• The args option will append arguments to the docker buildx build command which will then look something like this: docker buildx build --tag john/appbackend:DRLzYNS --push --file Dockerfile --cache-to user/app:cache -

command

The option takes a string array as value. By default, DevSpace will use docker buildx as base command for interacting with BuildKit, if this option is set, you can tell DevSpace to use a different base command. For example:

images:
  backend:
    image: john/appbackend
    build:
      buildKit: 
        command: ["/path/to/my/buildx"]

Explanation:

• buildKit tells DevSpace to use the BuildKit engine to build the image.
• The command option will tell DevSpace to use this command instead of docker buildx and the actual build command will look like this: /path/to/my/buildx build --tag john/appbackend:DRLzYNS --push --file Dockerfile --cache-to user/app:cache -

Build Options

DevSpace allows you to configure the following build options:

• target defining the build target for multi-stage builds
• network 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

options.target

The target option expects a string stating the build target when using multi-stage builds.

Example: Defining a Build Target for Docker

images:
  backend:
    image: john/appbackend
    build:
      docker:
        options:
          target: production

Explanation:
The image backend would be built using docker and the target production would be used for building the image as defined in the Dockerfile.

options.network

The network option expects a string stating the network setting for building the image.

Example: Defining a Network for Docker

images:
  backend:
    image: john/appbackend
    build:
      docker:
        options:
          network: host

Explanation:
The image backend would be built using docker and docker build would be called using the --network=host flag.

options.buildArgs

The buildArgs option expects a map of buildArgs representing values for the --build-arg flag used for docker or kaniko build commands.

Example: Defining Build Args for Docker

images:
  backend:
    image: john/appbackend
    build:
      docker:
        options:
          buildArgs:
            arg1: arg-value-2
            arg2: arg-value-2

Explanation:
The image backend would be built using docker and docker build would be called using the --build-arg arg1=arg-value-1 --build-arg arg2=arg-value-2 flags.