烘焙文件参考

Bake 文件是用于定义您使用 运行的工作流程的文件docker buildx bake。

文件格式

您可以使用以下文件格式定义 Bake 文件：

  • HashiCorp 配置语言 (HCL)
  • JSON
  • YAML（撰写文件）

默认情况下，Bake 使用以下查找顺序来查找配置文件：

  1. compose.yaml
  2. compose.yml
  3. docker-compose.yml
  4. docker-compose.yaml
  5. docker-bake.json
  6. docker-bake.override.json
  7. docker-bake.hcl
  8. 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 文件的 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细绳Docker 文件位置
inherits列表从其他目标继承属性
labels地图图像元数据
matrix地图定义一组变量，将一个目标分叉为多个目标。
name细绳使用矩阵时覆盖目标名称。
no-cache-filter列表禁用特定阶段的构建缓存
no-cache布尔值完全禁用构建缓存
output列表输出目的地
platforms列表目标平台
pull布尔值始终拉取图像
secret列表向构建公开的秘密
shm-size列表尺寸为/dev/shm
ssh列表向构建公开的 SSH 代理套接字或密钥
tags列表图像名称和标签
target细绳目标构建阶段
ulimits列表极限选项

目标参数

使用该args属性来定义目标的构建参数。这与将--build-arg标志传递给构建命令具有相同的效果 。

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

您可以设置args属性以使用null值。这样做会强制target使用ARGDockerfile 中指定的值。

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

目标.注释

该annotations属性允许您向使用烘焙构建的图像添加注释。该键采用注释列表，格式为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"]
}

请阅读指定注释级别来了解支持的级别 。

目标证明

该attest属性允许您将 构建证明应用于目标。此属性接受长格式 CSV 版本的证明参数。

target "default" {
  attest = [
    "type=provenance,mode=min",
    "type=sbom"
  ]
}

目标.缓存来源

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

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

目标.缓存到

构建缓存导出目的地。构建器将其构建缓存导出到您指定的位置。它使用 Buildx 缓存存储后端，其工作方式与 --cache-to标志相同。这采用列表值，因此您可以指定多个缓存导出目标。

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

目标.上下文

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

target "app" {
  context = "./src/www"
}

"."默认情况下，这会解析为当前工作目录 ( )。

$ docker buildx bake --print -f - <<< 'target "default" {}'
[+] Building 0.0s (0/0)
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile"
    }
  }
}

目标.上下文

额外的构建上下文。这与--build-context旗帜相同 。此属性采用一个映射，其中键生成您可以在构建中引用的命名上下文。

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

上下文类型例子
容器镜像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-内联

使用字符串值作为构建目标的内联 Dockerfile。

target "default" {
  dockerfile-inline = "FROM alpine\nENTRYPOINT [\"echo\", \"hello\"]"
}

优先dockerfile-inline于dockerfile属性。如果同时指定两者，Bake 将使用内联版本。

目标.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"
    }
  }
}

目标.继承

目标可以从其他目标继承属性。用于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列表中最后出现的目标优先。前面的示例BUILDX_EXPERIMENTAL为app-release目标定义了两次参数。它解析为，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"
      ]
    }
  }
}

目标.标签

为构建分配图像标签。这与--label的标志相同docker build。

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

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

目标矩阵

矩阵策略允许您根据指定的参数将单个目标分为多个不同的变体。这与 [GitHub Actions 的矩阵策略] 类似。您可以使用它来减少烘焙定义中的重复。

该matrix属性是参数名称到值列表的映射。 Bake 将每种可能的值组合构建为单独的目标。

每个生成的目标必须有一个唯一的名称。要指定目标名称应如何解析，请使用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
  }
}

目标名称

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

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

目标.无缓存过滤器

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

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

目标.无缓存

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

target "default" {
  no-cache = 1
}

目标.输出

用于导出构建输出的配置。这与--output旗帜相同 。以下示例将目标配置为使用仅缓存输出，

target "default" {
  output = ["type=cacheonly"]
}

目标平台

为构建目标设置目标平台。这与--platform旗帜相同 。以下示例为三种架构创建多平台构建。

target "default" {
  platforms = ["linux/amd64", "linux/arm64", "linux/arm/v7"]
}

目标拉动

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

target "default" {
  pull = "always"
}

目标.秘密

定义向构建目标公开的秘密。这与--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

目标.shm-大小

设置使用指令时为构建容器分配的共享内存的大小 RUN。

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

--shm-size这与的标志相同docker build。

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

笔记

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

目标.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

目标.标签

用于构建目标的图像名称和标签。这与--tag旗帜相同 。

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

目标.目标

设置要构建的目标构建阶段。这与--target旗帜相同 。

target "default" {
  target = "binaries"
}

目标.ulimits

使用指令时，ulimits 会覆盖构建容器的默认 ulimits，RUN 并使用软限制和硬限制指定，如下所示： <type>=<soft limit>[:<hard limit>]，例如：

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

笔记

如果您不提供 a 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"]
}

如果组与目标同名，则组优先于目标。以下烘焙文件构建该default组。烘焙忽略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_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"]
  }

在将变量插入属性之前，首先必须在烘焙文件中声明它，如以下示例所示。

$ 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 函数页面。