如何使用Buildah/Podman为多架构镜像清单添加注解？

问题背景 #

使用Buildah/Podman构建多架构镜像时，无法为多架构镜像清单添加org.opencontainers.image.description注解。当前构建流程如下：

# 构建各架构镜像
buildah bud --platform linux/amd64 -f Dockerfile --format oci --tls-verify=true -t debian-gcc:gcc_bullseye-linuxamd64 /home/runner/work/docker-images/docker-images
buildah bud --platform linux/arm64 -f Dockerfile --format oci --tls-verify=true -t debian-gcc:gcc_bullseye-linuxarm64 /home/runner/work/docker-images/docker-images

# 创建清单并添加各架构镜像
buildah manifest create debian-gcc:gcc_bullseye
buildah manifest add debian-gcc:gcc_bullseye debian-gcc:gcc_bullseye-linuxamd64
buildah manifest add debian-gcc:gcc_bullseye debian-gcc:gcc_bullseye-linuxarm64

# 查看清单
podman manifest inspect debian-gcc:gcc_bullseye

当前生成的是Docker格式清单列表（application/vnd.docker.distribution.manifest.list.v2+json），结构如下：

{
    "schemaVersion": 2,
    "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
    "manifests": [
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "size": 500,
            "digest": "sha256:7dbefc31c7b5f7c4f67f18f92213daec8c48740d9533996363812de4385b9528",
            "platform": {
                "architecture": "amd64",
                "os": "linux"
            }
        },
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "size": 500,
            "digest": "sha256:968fc2d27179baa3e7f8c85c7657659c5c67807dcd002922edce1437d22645f9",
            "platform": {
                "architecture": "arm64",
                "os": "linux"
            }
        }
    ]
}

期望为清单添加顶层注解，最终效果如下：

{
    "schemaVersion": 2,
    "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
    "manifests": [
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "size": 500,
            "digest": "sha256:7dbefc31c7b5f7c4f67f18f92213daec8c48740d9533996363812de4385b9528",
            "platform": {
                "architecture": "amd64",
                "os": "linux"
            }
        },
        {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "size": 500,
            "digest": "sha256:968fc2d27179baa3e7f8c85c7657659c5c67807dcd002922edce1437d22645f9",
            "platform": {
                "architecture": "arm64",
                "os": "linux"
            }
        }
    ],
  "annotations": {
    "org.opencontainers.image.description": "My description ..."
  }
}

尝试使用buildah manifest annotate命令未成功：

buildah manifest annotate --annotation org.opencontainers.image.description="My description ..." debian-gcc:gcc_bullseye debian-gcc:gcc_bullseye

核心原因：Docker格式清单列表（vnd.docker.distribution.manifest.list.v2+json）规范不支持顶层注解，而OCI镜像索引（vnd.oci.image.index.v1+json）支持该特性。

解决方案 #

方法一：直接创建OCI格式镜像索引 #

创建清单时指定--format oci参数，生成支持注解的OCI镜像索引：

# 创建OCI格式的镜像索引
buildah manifest create --format oci debian-gcc:gcc_bullseye

# 添加各架构镜像到索引
buildah manifest add debian-gcc:gcc_bullseye debian-gcc:gcc_bullseye-linuxamd64
buildah manifest add debian-gcc:gcc_bullseye debian-gcc:gcc_bullseye-linuxarm64

# 为索引添加顶层注解
buildah manifest annotate --annotation org.opencontainers.image.description="My description ..." debian-gcc:gcc_bullseye

推送时Buildah/Podman会自动转换为Docker清单列表格式，主流仓库（GitHub Packages、Quay等）均可识别并展示注解。

方法二：转换现有Docker清单为OCI索引 #

若已有Docker格式清单，可先转换为OCI索引再添加注解：

# 导出Docker清单为OCI索引归档文件
podman manifest push --format oci docker://debian-gcc:gcc_bullseye oci-archive:./debian-gcc-index.tar

# 加载归档文件为本地镜像索引
podman load -i ./debian-gcc-index.tar

# 为索引添加注解
buildah manifest annotate --annotation org.opencontainers.image.description="My description ..." debian-gcc:gcc_bullseye

方法三：使用Podman Buildx一键构建 #

Podman 3.0+支持直接构建多架构镜像并添加注解，简化流程：

# 直接构建多架构镜像、添加注解并推送（需提前登录仓库）
podman buildx build --platform linux/amd64,linux/arm64 -t debian-gcc:gcc_bullseye --annotation org.opencontainers.image.description="My description ..." --push .

验证 #

执行以下命令检查注解是否添加成功：

podman manifest inspect debian-gcc:gcc_bullseye | jq '.annotations'

若输出包含org.opencontainers.image.description字段，则说明操作生效。

内容的提问来源于stack exchange，提问作者vookimedlo