Docker container driver (original) (raw)

The Docker container driver allows creation of a managed and customizable BuildKit environment in a dedicated Docker container.

Using the Docker container driver has a couple of advantages over the default Docker driver. For example:

Run the following command to create a new builder, named container, that uses the Docker container driver:

The following table describes the available driver-specific options that you can pass to --driver-opt:

Parameter Type Default Description
image String Sets the BuildKit image to use for the container.
memory String Sets the amount of memory the container can use.
memory-swap String Sets the memory swap limit for the container.
cpu-quota String Imposes a CPU CFS quota on the container.
cpu-period String Sets the CPU CFS scheduler period for the container.
cpu-shares String Configures CPU shares (relative weight) of the container.
cpuset-cpus String Limits the set of CPU cores the container can use.
cpuset-mems String Limits the set of CPU memory nodes the container can use.
default-load Boolean false Automatically load images to the Docker Engine image store.
network String Sets the network mode for the container.
cgroup-parent String /docker/buildx Sets the cgroup parent of the container if Docker is using the "cgroupfs" driver.
restart-policy String unless-stopped Sets the container'srestart policy.
env. String Sets the environment variable key to the specified value in the container.

Before you configure the resource limits for the container, read aboutconfiguring runtime resource constraints for containers.

When you run a build, Buildx pulls the specified image (by default,moby/buildkit). When the container has started, Buildx submits the build submitted to the containerized build server.

The docker-container driver supports cache persistence, as it stores all the BuildKit state and related cache into a dedicated Docker volume.

To persist the docker-container driver's cache, even after recreating the driver using docker buildx rm and docker buildx create, you can destroy the builder using the --keep-state flag:

For example, to create a builder named container and then remove it while persisting state:

The docker-container driver supports usingQEMU(user mode) to build non-native platforms. Use the --platform flag to specify which architectures that you want to build for.

For example, to build a Linux image for amd64 and arm64:

Note

Emulation with QEMU can be much slower than native builds, especially for compute-heavy tasks like compilation and compression or decompression.

You can customize the network that the builder container uses. This is useful if you need to use a specific network for your builds.

For example, let'screate a networknamed foonet:

Now create adocker-container builderthat will use this network:

Boot andinspect mybuilder:

Inspect the builder containerand see what network is being used:

For more information on the Docker container driver, see thebuildx reference.