「Docker Buildx」- 构建“跨平台”镜像(学习笔记)

  CREATE BY JENKINSBOT

问题描述

“跨平台镜像”是指什么呢?我们以 nginx:latest 镜像为例,该镜像支持八种架构,比如 x86、arm64、amd64 等等。

神奇的地方是,对于同一个 docker pull 命令,却返回不同平台的镜像。比如:
1)在 amd64 中,执行 docker pull nginx:latest 命令,将返回摘要为 044451886742 的镜像;
2)在 arm64 中,执行 docker pull nginx:latest 命令,将返回摘要为 4f1e67ed43f3 的镜像;

经过一番研究,我们知道使用 Manifest List 创建“这种镜像”,并记录在 Multi-arch build 笔记中。

后来我们又发现 Docker Buildx 也可以用来构建这种镜像,而且更简洁,扩展性更高。

该笔记将记录:如何使用 Docker Buildx 构建多平台镜像,以及常见问题处理。

解决方案

Docker Buildx,是客户端插件,因此扩展 docker 命令,它支持全部 Moby BuildKit 特性。使用方法类同于 docker build 但又支持很多新特性,比如 创建有范围的构建器实例;在多节点中进行并行构建。背地里,还是在使用 BuildKit 工具,有兴趣可以研究 moby/buildkit 工具。

下面是使用 Docker Buildx 构建镜像的示例,比较简单,旨在让我们理解 Docker Buildx 的使用方法。

第一步、安装及启用

安装过程如下(详细内容,参考 README.md/Installing 文档)

# 第一步、下载并安装命令

mkdir -pv ~/.docker/cli-plugins/
wget -O ~/.docker/cli-plugins/docker-buildx \
    https://github.com/docker/buildx/releases/download/v0.5.1/buildx-v0.5.1.linux-amd64
chmod a+x ~/.docker/cli-plugins/docker-buildx 

# 第二步、设置 experimental 参数

vim ~/.docker/config.json
{
    ...
    "experimental": "enabled",
    ...
}

安装 docker buildx 为默认构建命令。而后,执行 docker build 等同于 docker buildx 命令:

docker buildx install
docker buildx uninstall # 卸载

第二步、使用 Buildx 构建镜像

如下示例,使用 buildx 构建镜像的流程:

# 获取我们要构建的镜像
git clone https://github.com/kstaken/dockerfile-examples.git
cd dockerfile-examples/rethinkdb

# 创建构建实例。通俗的讲,就是创建用于执行构建任务的节点
docker buildx create --use --name build-node-example --driver docker-container 
docker buildx ls

# 执行构建命令
docker buildx build \
    --tag 0xa0000/buildx-example:latest \
    --platform linux/amd64,linux/arm64 .

# 如果使用 --push 选项,那么在构建完成之后,会立即推送镜像仓库
docker buildx build --push \
    --tag 0xa0000/buildx-example:latest \
    --platform linux/amd64,linux/arm64 .

关于 docker buildx create 的 –driver 选项。其实有两种驱动:docker 与 docker-container:
1)–driver docker,表示使用绑定到 dockerd 的 BuildKit 工具来进行构建操作。但是,由于绑定到 dockerd 的 Buildkit 库使用不同的存储组件,所以该驱动未支持某些特性。比如说,使用 docker 驱动构建的镜像直接保存到本地,可以使用 docker images 查看。
2)–driver docker-container,表示使用容器运行 BuildKit 工具,在此容器中执行构建任务。而该构建方式产生的镜像,无法直接通过 docker images 查看,需要指定 –output 选项来导出。

高级功能及特性

多构建实例(使用不同节点来构建镜像)

该特性的用途:通过多构建实例特性,可以在多个主机中并发的构建镜像。

多架构构建(构建多种不同平台的镜像)。

该特性的用途:通过多架构构建,可以 同时 构建出 arm x86 ppc 等等架构的镜像。

它是如何实现:为构建出多平台镜像,它背后使用 QEMU 模拟器进行多个平台的镜像构建;此外,也支持使用多个节点(不同 CPU 架构)来完成多平台构建;

使用注意事项:多架构构建,只能使用 docker-container 驱动。

高级构建选项

通过 docker bake 命令,可以并行构建多个镜像。

应用案例:构建多平台镜像(基础案例)

正如文章开始处的问题,该案例也是我们要完成的事情。在该示例中,我们使用两个节点(arm64 与 amd64)来构建不同平台的镜像。

# 创建构建器实例

docker buildx create --name multi-platform --use \
    --platform linux/amd64 \
    --driver docker-container "build-node-amd64"
    
docker buildx create --name multi-platform --append \
    --platform linux/arm64 \
    --driver docker-container "build-node-arm64"

# 查看并使用我们创建的构建器实例

docker buildx ls
docker buildx use multi-platform

# 执行构建命令

docker buildx build --progress plain --output "type=image,push=false"  \
    --file "/data/cita-monitor/agent/cita_exporter/Dockerfile" \
    --tag citamon/agent-cita-exporter:20.2.2     \
    --platform linux/arm64,linux/amd64 \
    /data/cita-monitor/agent/cita_exporter

在上述命令中,”build-node-amd64″ 与 “build-node-arm64” 是添加到 Docker Context 中的两个主机节点(这里不再赘述 Docker Buildx 的使用方法)。

BUILDPLATFORM and TARGETPLATFORM

通过 Docker Buildx 构建,可以在 Dockerfile 中使用 BUILDPLATFORM and TARGETPLATFORM 这两个变量。BUILDPLATFORM 为执行构建任务的平台,通常是 linux/amd64(因为我们一般在 x86 平台上构建);TARGETPLATFORM 为目标平台,可能是 linux/arm64、linux/amd64(即我们构建产生这些平台的镜像)。

附加说明

Docker Compose 也支持 buildx 构建:
Use buildx build linux/arm64 in docker-compose file – Stack Overflow
Compose file version 2 reference | Docker Documentation

常见问题汇总

auto-push is currently not implemented for docker driver

buildx: auto-push is currently not implemented for docker driver · Issue #4991 · docker/for-win

问题描述:执行 docker buildx 时产生如下错误:

# docker buildx build --push \
    --platform linux/arm/v7,linux/arm64/v8,linux/amd64 \
    --tag your-username/multiarch-example:buildx-latest \
    ./
auto-push is currently not implemented for docker driver

问题原因:默认的 docker 驱动不支持 auto-push 操作。因此在使用多平台构建时,需要先创建构建实例,使用 docker container 驱动。

解决方法:docker buildx create --use --name build --node build --driver-opt network=host

multiple platforms feature is currently not supported for docker driver

在执行 docker buildx build 命令时,产生如下错误:

# docker buildx build \
>     --tag 0xa0000/buildx-example:latest \
>     --platform linux/amd64,linux/arm64 .
[+] Building 0.0s (0/0)
error: multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")

unable to upgrade to tcp, received 200

我们使用 Nginx 反向代理 Docker 连接,导致无法升级为 TCP 连接。

相关链接

平台字段的命名规范(platform)

The formatting for the platform specifier is defined in
https://github.com/containerd/containerd/blob/v1.2.6/platforms/platforms.go#L63

关于 docker buildx 命令手册

docker buildx | Docker Documentation

参考文献

Docker Buildx | Docker Documentation
docker buildx build | Docker Documentation