烘焙文件参考

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.yamlfile 和一个docker-bake.hcl文件中，Bake 会加载compose.yamlfile 文件，然后这docker-bake.hcl文件。

如果合并的文件包含重复的属性定义，则这些定义为 Merged 或 Overridned by the last occurrence，具体取决于属性。以下属性将被最后一个匹配项覆盖：

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 表示形式中，properties 是对象，和 attributes 是分配给这些对象的值。

以下示例显示了 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调用。请考虑以下 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`	列表	要向 build 公开的 secret
`shm-size`	列表	大小`/dev/shm`
`ssh`	列表	要向 build 公开的 SSH 代理套接字或密钥
`tags`	列表	镜像名称和标签
`target`	字符串	目标构建阶段
`ulimits`	列表	Ulimit 选项

`target.args`

使用args属性来定义目标的构建参数。这与传递--build-argflag 添加到 build 命令中。

target "default" {
  args = {
    VERSION = "0.0.0+unknown"
  }
}

您可以设置args要使用的属性null值。这样做会强制target要使用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 采用 annotation 列表，格式为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"]
}

默认情况下，注释会添加到镜像清单中。您可以配置级别，方法是向注释添加前缀，其中包含要注释的所有级别的逗号分隔列表。以下内容 example 将 annotations 添加到 Image 索引和 manifests。

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`

构建缓存源。构建器将从您指定的位置导入缓存。它使用 Buildx 缓存存储后端，它的工作方式与--cache-from旗。这需要一个 list 值，因此您可以指定多个缓存源。

target "app" {
  cache-from = [
    "type=s3,region=eu-west-1,bucket=mybucket",
    "user/repo:cache",
  ]
}

`target.cache-to`

构建缓存导出目标。构建器会将其构建缓存导出到您指定的位置。它使用 Buildx 缓存存储后端，它的工作方式与--cache-to旗. 这需要一个 list 值，因此您可以指定多个缓存导出目标。

target "app" {
  cache-to = [
    "type=s3,region=eu-west-1,bucket=mybucket",
    "type=inline"
  ]
}

`target.call`

指定要使用的前端方法。例如，前端方法允许您仅执行构建检查，而不是运行构建。这与--call旗。

target "app" {
  call = "check"
}

有关前端方法的更多信息，请参阅 CLI 参考docker buildx build --call.

`target.context`

指定要用于此目标的构建上下文的位置。接受 URL 或目录路径。这与 build context 位置参数相同传递给 build 命令。

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旗. 此 attribute 需要一个 map，其中 keys 会生成命名的 context，你可以引用。

您可以指定不同类型的上下文，例如本地目录、Git URL、甚至其他 Bake 目标。Bake 会自动确定基于 Context 值模式的 context。

上下文类型	例
容器镜像	`docker-image://alpine@sha256:0123456789`
Git 网址	`https://github.com/user/proj.git`
HTTP 网址	`https://example.com/files`
本地目录	`../path/to/src`
烘焙目标	`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`

使用 string 值作为构建目标的内联 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.entitlements`

权利是构建过程运行所需的权限。

当前支持的权利包括：

network.host：允许构建使用访问主机网络的命令。在 Dockerfile 中，使用RUN --network=host以在启用主机网络的情况下运行命令。
security.insecure：允许构建在不受默认安全沙箱限制的特权容器中运行命令。此类容器可能会访问和修改系统资源。在 Dockerfile 中，使用RUN --security=insecure在特权容器中运行命令。

target "integration-tests" {
  # this target requires privileged containers to run nested containers
  entitlements = ["security.insecure"]
}

权利通过两步过程启用。首先，目标必须声明它所需的权利。其次，在调用bake命令中，用户必须通过传递--allow标记或确认权利。这是为了确保用户知道他们向构建过程授予的可能不安全的权限。

`target.inherits`

目标可以从其他目标继承属性。用inherits从一个目标引用到另一个目标。

在以下示例中，这app-devtarget 指定镜像名称和标签。这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"]
}

这inheritsattribute 是一个列表，这意味着您可以重用来自多个其他目标的属性。在以下示例中，app-releaseTarget 重用属性从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"]
}

从多个目标继承属性时，如果存在冲突，最后显示在inheritslist 优先。前面的示例定义了BUILDX_EXPERIMENTAL参数的两次app-release目标。它解析为0因为_releasetarget 出现在继承链的最后：

$ 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`

将镜像标签分配给内部版本。这与--label的标志docker build.

target "default" {
  labels = {
    "org.opencontainers.image.source" = "https://github.com/username/myapp"
    "com.docker.image.source.entrypoint" = "Dockerfile"
  }
}

可以使用null标签的值。如果这样做，生成器将使用 Dockerfile 中指定的标签值。

`target.matrix`

矩阵策略允许您将单个目标分叉为多个不同的 variants，具体取决于您指定的参数。其工作方式与 [GitHub Actions 的矩阵策略] 类似。您可以使用它来减少烘焙定义中的重复。

这matrixattribute 是参数名称到值列表的映射。 Bake 将每个可能的值组合构建为单独的目标。

每个生成的目标都必须具有唯一的名称。要指定目标名称应如何解析，请使用name属性。

以下示例解析apptarget 设置为app-foo和app-bar. 它还使用 matrix 值来定义目标构建阶段。

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
  }
}

每个矩阵目标多个值

如果要对矩阵进行多个值的微分，您可以将 Map 用作 Matrix 值。Bake 为每个地图创建一个目标，并且您可以使用 Dot Notation 访问嵌套值。

以下示例构建两个目标：

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`

为使用矩阵策略的目标指定名称解析。以下示例解析apptarget 设置为app-foo和app-bar.

target "app" {
  name = "app-${tgt}"
  matrix = {
    tgt = ["foo", "bar"]
  }
  target = tgt
}

`target.network`

指定整个构建请求的网络模式。这将覆盖默认网络模式对于所有的RUN说明。接受的值为default,host和none.

通常，为构建步骤设置网络模式的更好方法是使用RUN --network=<value>在 Dockerfile 中。这样，您可以为各个构建步骤和每个人构建设置网络模式 Dockerfile 无需将其他标志传递给 build 命令即可获得一致的行为。

如果将网络模式设置为host在 Bake 文件中，还必须授予network.hostentitlement 时调用bake命令。这是因为host网络模式需要提升的权限，并且可能存在安全风险。您可以将--allow=network.host到docker buildx bake命令授予权利，或者您可以如果您使用的是交互式终端，请在出现提示时确认权利。

target "app" {
  # make sure this build does not access internet
  network = "none"
}

`target.no-cache-filter`

不要对指定的阶段使用构建缓存。这与--no-cache-filter的标志docker build. 以下示例避免了foobuild 阶段。

target "default" {
  no-cache-filter = ["foo"]
}

`target.no-cache`

构建镜像时不要使用缓存。这与--no-cache的标志docker build.

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`

配置生成器在构建目标时是否应尝试提取镜像。这与--pull的标志docker build. 以下示例强制生成器始终提取构建目标中引用的所有镜像。

target "default" {
  pull = true
}

`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,env=KUBECONFIG \
    helm upgrade --install

`target.shm-size`

设置在使用RUN指示。

格式为<number><unit>.number必须大于0.单位为可选，可以是b（字节）、k（千字节）、m（兆字节）或g（千兆字节）。如果省略该单位，系统将使用字节。

这与--shm-size的标志docker build.

target "default" {
  shm-size = "128m"
}

注意
在大多数情况下，建议让 Builder 自动确定适当的配置。只应考虑手动调整当复杂的构建场景需要特定的性能优化时。

`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 git@github.com:user/my-private-repo.git

`target.tags`

用于构建目标的镜像名称和标签。这与--tag旗.

target "default" {
  tags = [
    "org/repo:latest",
    "myregistry.azurecr.io/team/image:v1"
  ]
}

`target.target`

将目标 build 阶段设置为 build。这与--target旗.

target "default" {
  target = "binaries"
}

`target.ulimits`

Ulimits 在使用RUN说明，并指定了软限制和硬限制，如下所示：<type>=<soft limit>[:<hard limit>]例如：

target "app" {
  ulimits = [
    "nofile=1024:1024"
  ]
}

注意
如果您未提供hard limit这soft limit已使用对于这两个值。如果没有ulimits设置，则它们继承自默认的ulimits设置在守护进程上。

注意
在大多数情况下，建议让 Builder 自动确定适当的配置。只应考虑手动调整当复杂的构建场景需要特定的性能优化时。

群

组允许您一次调用多个构建（目标）。

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"]
}

如果 Group 以相同的名称存在，则 groups 优先于 targets。以下 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 文件中的变量分配默认值。或分配一个nullvalue 添加到它。如果您将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 函数页面。