Bake 文件参考
Bake 文件用于定义使用 docker buildx bake
运行的工作流程。
文件格式
您可以使用以下文件格式定义 Bake 文件
- HashiCorp 配置语言 (HCL)
- JSON
- YAML(Compose 文件)
默认情况下,Bake 使用以下查找顺序查找配置文件
compose.yaml
compose.yml
docker-compose.yml
docker-compose.yaml
docker-bake.json
docker-bake.override.json
docker-bake.hcl
docker-bake.override.hcl
您可以使用 --file
标志显式指定文件位置
$ docker buildx bake --file ../docker/bake.hcl --print
如果您没有显式指定文件,Bake 会在当前工作目录中搜索文件。如果找到多个 Bake 文件,所有文件将合并为单个定义。文件根据查找顺序合并。这意味着,如果您的项目同时包含 compose.yaml
文件和 docker-bake.hcl
文件,Bake 会先加载 compose.yaml
文件,然后加载 docker-bake.hcl
文件。
如果合并的文件包含重复的属性定义,这些定义将根据属性合并或被最后出现的定义覆盖。以下属性将被最后出现的定义覆盖
target.cache-to
target.dockerfile-inline
target.dockerfile
target.outputs
target.platforms
target.pull
target.tags
target.target
例如,如果 compose.yaml
和 docker-bake.hcl
都定义了 tags
属性,则将使用 docker-bake.hcl
。
$ cat compose.yaml
services:
webapp:
build:
context: .
tags:
- bar
$ cat docker-bake.hcl
target "webapp" {
tags = ["foo"]
}
$ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"foo"
]
}
}
}
所有其他属性都将合并。例如,如果 compose.yaml
和 docker-bake.hcl
都为 labels
属性定义了唯一的条目,则将包含所有条目。同一标签的重复条目将被覆盖。
$ cat compose.yaml
services:
webapp:
build:
context: .
labels:
com.example.foo: "foo"
com.example.name: "Alice"
$ cat docker-bake.hcl
target "webapp" {
labels = {
"com.example.bar" = "bar"
"com.example.name" = "Bob"
}
}
$ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"labels": {
"com.example.foo": "foo",
"com.example.bar": "bar",
"com.example.name": "Bob"
}
}
}
}
语法
Bake 文件支持以下属性类型
target
:构建目标group
:构建目标集合variable
:构建参数和变量function
:自定义 Bake 函数
您在 Bake 文件中将属性定义为层次结构块。您可以将一个或多个属性分配给属性。
以下代码段显示了一个简单 Bake 文件的 JSON 表示形式。此 Bake 文件定义了三个属性:变量、组和目标。
{
"variable": {
"TAG": {
"default": "latest"
}
},
"group": {
"default": {
"targets": ["webapp"]
}
},
"target": {
"webapp": {
"dockerfile": "Dockerfile",
"tags": ["docker.io/username/webapp:${TAG}"]
}
}
}
在 Bake 文件的 JSON 表示形式中,属性是对象,而属性是分配给这些对象的数值。
以下示例显示了 HCL 格式的相同 Bake 文件
variable "TAG" {
default = "latest"
}
group "default" {
targets = ["webapp"]
}
target "webapp" {
dockerfile = "Dockerfile"
tags = ["docker.io/username/webapp:${TAG}"]
}
HCL 是 Bake 文件的首选格式。除了语法差异之外,HCL 允许您使用 JSON 和 YAML 格式不支持的功能。
本文档中的示例使用 HCL 格式。
目标
目标反映单个 docker build
调用。考虑以下构建命令
$ docker build \
--file=Dockerfile.webapp \
--tag=docker.io/username/webapp:latest \
https://github.com/username/webapp
您可以在 Bake 文件中按如下方式表达此命令
target "webapp" {
dockerfile = "Dockerfile.webapp"
tags = ["docker.io/username/webapp:latest"]
context = "https://github.com/username/webapp"
}
下表显示了可以分配给目标的完整属性列表
名称 | 类型 | 描述 |
---|---|---|
args | 映射 | 构建参数 |
annotations | 列表 | 导出程序注释 |
attest | 列表 | 构建证明 |
cache-from | 列表 | 外部缓存源 |
cache-to | 列表 | 外部缓存目标 |
context | 字符串 | 位于指定路径或 URL 中的一组文件 |
contexts | 映射 | 其他构建上下文 |
dockerfile-inline | 字符串 | 内联 Dockerfile 字符串 |
dockerfile | 字符串 | Dockerfile 位置 |
inherits | 列表 | 从其他目标继承属性 |
labels | 映射 | 镜像的元数据 |
matrix | 映射 | 定义一组变量,将目标分叉成多个目标。 |
name | 字符串 | 在使用矩阵时覆盖目标名称。 |
no-cache-filter | 列表 | 禁用特定阶段的构建缓存 |
no-cache | 布尔值 | 完全禁用构建缓存 |
output | 列表 | 输出目标 |
platforms | 列表 | 目标平台 |
pull | 布尔值 | 始终拉取镜像 |
secret | 列表 | 要公开给构建的机密 |
shm-size | 列表 | /dev/shm 的大小 |
ssh | 列表 | 要公开给构建的 SSH 代理套接字或密钥 |
tags | 列表 | 镜像名称和标签 |
target | 字符串 | 目标构建阶段 |
ulimits | 列表 | Ulimit 选项 |
target.args
使用 args
属性为目标定义构建参数。这与向构建命令传递 --build-arg
标志到构建命令具有相同的效果。
target "default" {
args = {
VERSION = "0.0.0+unknown"
}
}
您可以设置 args
属性以使用 null
值。这样做会强制 target
使用 Dockerfile 中指定的 ARG
值。
variable "GO_VERSION" {
default = "1.20.3"
}
target "webapp" {
dockerfile = "webapp.Dockerfile"
tags = ["docker.io/username/webapp"]
}
target "db" {
args = {
GO_VERSION = null
}
dockerfile = "db.Dockerfile"
tags = ["docker.io/username/db"]
}
target.annotations
annotations
属性允许您将注释添加到使用 bake 构建的镜像。键采用注释列表,格式为 KEY=VALUE
。
target "default" {
output = ["type=image,name=foo"]
annotations = ["org.opencontainers.image.authors=dvdksn"]
}
与以下命令相同
target "default" {
output = ["type=image,name=foo,annotation.org.opencontainers.image.authors=dvdksn"]
}
默认情况下,注释将添加到镜像清单中。您可以通过在注释前面添加前缀来配置注释的级别,该前缀包含要注释的所有级别的逗号分隔列表。以下示例将注释添加到镜像索引和清单。
target "default" {
output = ["type=image,name=foo"]
annotations = ["index,manifest:org.opencontainers.image.authors=dvdksn"]
}
阅读 指定注释级别 中支持的级别。
target.attest
attest
属性允许您将 构建证明 应用于目标。此属性接受证明参数的长格式 CSV 版本。
target "default" {
attest = [
"type=provenance,mode=min",
"type=sbom"
]
}
target.cache-from
构建缓存源。构建器从您指定的 location 导入缓存。它使用 Buildx 缓存存储后端,它的工作方式与 --cache-from
标志相同。这采用列表值,因此您可以指定多个缓存源。
target "app" {
cache-from = [
"type=s3,region=eu-west-1,bucket=mybucket",
"user/repo:cache",
]
}
target.cache-to
构建缓存导出目标。构建器将构建缓存导出到您指定的 位置。它使用 Buildx 缓存存储后端,并且工作方式与 --cache-to
标志 一样。这接受一个列表值,因此您可以指定多个缓存导出目标。
target "app" {
cache-to = [
"type=s3,region=eu-west-1,bucket=mybucket",
"type=inline"
]
}
target.context
指定此目标要使用的构建上下文的 位置。接受 URL 或目录路径。这与您传递给构建命令的 构建上下文 位置参数一样。
target "app" {
context = "./src/www"
}
默认情况下,这解析为当前工作目录("."
)。
$ docker buildx bake --print -f - <<< 'target "default" {}'
[+] Building 0.0s (0/0)
{
"target": {
"default": {
"context": ".",
"dockerfile": "Dockerfile"
}
}
}
target.contexts
其他构建上下文。这与 --build-context
标志 一样。此属性接受一个映射,其中键会导致命名上下文,您可以在构建中引用这些上下文。
您可以指定不同类型的上下文,例如本地目录、Git URL,甚至其他 Bake 目标。Bake 会根据上下文值的模式自动确定上下文的类型。
上下文类型 | 示例 |
---|---|
容器镜像 | docker-image://alpine@sha256:0123456789 |
Git URL | https://github.com/user/proj.git |
HTTP URL | https://example.com/files |
本地目录 | ../path/to/src |
Bake 目标 | target:base |
固定镜像版本
# docker-bake.hcl
target "app" {
contexts = {
alpine = "docker-image://alpine:3.13"
}
}
# Dockerfile
FROM alpine
RUN echo "Hello world"
使用本地目录
# docker-bake.hcl
target "app" {
contexts = {
src = "../path/to/source"
}
}
# Dockerfile
FROM scratch AS src
FROM golang
COPY --from=src . .
使用其他目标作为基础
注意
您应该优先使用常规的多阶段构建而不是此选项。当您有多个 Dockerfile 无法轻松合并为一个时,您可以使用此功能。
# docker-bake.hcl
target "base" {
dockerfile = "baseapp.Dockerfile"
}
target "app" {
contexts = {
baseapp = "target:base"
}
}
# Dockerfile
FROM baseapp
RUN echo "Hello world"
target.dockerfile-inline
将字符串值用作构建目标的内联 Dockerfile。
target "default" {
dockerfile-inline = "FROM alpine\nENTRYPOINT [\"echo\", \"hello\"]"
}
dockerfile-inline
优先于 dockerfile
属性。如果您同时指定两者,Bake 将使用内联版本。
target.dockerfile
用于构建的 Dockerfile 的名称。这与 --file
标志 用于 docker build
命令。
target "default" {
dockerfile = "./src/www/Dockerfile"
}
默认情况下,解析为 "Dockerfile"
。
$ docker buildx bake --print -f - <<< 'target "default" {}'
[+] Building 0.0s (0/0)
{
"target": {
"default": {
"context": ".",
"dockerfile": "Dockerfile"
}
}
}
target.inherits
目标可以从其他目标继承属性。使用 inherits
从一个目标引用另一个目标。
在以下示例中,app-dev
目标指定了镜像名称和标签。app-release
目标使用 inherits
重用标签名称。
variable "TAG" {
default = "latest"
}
target "app-dev" {
tags = ["docker.io/username/myapp:${TAG}"]
}
target "app-release" {
inherits = ["app-dev"]
platforms = ["linux/amd64", "linux/arm64"]
}
inherits
属性是一个列表,这意味着您可以从多个其他目标重用属性。在以下示例中,app-release
目标从 app-dev
和 _release
两个目标重用属性。
target "app-dev" {
args = {
GO_VERSION = "1.20"
BUILDX_EXPERIMENTAL = 1
}
tags = ["docker.io/username/myapp"]
dockerfile = "app.Dockerfile"
labels = {
"org.opencontainers.image.source" = "https://github.com/username/myapp"
}
}
target "_release" {
args = {
BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
BUILDX_EXPERIMENTAL = 0
}
}
target "app-release" {
inherits = ["app-dev", "_release"]
platforms = ["linux/amd64", "linux/arm64"]
}
从多个目标继承属性时,如果存在冲突,inherits
列表中最后出现的目标优先。前面的示例为 app-release
目标两次定义了 BUILDX_EXPERIMENTAL
参数。它解析为 0
,因为 _release
目标在继承链中最后出现
$ docker buildx bake --print app-release
[+] Building 0.0s (0/0)
{
"group": {
"default": {
"targets": [
"app-release"
]
}
},
"target": {
"app-release": {
"context": ".",
"dockerfile": "app.Dockerfile",
"args": {
"BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1",
"BUILDX_EXPERIMENTAL": "0",
"GO_VERSION": "1.20"
},
"labels": {
"org.opencontainers.image.source": "https://github.com/username/myapp"
},
"tags": [
"docker.io/username/myapp"
],
"platforms": [
"linux/amd64",
"linux/arm64"
]
}
}
}
target.labels
将镜像标签分配给构建。这与 docker build
的 --label
标志相同。
target "default" {
labels = {
"org.opencontainers.image.source" = "https://github.com/username/myapp"
"com.docker.image.source.entrypoint" = "Dockerfile"
}
}
可以使用 null
值作为标签。如果这样做,构建器将使用 Dockerfile 中指定的标签值。
target.matrix
矩阵策略允许您根据指定的参数将单个目标分叉为多个不同的变体。这与 [GitHub Actions 的矩阵策略] 的工作方式类似。您可以使用它来减少 Bake 定义中的重复。
matrix
属性是参数名称到值列表的映射。Bake 会构建每个可能的价值组合作为单独的目标。
每个生成的 target 必须有唯一的名称。要指定目标名称的解析方式,请使用 name
属性。
以下示例将 app
目标解析为 app-foo
和 app-bar
。它还使用矩阵值来定义 目标构建阶段。
target "app" {
name = "app-${tgt}"
matrix = {
tgt = ["foo", "bar"]
}
target = tgt
}
$ docker buildx bake --print app
[+] Building 0.0s (0/0)
{
"group": {
"app": {
"targets": [
"app-foo",
"app-bar"
]
},
"default": {
"targets": [
"app"
]
}
},
"target": {
"app-bar": {
"context": ".",
"dockerfile": "Dockerfile",
"target": "bar"
},
"app-foo": {
"context": ".",
"dockerfile": "Dockerfile",
"target": "foo"
}
}
}
多个轴
您可以在矩阵中指定多个键,以便在多个轴上分叉目标。使用多个矩阵键时,Bake 会构建所有可能的变体。
以下示例构建四个目标
app-foo-1-0
app-foo-2-0
app-bar-1-0
app-bar-2-0
target "app" {
name = "app-${tgt}-${replace(version, ".", "-")}"
matrix = {
tgt = ["foo", "bar"]
version = ["1.0", "2.0"]
}
target = tgt
args = {
VERSION = version
}
}
每个矩阵目标的多个值
如果要根据单个值以外的内容区分矩阵,可以使用映射作为矩阵值。Bake 会为每个映射创建一个目标,您可以使用点表示法访问嵌套的值。
以下示例构建两个目标
app-foo-1-0
app-bar-2-0
target "app" {
name = "app-${item.tgt}-${replace(item.version, ".", "-")}"
matrix = {
item = [
{
tgt = "foo"
version = "1.0"
},
{
tgt = "bar"
version = "2.0"
}
]
}
target = item.tgt
args = {
VERSION = item.version
}
}
target.name
为使用矩阵策略的目标指定名称解析。以下示例将 app
目标解析为 app-foo
和 app-bar
。
target "app" {
name = "app-${tgt}"
matrix = {
tgt = ["foo", "bar"]
}
target = tgt
}
target.no-cache-filter
不要为指定的阶段使用构建缓存。这与 docker build
的 --no-cache-filter
标志相同。以下示例避免为 foo
构建阶段使用构建缓存。
target "default" {
no-cache-filter = ["foo"]
}
target.no-cache
构建镜像时不要使用缓存。这与 docker build
的 --no-cache
标志相同。
target "default" {
no-cache = 1
}
target.output
用于导出构建输出的配置。这与 --output
标志 一样。以下示例配置目标以使用仅缓存的输出,
target "default" {
output = ["type=cacheonly"]
}
target.platforms
为构建目标设置目标平台。这与 --platform
标志 一样。以下示例为三个体系结构创建多平台构建。
target "default" {
platforms = ["linux/amd64", "linux/arm64", "linux/arm/v7"]
}
target.pull
配置构建器在构建目标时是否应尝试拉取镜像。这与 docker build
的 --pull
标志相同。以下示例强制构建器始终拉取构建目标中引用的所有镜像。
target "default" {
pull = "always"
}
target.secret
定义要公开给构建目标的机密。这与 --secret
标志 一样。
variable "HOME" {
default = null
}
target "default" {
secret = [
"type=env,id=KUBECONFIG",
"type=file,id=aws,src=${HOME}/.aws/credentials"
]
}
这使您可以在 Dockerfile 中挂载机密。
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
aws cloudfront create-invalidation ...
RUN --mount=type=secret,id=KUBECONFIG \
KUBECONFIG=$(cat /run/secrets/KUBECONFIG) helm upgrade --install
target.shm-size
设置使用 RUN
指令时为构建容器分配的共享内存的大小。
格式为 <number><unit>
。number
必须大于 0
。Unit 是可选的,可以是 b
(字节)、k
(千字节)、m
(兆字节)或 g
(千兆字节)。如果省略单位,则系统使用字节。
这与 docker build
的 --shm-size
标志相同。
target "default" {
shm-size = "128m"
}
注意
在大多数情况下,建议让构建器自动确定适当的配置。仅当复杂构建场景需要特定性能调整时,才应考虑手动调整。
target.ssh
定义要公开给构建的 SSH 代理套接字或密钥。这与 --ssh
标志 一样。如果您需要在构建期间访问私有存储库,这可能很有用。
target "default" {
ssh = ["default"]
}
FROM alpine
RUN --mount=type=ssh \
apk add git openssh-client \
&& install -m 0700 -d ~/.ssh \
&& ssh-keyscan github.com >> ~/.ssh/known_hosts \
&& git clone [email protected]:user/my-private-repo.git
target.tags
用于构建目标的镜像名称和标签。这与 --tag
标志 一样。
target "default" {
tags = [
"org/repo:latest",
"myregistry.azurecr.io/team/image:v1"
]
}
target.target
将目标构建阶段设置为构建。这与 --target
标志 相同。
target "default" {
target = "binaries"
}
target.ulimits
使用 RUN
指令时,Ulimits 会覆盖构建容器的默认 ulimits,并使用软限制和硬限制指定,例如:<type>=<soft limit>[:<hard limit>]
,例如
target "app" {
ulimits = [
"nofile=1024:1024"
]
}
注意
如果未提供
hard limit
,则soft limit
用于两个值。如果未设置ulimits
,则会从守护程序上设置的默认ulimits
继承。
注意
在大多数情况下,建议让构建器自动确定适当的配置。仅当复杂构建场景需要特定性能调整时,才应考虑手动调整。
组
组允许您一次调用多个构建(目标)。
group "default" {
targets = ["db", "webapp-dev"]
}
target "webapp-dev" {
dockerfile = "Dockerfile.webapp"
tags = ["docker.io/username/webapp:latest"]
}
target "db" {
dockerfile = "Dockerfile.db"
tags = ["docker.io/username/db"]
}
如果组和目标都存在且名称相同,则组优先于目标。以下 bake 文件构建 default
组。Bake 忽略 default
目标。
target "default" {
dockerfile-inline = "FROM ubuntu"
}
group "default" {
targets = ["alpine", "debian"]
}
target "alpine" {
dockerfile-inline = "FROM alpine"
}
target "debian" {
dockerfile-inline = "FROM debian"
}
变量
HCL 文件格式支持变量块定义。您可以在 Dockerfile 中将变量用作构建参数,或在 Bake 文件中的属性值中插入它们。
variable "TAG" {
default = "latest"
}
target "webapp-dev" {
dockerfile = "Dockerfile.webapp"
tags = ["docker.io/username/webapp:${TAG}"]
}
您可以在 Bake 文件中为变量分配默认值,或为其分配 null
值。如果您分配 null
值,Buildx 将使用 Dockerfile 中的默认值。
您可以使用环境变量覆盖 Bake 文件中设置的变量默认值。以下示例将 TAG
变量设置为 dev
,覆盖上一个示例中显示的默认 latest
值。
$ TAG=dev docker buildx bake webapp-dev
内置变量
以下变量是内置变量,您可以在 Bake 中使用它们,而无需定义它们。
变量 | 描述 |
---|---|
BAKE_CMD_CONTEXT | 在使用远程 Bake 文件构建时保存主上下文。 |
BAKE_LOCAL_PLATFORM | 返回当前平台的默认平台规范(例如 linux/amd64 )。 |
使用环境变量作为默认值
您可以设置 Bake 变量以使用环境变量的值作为默认值
variable "HOME" {
default = "$HOME"
}
将变量内插到属性中
要在属性字符串值中插入变量,您必须使用花括号。以下不起作用
variable "HOME" {
default = "$HOME"
}
target "default" {
ssh = ["default=$HOME/.ssh/id_rsa"]
}
将变量括在花括号中,您希望将其插入
variable "HOME" {
default = "$HOME"
}
target "default" {
- ssh = ["default=$HOME/.ssh/id_rsa"]
+ ssh = ["default=${HOME}/.ssh/id_rsa"]
}
在将变量插入属性之前,您必须先在 bake 文件中声明它,如下面的示例所示。
$ cat docker-bake.hcl
target "default" {
dockerfile-inline = "FROM ${BASE_IMAGE}"
}
$ docker buildx bake
[+] Building 0.0s (0/0)
docker-bake.hcl:2
--------------------
1 | target "default" {
2 | >>> dockerfile-inline = "FROM ${BASE_IMAGE}"
3 | }
4 |
--------------------
ERROR: docker-bake.hcl:2,31-41: Unknown variable; There is no variable named "BASE_IMAGE"., and 1 other diagnostic(s)
$ cat >> docker-bake.hcl
variable "BASE_IMAGE" {
default = "alpine"
}
$ docker buildx bake
[+] Building 0.6s (5/5) FINISHED
函数
由 go-cty 提供的 一组通用函数 可用于 HCL 文件。
# docker-bake.hcl
target "webapp-dev" {
dockerfile = "Dockerfile.webapp"
tags = ["docker.io/username/webapp:latest"]
args = {
buildno = "${add(123, 1)}"
}
}
此外,还支持 用户定义函数。
# docker-bake.hcl
function "increment" {
params = [number]
result = number + 1
}
target "webapp-dev" {
dockerfile = "Dockerfile.webapp"
tags = ["docker.io/username/webapp:latest"]
args = {
buildno = "${increment(123)}"
}
}
注意
有关更多详细信息,请参阅 用户定义的 HCL 函数 页面。