In addition to the main context
key that defines the build context, each
target can also define additional named contexts with a map defined with key
contexts
. These values map to the --build-context
flag in the build
command.
Inside the Dockerfile these contexts can be used with the FROM
instruction or
--from
flag.
Supported context values are:
- Local filesystem directories
- Container images
- Git URLs
- HTTP URLs
- Name of another target in the Bake file
Pinning alpine image#
# syntax=docker/dockerfile:1
FROM alpine
RUN echo "Hello world"
# docker-bake.hcl
target "app" {
contexts = {
alpine = "docker-image://alpine:3.13"
}
}
Using a secondary source directory#
# syntax=docker/dockerfile:1
FROM scratch AS src
FROM golang
COPY --from=src . .
# docker-bake.hcl
target "app" {
contexts = {
src = "../path/to/source"
}
}
Using a target as a build context#
To use a result of one target as a build context of another, specify the target
name with target:
prefix.
# syntax=docker/dockerfile:1
FROM baseapp
RUN echo "Hello world"
# docker-bake.hcl
target "base" {
dockerfile = "baseapp.Dockerfile"
}
target "app" {
contexts = {
baseapp = "target:base"
}
}
In most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is only recommended when you have multiple Dockerfiles that can't be easily merged into one.
Deduplicate context transfer#
Note
As of Buildx version 0.17.0 and later, Bake automatically deduplicates context transfer for targets that share the same context. In addition to Buildx version 0.17.0, the builder must be running BuildKit version 0.16.0 or later, and the Dockerfile syntax must be
docker/dockerfile:1.10
or later.If you meet these requirements, you don't need to manually deduplicate context transfer as described in this section.
- To check your Buildx version, run
docker buildx version
.- To check your BuildKit version, run
docker buildx inspect --bootstrap
and look for theBuildKit version
field.- To check your Dockerfile syntax version, check the
syntax
parser directive in your Dockerfile. If it's not present, the default version whatever comes bundled with your current version of BuildKit. To set the version explicitly, add#syntax=docker/dockerfile:1.10
at the top of your Dockerfile.
When you build targets concurrently, using groups, build contexts are loaded independently for each target. If the same context is used by multiple targets in a group, that context is transferred once for each time it's used. This can result in significant impact on build time, depending on your build configuration. For example, say you have a Bake file that defines the following group of targets:
group "default" {
targets = ["target1", "target2"]
}
target "target1" {
target = "target1"
context = "."
}
target "target2" {
target = "target2"
context = "."
}
In this case, the context .
is transferred twice when you build the default
group: once for target1
and once for target2
.
If your context is small, and if you are using a local builder, duplicate context transfers may not be a big deal. But if your build context is big, or you have a large number of targets, or you're transferring the context over a network to a remote builder, context transfer becomes a performance bottleneck.
To avoid transferring the same context multiple times, you can define a named
context that only loads the context files, and have each target that needs
those files reference that named context. For example, the following Bake file
defines a named target ctx
, which is used by both target1
and target2
:
group "default" {
targets = ["target1", "target2"]
}
target "ctx" {
context = "."
target = "ctx"
}
target "target1" {
target = "target1"
contexts = {
ctx = "target:ctx"
}
}
target "target2" {
target = "target2"
contexts = {
ctx = "target:ctx"
}
}
The named context ctx
represents a Dockerfile stage, which copies the files
from its context (.
). Other stages in the Dockerfile can now reference the
ctx
named context and, for example, mount its files with --mount=from=ctx
.
FROM scratch AS ctx
COPY --link . .
FROM golang:alpine AS target1
WORKDIR /work
RUN --mount=from=ctx \
go build -o /out/client ./cmd/client \
FROM golang:alpine AS target2
WORKDIR /work
RUN --mount=from=ctx \
go build -o /out/server ./cmd/server