使用 Docker Buildx Bake 精通多平台构建、测试等功能

目录

本指南演示了如何使用 Docker Buildx Bake 简化和自动化镜像构建、测试以及生成构建产物的过程。通过在声明式的 docker-bake.hcl 文件中定义构建配置，您可以消除手动编写的脚本，并为复杂的构建、测试和产物生成启用高效的工作流程。

假设

本指南假设您熟悉以下内容

先决条件

  • 您的机器上安装了最新版本的 Docker。
  • 您已安装 Git 用于克隆仓库。
  • 您正在使用 containerd 镜像存储。

简介

本指南使用一个示例项目来演示 Docker Buildx Bake 如何简化您的构建和测试工作流程。该仓库包含一个 Dockerfile 和一个 docker-bake.hcl 文件，为您提供了一个即用型的设置来尝试 Bake 命令。

首先克隆示例仓库

git clone https://github.com/dvdksn/bakeme.git
cd bakeme

Bake 文件 docker-bake.hcl 使用目标（targets）和组（groups），以声明式语法定义构建目标，使您能够高效地管理复杂的构建。

以下是 Bake 文件开箱即用的样子

target "default" {
  target = "image"
  tags = [
    "bakeme:latest",
  ]
  attest = [
    "type=provenance,mode=max",
    "type=sbom",
  ]
  platforms = [
    "linux/amd64",
    "linux/arm64",
    "linux/riscv64",
  ]
}

target 关键字为 Bake 定义了一个构建目标。default 目标定义了在命令行未指定特定目标时要构建的目标。以下是 default 目标的选项快速摘要

  • target：Dockerfile 中的目标构建阶段。

  • tags：分配给镜像的标签。

  • attest：附加到镜像的证明。

    提示

    证明提供了元数据，如构建来源（provenance），用于追踪镜像构建的来源，以及 SBOM（软件物料清单），可用于安全审计和合规性检查。

  • platforms：要构建的平台变体。

要执行此构建，只需在仓库的根目录运行以下命令

$ docker buildx bake

使用 Bake，您可以避免冗长且难以记住的命令行调用，通过用结构化的配置文件替换手动的、易出错的脚本，来简化构建配置管理。

作为对比，以下是未使用 Bake 的构建命令的样子

$ docker buildx build \
  --target=image \
  --tag=bakeme:latest \
  --provenance=true \
  --sbom=true \
  --platform=linux/amd64,linux/arm64,linux/riscv64 \
  .

测试和代码检查

Bake 不仅用于定义构建配置和运行构建。您还可以使用 Bake 来运行测试，有效地将 BuildKit 用作任务运行器。在容器中运行测试非常适合确保可复现的结果。本节将展示如何添加两种类型的测试

  • 使用 go test 进行单元测试。
  • 使用 golangci-lint 进行代码风格违规检查。

以测试驱动开发（TDD）的方式，首先向 Bake 文件添加一个新的 test 目标

target "test" {
  target = "test"
  output = ["type=cacheonly"]
}
提示

使用 type=cacheonly 可确保构建输出被有效地丢弃；层被保存到 BuildKit 的缓存中，但 Buildx 不会尝试将结果加载到 Docker Engine 的镜像存储中。

对于测试运行，您不需要导出构建输出——只有测试执行才重要。

要执行此 Bake 目标，请运行 docker buildx bake test。此时，您将收到一个错误，指示 Dockerfile 中不存在 test 阶段。

$ docker buildx bake test
[+] Building 1.2s (6/6) FINISHED
 => [internal] load local bake definitions
...
ERROR: failed to solve: target stage "test" could not be found

要满足此目标，请添加相应的 Dockerfile 目标。这里的 test 阶段基于与构建阶段相同的基础阶段。

FROM base AS test
RUN --mount=target=. \
    --mount=type=cache,target=/go/pkg/mod \
    go test .
提示

--mount=type=cache 指令可以在构建之间缓存 Go 模块，通过避免重新下载依赖项来提高构建性能。这个共享缓存确保了相同的依赖集在构建、测试和其他阶段都可用。

现在，使用 Bake 运行 test 目标将评估此项目的单元测试。如果您想验证它是否有效，可以对 main_test.go 进行任意更改以导致测试失败。

接下来，要启用代码检查，请向 Bake 文件添加另一个名为 lint 的目标

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

然后在 Dockerfile 中，添加构建阶段。此阶段将使用 Docker Hub 上的官方 golangci-lint 镜像。

提示

因为此阶段依赖于执行外部依赖项，通常最好将要使用的版本定义为构建参数。这使您将来可以通过将依赖项版本集中放置在 Dockerfile 的开头来更轻松地管理版本升级。

ARG GO_VERSION="1.23"
ARG GOLANGCI_LINT_VERSION="1.61"

#...

FROM golangci/golangci-lint:v${GOLANGCI_LINT_VERSION}-alpine AS lint
RUN --mount=target=.,rw \
    golangci-lint run

最后，要启用同时运行两个测试，您可以在 Bake 文件中使用 groups 结构。一个组可以指定通过单次调用运行多个目标。

group "validate" {
  targets = ["test", "lint"]
}

现在，运行两个测试就像这样简单

$ docker buildx bake validate

构建变体

有时您需要构建一个程序的多个版本。以下示例使用 Bake 来构建程序的单独的“发布”和“调试”变体，使用矩阵。使用矩阵可以让您并行运行具有不同配置的构建，从而节省时间并确保一致性。

矩阵将单个构建扩展为多个构建，每个构建代表矩阵参数的唯一组合。这意味着您可以通过最少的配置更改，来协调 Bake 并行构建程序的生产和开发版本。

本指南的示例项目已设置为使用构建时选项来有条件地启用调试日志和跟踪功能。

  • 如果您使用 go build -tags="debug" 编译程序，则会启用额外的日志和跟踪功能（开发模式）。
  • 如果您在没有 debug 标签的情况下构建，程序将使用默认记录器进行编译（生产模式）。

通过添加一个定义要构建的变量组合的矩阵属性来更新 Bake 文件

docker-bake.hcl
 target "default" {
+  matrix = {
+    mode = ["release", "debug"]
+  }
+  name = "image-${mode}"
   target = "image"

matrix 属性定义了要构建的变体（“release” 和 “debug”）。name 属性定义了矩阵如何扩展为多个不同的构建目标。在这种情况下，矩阵属性将构建扩展为两个工作流：image-release 和 image-debug，每个工作流使用不同的配置参数。

接下来，定义一个名为 BUILD_TAGS 的构建参数，它接受矩阵变量的值。

docker-bake.hcl
   target = "image"
+  args = {
+    BUILD_TAGS = mode
+  }
   tags = [

您还需要更改为这些构建分配镜像标签的方式。目前，两个矩阵路径都会生成相同的镜像标签名称，并会相互覆盖。更新 tags 属性，使用条件运算符根据矩阵变量值设置标签。

docker-bake.hcl
   tags = [
-    "bakeme:latest",
+    mode == "release" ? "bakeme:latest" : "bakeme:dev"
   ]
  • 如果 mode 是 release，标签名称是 bakeme:latest
  • 如果 mode 是 debug，标签名称是 bakeme:dev

最后，更新 Dockerfile 以在编译阶段使用 BUILD_TAGS 参数。当 -tags="${BUILD_TAGS}" 选项评估为 -tags="debug" 时，编译器将使用 debug.go 文件中的 configureLogging 函数。

Dockerfile
 # build compiles the program
 FROM base AS build
-ARG TARGETOS TARGETARCH
+ARG TARGETOS TARGETARCH BUILD_TAGS
 ENV GOOS=$TARGETOS
 ENV GOARCH=$TARGETARCH
 RUN --mount=target=. \
        --mount=type=cache,target=/go/pkg/mod \
-       go build -o "/usr/bin/bakeme" .
+       go build -tags="${BUILD_TAGS}" -o "/usr/bin/bakeme" .

就是这些了。有了这些更改，您的 docker buildx bake 命令现在可以构建两个多平台镜像变体。您可以使用 docker buildx bake --print 命令来检查 Bake 生成的规范构建配置。运行此命令显示 Bake 将运行一个包含两个目标的 default 组，这两个目标具有不同的构建参数和镜像标签。

{
  "group": {
    "default": {
      "targets": ["image-release", "image-debug"]
    }
  },
  "target": {
    "image-debug": {
      "attest": ["type=provenance,mode=max", "type=sbom"],
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "BUILD_TAGS": "debug"
      },
      "tags": ["bakeme:dev"],
      "target": "image",
      "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
    },
    "image-release": {
      "attest": ["type=provenance,mode=max", "type=sbom"],
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "BUILD_TAGS": "release"
      },
      "tags": ["bakeme:latest"],
      "target": "image",
      "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
    }
  }
}

考虑到所有的平台变体，这意味着构建配置会生成 6 个不同的镜像。

$ docker buildx bake
$ docker image ls --tree

IMAGE                   ID             DISK USAGE   CONTENT SIZE   USED
bakeme:dev              f7cb5c08beac       49.3MB         28.9MB
├─ linux/riscv64        0eae8ba0367a       9.18MB         9.18MB
├─ linux/arm64          56561051c49a         30MB         9.89MB
└─ linux/amd64          e8ca65079c1f        9.8MB          9.8MB

bakeme:latest           20065d2c4d22       44.4MB         25.9MB
├─ linux/riscv64        7cc82872695f       8.21MB         8.21MB
├─ linux/arm64          e42220c2b7a3       27.1MB         8.93MB
└─ linux/amd64          af5b2dd64fde       8.78MB         8.78MB

导出构建产物

导出像二进制文件这样的构建产物，对于部署到没有 Docker 或 Kubernetes 的环境非常有用。例如，如果您的程序要在用户的本地机器上运行。

提示

本节讨论的技术不仅可以应用于像二进制文件这样的构建输出，还可以应用于任何类型的产物，例如测试报告。

对于像 Go 和 Rust 这样编译后的二进制文件通常是可移植的编程语言，为仅导出二进制文件创建备用构建目标非常简单。您所需要做的就是在 Dockerfile 中添加一个空阶段，其中只包含您想要导出的二进制文件。

首先，让我们添加一种快速构建本地平台二进制文件并将其导出到本地文件系统的 ./build/local 的方法。

在 docker-bake.hcl 文件中，创建一个新的 bin 目标。在此阶段中，将 output 属性设置为本地文件系统路径。Buildx 会自动检测到输出看起来像文件路径，并使用本地导出器将结果导出到指定路径。

target "bin" {
  target = "bin"
  output = ["build/bin"]
  platforms = ["local"]
}

请注意，此阶段指定了一个 local 平台。默认情况下，如果未指定 platforms，构建将以 BuildKit 主机的操作系统和架构为目标。如果您使用 Docker Desktop，这通常意味着构建目标是 linux/amd64 或 linux/arm64，即使您的本地机器是 macOS 或 Windows，因为 Docker 在 Linux VM 中运行。使用 local 平台会强制目标平台与您的本地环境相匹配。

接下来，将 bin 阶段添加到 Dockerfile，它会从构建阶段复制已编译的二进制文件。

FROM scratch AS bin
COPY --from=build "/usr/bin/bakeme" /

现在，您可以使用 docker buildx bake bin 导出您的本地平台版本的二进制文件。例如，在 macOS 上，此构建目标会生成一个Mach-O 格式的可执行文件——这是 macOS 的标准可执行文件格式。

$ docker buildx bake bin
$ file ./build/bin/bakeme
./build/bin/bakeme: Mach-O 64-bit executable arm64

接下来，让我们添加一个目标来构建程序的所有平台变体。为此，您可以继承刚刚创建的 bin 目标，并通过添加所需的平台来扩展它。

target "bin-cross" {
  inherits = ["bin"]
  platforms = [
    "linux/amd64",
    "linux/arm64",
    "linux/riscv64",
  ]
}

现在，构建 bin-cross 目标会为所有平台创建二进制文件。每个变体都会自动创建子目录。

$ docker buildx bake bin-cross
$ tree build/
build/
└── bin
    ├── bakeme
    ├── linux_amd64
    │   └── bakeme
    ├── linux_arm64
    │   └── bakeme
    └── linux_riscv64
        └── bakeme

5 directories, 4 files

为了同时生成“发布”和“调试”变体，您可以像处理默认目标时一样使用矩阵。当使用矩阵时，您还需要根据矩阵值来区分输出目录，否则每次矩阵运行都会将二进制文件写入相同的位置。

target "bin-all" {
  inherits = ["bin-cross"]
  matrix = {
    mode = ["release", "debug"]
  }
  name = "bin-${mode}"
  args = {
    BUILD_TAGS = mode
  }
  output = ["build/bin/${mode}"]
}
$ rm -r ./build/
$ docker buildx bake bin-all
$ tree build/
build/
└── bin
    ├── debug
    │   ├── linux_amd64
    │   │   └── bakeme
    │   ├── linux_arm64
    │   │   └── bakeme
    │   └── linux_riscv64
    │       └── bakeme
    └── release
        ├── linux_amd64
        │   └── bakeme
        ├── linux_arm64
        │   └── bakeme
        └── linux_riscv64
            └── bakeme

10 directories, 6 files

结论

Docker Buildx Bake 简化了复杂的构建工作流程，实现了高效的多平台构建、测试和产物导出。通过将 Buildx Bake 集成到您的项目中，您可以简化 Docker 构建，使您的构建配置具有可移植性，并更轻松地处理复杂的配置。

尝试不同的配置，并扩展您的 Bake 文件以适应您项目的需求。您可以考虑将 Bake 集成到您的 CI/CD 管道中，以自动化构建、测试和产物部署。Buildx Bake 的灵活性和强大功能可以显著改善您的开发和部署流程。

进一步阅读

有关如何使用 Bake 的更多信息，请查看以下资源

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.