1. docker buildx build

开启构建任务。

buildx build 命令使用 BuildKit 启动一个构建。这个命令类似于 docker build 命令的 UI，使用相同的标志和参数。

文档中大多数的参数都可以参考 docker build。这里主要描述的新的选项。

1.1. 帮助

# docker buildx build --help

Usage:  docker buildx build [OPTIONS] PATH | URL | -

Start a build

Aliases:
  build, b

Options:
      --add-host strings         Add a custom host-to-IP mapping (host:ip)
      --allow strings            Allow extra privileged entitlement, e.g. network.host, security.insecure
      --build-arg stringArray    Set build-time variables
      --builder string           Override the configured builder instance
      --cache-from stringArray   External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
      --cache-to stringArray     Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
  -f, --file string              Name of the Dockerfile (Default is 'PATH/Dockerfile')
      --iidfile string           Write the image ID to the file
      --label stringArray        Set metadata for an image
      --load                     Shorthand for --output=type=docker
      --network string           Set the networking mode for the RUN instructions during build (default "default")
      --no-cache                 Do not use cache when building the image
  -o, --output stringArray       Output destination (format: type=local,dest=path)
      --platform stringArray     Set target platform for build
      --progress string          Set type of progress output (auto, plain, tty). Use plain to show container output
                                 (default "auto")
      --pull                     Always attempt to pull a newer version of the image
      --push                     Shorthand for --output=type=registry
      --secret stringArray       Secret file to expose to the build: id=mysecret,src=/local/secret
      --ssh stringArray          SSH agent socket or keys to expose to the build (format:
                                 default|<id>[=<socket>|<key>[,<key>]])
  -t, --tag stringArray          Name and optionally a tag in the 'name:tag' format
      --target string            Set the target build stage to build.

1.2. 选项

1.3. 示例

• 构建一个 arm ，arm64 和 amd64 架构的镜像，并 push 到原创镜像仓库

→ docker buildx build -t registry/hello-multi-arch --platform=linux/arm,linux/arm64,linux/amd64 . --push

1.3.1. 允许额外的权限（--allow）

--allow=ENTITLEMENT

运行额外的权限权益，可配置的额外权限列表：

• network.host - 允许执行时使用主机网络
• security.insecure - 允许在没有沙盒的情况运行，详见 related Dockerfile extensions.

For entitlements to be enabled, the buildkitd daemon also needs to allow them with --allow-insecure-entitlement (see create --buildkitd-flags)

开启额外权限配置需要 buildkitd 进程在创建时添加选项 --allow-insecure-entitlement ，想见 docker buildx create --buildkitd-flags

示例

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .

1.3.2. 设置构建时选项 (--build-arg)

参考 docker build 命令

还有一些有用的内置参数，如:

• BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool> 触发上下文时，保留 .git 目录
• BUILDKIT_INLINE_BUILDINFO_ATTRS=<bool> 镜像配置中是否包含内联构建信息属性
• BUILDKIT_INLINE_CACHE=<bool> 镜像配置中是否包含内联缓存元数据
• BUILDKIT_MULTI_PLATFORM=<bool> 选择确定性输出，不管是否多平台输出

$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .

更多构建时参数参考 dockerfile frontend docs.

1.3.3. 额外的构建上下文 (--build-context)

--build-context=name=VALUE

通过配置来指定额外的构建上下文。在 Dockerfile 中可以被 FROM name 或 --from-name 使用

当 Dockerfile 中定义了一个同名阶段将会被覆盖。

值可以是本地源目录，容器镜像（通过 docker-image:// 前缀），Git 或 HTTP 地址

把 alpine:latest 替换成一个固定的镜像：

$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .

Expose a secondary local source directory:

$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .

FROM alpine
COPY --from=project myfile /

1.3.4. 构建时使用外部缓存源 (--cache-from)

--cache-from=[NAME|type=TYPE[,KEY=VALUE]]

构建时使用外部缓存源，支持的类型有 registry, local 和 gha。

• registry source can import cache from a cache manifest or (special) image configuration on the registry.
• local source can import cache from local files previously exported with --cache-to.
• gha source can import cache from a previously exported cache with --cache-to in your GitHub repository

如果没有指定， registry exporter is used with a specified reference.

当前，docker 驱动只支持通过远程 registry 仓库导入构建缓存

$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .

更多关于缓存导出和可用属性的信息: https://github.com/moby/buildkit#export-cache

1.3.5. 将构建缓存到处到一个额外的目标中 (--cache-to)

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

将构建缓存到处到一个额外的目标中，支持 registry, local, inline and gha.

• registry 类型 导出构建缓存为缓存的 manifest 到到远程仓库中
• local 类型 导出缓存到本地目录
• inline 类型 将缓存的元数据写到镜像配置中。
• gha 类型 通过 Github API 导出 Github Actions Cache service API.

当前，docker 驱动只支持 inline 缓存导出为镜像配置。或者配置 --build-arg BUILDKIT_INLINE_CACHE=1 触发 inline 缓存导出。

属性值：

• mode - 指定导出的缓存有多少 layers 层。min 只到处构建的最后阶段的层，max 会到处所有阶段的层。整个构建过程的元数据都会导出。

$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .

更多缓存导出可用属性: https://github.com/moby/buildkit#export-cache

1.3.6. 导入单平台的镜像 docker images (--load)

--load 是 --output=type=docker 的简写。

会自动加载单平台构建的镜像，即可以通过 docker images 看到的镜像。

1.3.7. 将构建结果的元数据存储到文件中 (--metadata-file)

通过 --metadata-file 标签，可以将构建输出的元数据保存到文件中，例如镜像 digest。

元数据将会使用 JSON 对象保存到指定的文件中，指定的文件或目录必须已经存在并且具有可写的权限。

$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json

{
  "containerimage.buildinfo": {
    "frontend": "dockerfile.v0",
    "attrs": {
      "context": "https://github.com/crazy-max/buildkit-buildsources-test.git#master",
      "filename": "Dockerfile",
      "source": "docker/dockerfile:master"
    },
    "sources": [
      {
        "type": "docker-image",
        "ref": "docker.io/docker/buildx-bin:0.6.1@sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0",
        "pin": "sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0"
      },
      {
        "type": "docker-image",
        "ref": "docker.io/library/alpine:3.13",
        "pin": "sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c"
      }
    ]
  },
  "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
  "containerimage.descriptor": {
    "annotations": {
      "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
      "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
    },
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 506
  },
  "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}

1.3.8. 设置构建结果的输出方式 (-o, --output)

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

设置构建结果的输出方式。 在使用 docker build 构建时，构建输出的结果会创建一个镜像，并到出道 docker images 视图中可查看。buildx 允许构建的结果可配置，例如 oci 镜像的 tar 包，registry 仓库等等。

Buildx 在使用 docker 驱动时至支持 local 本地，导出为 tarball和导出为 image 镜像。docker-container 驱动支持所有的导出方式。

如果 dest 配置了 path 路径值，buildx 将使用 local 本地导出到目的路径。如果 dest 配置的是 “-”，buildx 会使用 tar 类型导出，然后输出到 stdout。

$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - - > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry

支持的导出类型：

local

使用 local 导出类型，会将所有的构建结果文件报错到目标路径中（客户端），文件的所属用户就是当前的用户。在多平台构建时，所有的构建结果会分别保存在不同平台的子目录中。

属性值：

• dest - 构建结果保存的目的目录

tar

使用 tar 导出类型，会将所有的构建结果文件打包成一个单独的 tarball（客户端）。当使用多平台构建时，所有的构建结果会分别保存在不同平台的子目录中。

属性值：

• dest - 构建结果保存的目的目录。当配置时 “-” 时，会输出到 stdout 标准输出

oci

使用 oci 导出类型，会将所有的构建结果镜像或 manifest 清单保存为 OCI 镜像 layout 的 tarball（客户端）

属性值：

• dest - 构建结果保存的目的目录。当配置时 “-” 时，会输出到 stdout 标准输出

docker

使用 docker 导出类型会导出单平台镜像为 tarball（客户端），该导出的 tarball 是符合 OCI 标准的。

当前，使用 docker 导出类型不支持导出多平台镜像。大多数情况下多平台镜像会直接 push 推送到远程仓库 registry。

属性值：

• dest - 如果配置了 dest 路径会导出为一个 tarball，如果没有指定会自动加载到当前的 docker 实例中。
• context - 导入结果到一个 docker context 上下文中（可使用 docker context ls 查看）

image

使用 image 导出类型，会将构建结果保存到一个 image 镜像或 manifest list。当使用 docker 驱动时，镜像会自动添加到 docker images 视图中。也可以选择指定属性，将镜像自动 push 到远程 registry 仓库。

属性值：

• name - 指定新镜像的名称
• push - boolean 类型，自动 push 镜像。

registry

使用 registry 导出类型，就是 type=image,push=true 的简写。

1.3.9. 设置构建的目标平台< (--platform)

--platform=value[,value]

设置构建的目标平台。Dockerfile 中所有的 FROM 命令在构建 --platform 指定的平台时，会自动拉取对应的基础镜像，并构建对应平台的镜像。默认是当前 Buildkit 进程运行系统的平台。

当 buildx 使用 docker-container 驱动时，这个可以接受多个基于逗号分隔的值。当有多个值时，会构建所有指定的多个不同平台的镜像，然后聚会成一个单独的 manifest 清单。

当 Dockerfile 需要运行 RUN 时，构建器需要支持在指定的平台运行。在清理步骤时，只需要你系统的架构平台执行 RUN 命令就可以了。

如果的 OS 内核支持 binfmt_misc二级架构的启动器， buildx 将自动调用他们。Docker Desktop 版本默认就是基于 binfmt_misc 自动配置 arm64 和 arm 架构。可以通过 docker buildx inspect --bootstrap 查看你当前的 builder 构建器有哪些平台支持。

在 Dockerfile 中，可以通过 TARGETPLATFORM构建参数来访问当前平台的信息。请查阅 docker build documentation ，获取完整的自动构建是平台的参数。

格式定义参考 containerd source code.

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

1.3.10. 设置进度条信息类型 (--progress)

--progress=VALUE

设置进度条信息类型（支持 auto, plain, tty），使用 plain 来显示容器输出（默认 “auto”）

也可以使用 BUILDKIT_PROGRESS 环境变量来设置值

下面这个示例就是用 plain 来输出构建过程

$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...

1.3.11. 将构建结果 push 到仓库 registry (--push)

将构建结果 push 到仓库 registry 。--push 是--output=type=registry 简写。

1.3.12. 构建过程依赖的密钥 (--secret)

--secret=[type=TYPE[,KEY=VALUE]

暴露构建过程的 secret 密钥。 这个 secret 可以给构建过程中 RUN --mount=type=secret mount 使用。

如果 type 没有设置，会被检查。支持的类型：

file

属性值：

• id - secret 的 ID，默认名称是 src 路径的最后一级名称（basename）
• src, source - Secret 文件名称. 如果没有设置，会使用 id.

# syntax=docker/dockerfile:1.4
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...

$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

env

属性值：

• id - secret 的 ID。默认 env 名称.
• env - Secret 的环境变量。如果没有设置会使用 id。否则，将会查找 src, 如果 id 没有设置，会使用 source 。

# syntax=docker/dockerfile:1.4
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN \
  SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test

$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

1.3.13. 共享内存 /dev/shm 大小 (--shm-size)

格式是 <number><unit>。number 必须大于 0。单位可以是 b (bytes), k (kilobytes), m (megabytes), 或 g (gigabytes)。如果没有配置单位，默认会使用 bytes。

1.3.14. 暴露给构建过程使用的 SSH Agent 的 socket 或 keys (--ssh)

--ssh=default|<id>[=<socket>|<key>[,<key>]]

在 Dockerfile 中指定的一些命令需要 SSH 认证时很有用。（如：git clone 一个私有仓库）

--ssh 将 SSH agent socket 或 keys 暴露给构建过程，用使用 RUN --mount=type=ssh mount.

例如，使用 SSH agent socket 访问 gitlab ：

# syntax=docker/dockerfile:1.4
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.

$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .

1.3.15. 设置 ulimits (--ulimit)

--ulimit 设置 soft 和 harbor limit 配置 <type>=<soft limit>[:<hard limit>],

如：

$ docker buildx build --ulimit nofile=1024:1024 .

注意 如果没有配置 hard limit， 那么 soft limit 的值会同时设置 soft 和 harb 值。如果没有设置 ulimits，会使用进程默认的配置。

2. 参考

• https://docs.docker.com/engine/reference/commandline/buildx_build/
• https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md