Docker Buildx 版本更新引起的镜像血案
❝本文转自 Nova Kwok 的博客，原文：https://nova.moe/docker-attestation/，版权归原作者所有。欢迎投稿，投稿请添加微信好友：cloud-native-yang
你有没有遇到过这种情况，对于一个镜像来说，它可以正常 pull 下来：
$ docker pull knatnetwork/github-runner-amd64:focal-2.301.1
focal-2.301.1: Pulling from knatnetwork/github-runner-amd64
846c0b181fff: Pull complete
588b3eef3b63: Pull complete
189ea0ac146f: Pull complete
4f4fb700ef54: Pull complete
546945707c6e: Pull complete
71464c2d54c9: Pull complete
1c4efc443e6a: Pull complete
21bbc223ea9a: Pull complete
Digest: sha256:6b5b4aa94f8c1e781785e831d18d7ccc1a0de7d70d63b1afd4df3cce27ddd53f
Status: Downloaded newer image for knatnetwork/github-runner-amd64:focal-2.301.1
docker.io/knatnetwork/github-runner-amd64:focal-2.301.1但是如果你想 inspect 它的 manifest 会发现 no such manifest。
$ docker manifest inspect knatnetwork/github-runner-amd64:focal-2.301.1
no such manifest: docker.io/knatnetwork/github-runner-amd64:focal-2.301.1我怎么会遇到这么个鬼问题呢？
在 2022 年 4 月，我开源了 GitHub Runner， 相关的文章是：开源 Github Actions Self-Hosted Runner[1]，由于这个 Runner 的 Image 就是在 GitHub Actions 上面构建的，且为了提供多架构的支持（ARM64 和 AMD64） 并为了保证构建速度，整个构建工作分为了以下几步：
第一阶段同时开两个 Runner 分别构建
knatnetwork/github-runner-amd64:focal-2.301.1和knatnetwork/github-runner-arm64:focal-2.301.1的镜像在上面两个 Runner 完成之后通过操作 manifest 的方式合并为一个叫
knatnetwork/github-runner:focal-2.301.1的 Multi-Arch 镜像
这么做一直没有问题，直到几天前在最后一步合并镜像的时候遇到了第一个报错：https://github.com/knatnetwork/github-runner/actions/runs/3954481625/jobs/6776296661
failed to put manifest docker.io/knatnetwork/github-runner:focal-2.301.1: errors:
manifest blob unknown: blob unknown to registry奇怪，难道是因为 GitHub 有一些 Step 没有升级么？
想到之前看到过一堆 The set-output command is deprecated and will be disabled soon.，于是尝试升级了一下 docker/login-action 和 docker/build-push-action 等，然后重新触发任务，结果依然是在合并镜像的时候报错，不过这一次报错内容还不太一样，是：
Run docker manifest create knatnetwork/github-runner:focal-2.301.1 --amend knatnetwork/github-runner-amd64:focal-2.301.1 --amend knatnetwork/github-runner-arm64:focal-2.301.1
docker.io/knatnetwork/github-runner-amd64:focal-2.301.1 is a manifest list
基于个人的经验，如果同一段代码之前能跑，现在突然不能跑了，在这个情况下，一般有如下可能：
GitHub Runner 环境的 Docker 版本变了
docker/login-action和docker/build-push-action中有什么变更，或者这些 step 使用的组件（比如 buildx）有啥变更DockerHub/GHCR 出问题了
我们先排除最后一个可能，因为过了两天之后再重试发现问题依旧，且没有看到有大量对于这两个服务不可用的反馈，所以只剩下前两个可能。
GitHub Runner Docker
先看看是不是 Docker 有啥 Breaking change 导致的问题，最后一次成功的 Action 是：https://github.com/knatnetwork/github-runner/actions/runs/3736662591，调试信息中：
Client:
Version: 20.10.21+azure-2
API version: 1.41
Go version: go1.18.9
Git commit: baeda1f82a10204ec5708d5fbba130ad76cfee49
Built: Tue Oct 25 17:53:02 UTC 2022
OS/Arch: linux/amd64
Context: default
Experimental: true
Server:
Engine:
Version: 20.10.21+azure-2
API version: 1.41 (minimum version 1.12)
Go version: go1.18.9
Git commit: 3056208812eb5e792fa99736c9167d1e10f4ab49
Built: Tue Oct 25 11:44:15 2022
OS/Arch: linux/amd64
Experimental: false第一次失败开始的 Action：https://github.com/knatnetwork/github-runner/actions/runs/3954481625/jobs/6776269393 ，调试信息中：
Client:
Version: 20.10.22+azure-1
API version: 1.41
Go version: go1.18.9
Git commit: 3a2c30b63ab20acfcc3f3550ea756a0561655a77
Built: Thu Dec 15 15:37:38 UTC 2022
OS/Arch: linux/amd64
Context: default
Experimental: true
Server:
Engine:
Version: 20.10.22+azure-1
API version: 1.41 (minimum version 1.12)
Go version: go1.18.9
Git commit: 42c8b314993e5eb3cc2776da0bbe41d5eb4b707b
Built: Thu Dec 15 22:17:04 2022
OS/Arch: linux/amd64
Experimental: false看上去确实有一些版本升级，不过阅读了 https://docs.docker.com/engine/release-notes/#201022 之后发现基本只有点 Patch ，没有什么足以引起这种问题的更新。
那么现在压力就来到了第二个，即 「docker/login-action 和 docker/build-push-action 中有什么变更，或者这些 step 使用的组件（比如 buildx）有啥变更」。
Manifest
在继续调查前我们先看一下上面的报错是个什么情况，为什么镜像能拉，但是 manifest 看不了，难道拉镜像之前不需要看 manifest 么？
Docker 用来查看 manifest 的指令是 docker manifest inspect ，但是这个指令没有类似用于调试的 -v 的选项，所以如果看到了 no such manifest，那你也没法知道背后出了啥问题，不过考虑到 manifest 就一个 JSON 文件，所以肯定是有 Docker Hub 的 API 可以查询的，于是立即上网梭了一个脚本出来：
#!/bin/sh
ref="${1:-library/ubuntu:latest}"
sha="${ref#*@}"
if [ "$sha" = "$ref" ]; then
sha=""
fi
wosha="${ref%%@*}"
repo="${wosha%:*}"
tag="${wosha##*:}"
if [ "$tag" = "$wosha" ]; then
tag="latest"
fi
api="application/vnd.docker.distribution.manifest.v2+json"
apil="application/vnd.docker.distribution.manifest.list.v2+json"
token=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:${repo}:pull" \
| jq -r '.token')
curl -H "Accept: ${api}" -H "Accept: ${apil}" \
-H "Authorization: Bearer $token" \
-s "https://registry-1.docker.io/v2/${repo}/manifests/${sha:-$tag}" | jq .❝来源：https://stackoverflow.com/questions/57316115/get-manifest-of-a-public-docker-image-hosted-on-docker-hub-using-the-docker-regi
然后找了个正常的镜像试了一下，输出结果类似是这样的，和用 docker manifest inspect 结果一致：
{
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"schemaVersion": 2,
"config": {
"mediaType": "application/vnd.docker.container.image.v1+json",
"digest": "sha256:19bf2d0d0a8aaf27988db772ff6ba4044405447535762bfc9ba451d0d84f0a18",
"size": 4995
},
"layers": [
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"digest": "sha256:846c0b181fff0c667d9444f8378e8fcfa13116da8d308bf21673f7e4bea8d580",
"size": 28576882
},
...
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"digest": "sha256:74b36662af5e651ae3390a6cf13fcaa8fca08fea5bd711ddbed60bf9e5924654",
"size": 932
}
]
}于是立即看了一下有问题的镜像，结果是这样的：
{
"errors": [
{
"code": "MANIFEST_UNKNOWN",
"message": "OCI index found, but accept header does not support OCI indexes"
}
]
}从 OCI Image Index Specification[2] 文档中我们知道 manifest 有很多类型，大家一般在用的是 application/vnd.docker.distribution.manifest.v2+json，如果是一个 multi-arch 的镜像的话可能输出结果是这样的：
{
"manifests": [
{
"digest": "sha256:93d5a28ff72d288d69b5997b8ba47396d2cbb62a72b5d87cd3351094b5d578a0",
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"platform": {
"architecture": "amd64",
"os": "linux"
},
"size": 528
},
{
"digest": "sha256:176bc6c6e93528f4b729fae1f8dbd70b73861264dba3a3f64c49c92e1f42a5aa",
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"platform": {
"architecture": "s390x",
"os": "linux"
},
"size": 528
}
],
"mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
"schemaVersion": 2
}这里它的格式是 application/vnd.docker.distribution.manifest.list.v2+json ，也就是上面脚本中请求的时候同时带上了以下两个 header 的原因。
api="application/vnd.docker.distribution.manifest.v2+json"
apil="application/vnd.docker.distribution.manifest.list.v2+json"但是这里根据提示 OCI index found ，我们猜测可能实际的 manifest 格式和上面两个都不匹配，于是加入了以下两个新的 Header 上去，显式定义一下我们还接受 application/vnd.oci.image.index.v1+json 这个格式：
api_old="application/vnd.oci.image.manifest.v1+json"
api_oldi="application/vnd.oci.image.index.v1+json"很快，我们就看到有问题的镜像也能返回了，数据是这样的：
{
"mediaType": "application/vnd.oci.image.index.v1+json",
"schemaVersion": 2,
"manifests": [
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:73809677ff2aff4bee611f1da7cdc9b8825c5729d2aab4c88b683cfa0e5fc7f0",
"size": 1817,
"platform": {
"architecture": "amd64",
"os": "linux"
}
},
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:f47cf60d8b8da4e0f5040071b78ddb41f0ae160da6b1be7ddcba03a5c0bf9b3d",
"size": 567,
"annotations": {
"vnd.docker.reference.digest": "sha256:73809677ff2aff4bee611f1da7cdc9b8825c5729d2aab4c88b683cfa0e5fc7f0",
"vnd.docker.reference.type": "attestation-manifest"
},
"platform": {
"architecture": "unknown",
"os": "unknown"
}
}
]
}这就很有意思了，我用：
- name: Build and push AMD64 Version
uses: docker/build-push-action@v2
with:
context: ./amd64/
file: ./amd64/Dockerfile
platforms: linux/amd64
push: true
tags: |
knatnetwork/github-runner-amd64:focal-${{ github.event.inputs.github-runner-version }}构建出来的镜像为什么 manifests 是个数组（像是一个 multi-arch 的镜像），而且第二个 platform 还是 unknown？
所以应该也是这个原因导致了：docker.io/knatnetwork/github-runner-amd64:focal-2.301.1 is a manifest list 这个报错， 操作 manifest 合并镜像不能把两个多 Arch 镜像合并。
但为什么？
attestation manifest
在上文的输出中我们看到了一个关键信息："vnd.docker.reference.type": "attestation-manifest"，经过搜索看到了这个文档：Attestation storage | Docker Documentation[3]
❝Buildkit supports creating and attaching attestations to build artifacts. These attestations can provide valuable information from the build process, including, but not limited to: SBOMs, SLSA Provenance, build logs, etc.
哦？是 Buildkit 搞的事情？
于是开始检查最后一次成功的 Buildx 版本，发现是：
github.com/docker/buildx 0.9.1+azure-2 ed00243a0ce2a0aee75311b06e32d33b44729689再看看第一次失败的 Buildx 版本：
github.com/docker/buildx 0.10.0+azure-1 876462897612d36679153c3414f7689626251501版本从 0.9.1 升级到了 0.10.0 ，这个时候回顾一下 docker/build-push-action 的 Release Note[4] 中有这么一段话：
❝Buildx v0.10 enables support for a minimal SLSA Provenance attestation, which requires support for OCI-compliant multi-platform images. This may introduce issues with registry and runtime support (e.g. GCR and Lambda). You can optionally disable the default provenance attestation functionality using provenance: false.
很快我们就知道这里的问题在于 Buildx 从 0.10 开始就默认加入了这个叫做 SLSA Provenance attestation 的东西，也就是我们看到的 manifest 中底下那个 "vnd.docker.reference.type": "attestation-manifest" 的内容，这么做对于直接构建的 Multi-Arch 镜像没有影响，对于单架构镜像而言一般也没有影响（虽然会在 docker manifest inspect 的时候报错），但是一旦有了像我这样多个并行构建，后期操作 manifest 的合并的操作的时候，就会导致 docker.io/knatnetwork/github-runner-amd64:focal-2.301.1 is a manifest list 类似这样的错误。
如果你想了解更多关于 Build attestations 的事情，可以从 Docker 的文档：Build attestations | Docker Documentation[5] 开始阅读，简单来说分为 SBOM 和 Provenance：
❝Build attestations describe how an image was built, and what it contains. The attestations are created at build-time by BuildKit, and become attached to the final image as metadata.
Two types of build annotations are available:
Software Bill of Material (SBOM): list of software artifacts that an image contains, or that were used to build the image.
Provenance: how an image was built.
既然问题很清晰了，那解决问题的思路也明确了，在 docker/build-push-action 加入以下两行即可：
provenance: false
sbom: false构建后我们再次通过脚本确认，发现 manifest 已经正常，如下：
{
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"schemaVersion": 2,
"config": {
"mediaType": "application/vnd.docker.container.image.v1+json",
"digest": "sha256:82da6a4f14803932bfece329e5d2592b74dbbb65a3c493bb6b459fb8b3a082ff",
"size": 4995
},
"layers": [
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"digest": "sha256:846c0b181fff0c667d9444f8378e8fcfa13116da8d308bf21673f7e4bea8d580",
"size": 28576882
},
...
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"digest": "sha256:8b5ad40966565f7a972b30cf9494aa3600645350952d99f1d442c143a03d2650",
"size": 932
}
]
}而至于一开始遇到的 manifest blob unknown: blob unknown to registry 问题，猜测是由于合并镜像需要在一个 repo 下，逻辑应该是：
knatnetwork/github-runner-amd64:latest和knatnetwork/github-runner-arm64:latest不能合并knatnetwork/github-runner:latest-amd64和knatnetwork/github-runner:latest-arm64可以合并
不过这里似乎也没法解释为什么之前这么做是可以的，如果有读者有了解的话，欢迎在评论区中指出。
总结
总结，为了解决上面两个问题，我分别做了以下调整：
在
docker/build-push-action中显式禁用了 provenance 和 sbom 的输出将 amd64 和 arm64 的镜像改变同 repo 的不同 tag 输出
同时得出一个结论就是：如果你和我一样想后期操作 manifest 来调整镜像的话，一定要注意 buildx 的这个新特性，要么显式禁用掉，要么考虑修改你的 Dockerfile 们尽量一次通过 buildx 构建成 Multi-Arch 的镜像。
参考资料
Attestation storage | Docker Documentation[6]
Build attestations | Docker Documentation[7]
Attestation storage | Docker Documentation[8]
Releases · docker/build-push-action · GitHub[9]
Action started to push manifest indexes instead of images for a single platform · Issue #755 · docker/build-push-action · GitHub[10]
引用链接
[1]
开源 Github Actions Self-Hosted Runner: https://nova.moe/unleash-github-actions-runner/
[2]OCI Image Index Specification: https://github.com/opencontainers/image-spec/blob/main/image-index.md
[3]Attestation storage | Docker Documentation: https://docs.docker.com/build/attestations/attestation-storage/
[4]Release Note: https://github.com/docker/build-push-action/releases/tag/v3.3.0
[5]Build attestations | Docker Documentation: https://docs.docker.com/build/attestations/
[6]Attestation storage | Docker Documentation: https://docs.docker.com/build/attestations/attestation-storage/
[7]Build attestations | Docker Documentation: https://docs.docker.com/build/attestations/
[8]Attestation storage | Docker Documentation: https://docs.docker.com/build/attestations/attestation-storage/
[9]Releases · docker/build-push-action · GitHub: https://github.com/docker/build-push-action/releases
[10]Action started to push manifest indexes instead of images for a single platform · Issue #755 · docker/build-push-action · GitHub: https://github.com/docker/build-push-action/issues/755
你可能还喜欢
点击下方图片即可阅读
K8s 基于 cgroup 限制资源使用量模型设计与实现
2023-02-01
云原生可观测领域的半壁江山，这次被 Grafana 和 Cilium 给拿下了
2023-01-13
如何配置 Cilium 和 BGP 协同工作？
2023-01-05
云原生是一种信仰
关注公众号
后台回复◉k8s◉获取史上最方便快捷的 Kubernetes 高可用部署工具，只需一条命令，连 ssh 都不需要！
点击 "阅读原文" 获取更好的阅读体验！
发现朋友圈变“安静”了吗？