使用 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` 使用目标和组以声明性语法定义构建目标，使您可以高效地管理复杂的构建。

这是 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`：要附加到镜像的 声明。

    提示

    声明提供了元数据，例如构建来源（跟踪镜像构建的来源）和 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` 属性定义要构建的变体（“发布”和“调试”）。 `name` 属性定义矩阵如何扩展为多个不同的构建目标。在这种情况下， `matrix` 属性将构建扩展为两个工作流： `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，这通常意味着即使你的本地机器是macOS或Windows，构建目标也是linux/amd64或linux/arm64，因为Docker运行在Linux虚拟机中。使用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

为了生成“release”和“debug”变体，你可以像使用默认目标一样使用矩阵。使用矩阵时，你还需要根据矩阵值区分输出目录，否则二进制文件将被写入每个矩阵运行的同一位置。

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的更多信息，请查看以下资源