Zenn
🐳

Docker HubにOCIイメージをPushする際の不具合と回避策

2021/07/18に公開
Docker
podman
buildah
skopeo
OCI
tech

Docker HubにOCIイメージをPushする際の不具合と回避策

不具合の内容

Podman / Buildah でビルドしたコンテナイメージはデフォルトでOCI Image（以後、OCIイメージ）になっています。

このOCIイメージをコンテナレジストリであるDocker HubにPushすると、各TAGのDIGEST、OS/ARCH、LAST PULL、COMPRESSED SIZEが表示されない不具合があります。

Docker Hubのバグ報告を受け付けるGitHubリポジトリでは以前からIssueが上がっていますがまだ未対応の状態です。

https://github.com/docker/hub-feedback/issues/1871

そのため、現時点（2021/7/18、時点）ではDocker社の対応が完了するまで下記のワークアラウンドを行う必要があります。

追記（2024/4/22）
下記のIssueによるとDocker Hubに更新があり、問題は解決しました。
https://github.com/docker/roadmap/issues/262
過去にPushしたイメージは自動で更新されず、更新するには再度Pushする必要があります。

ワークアラウンド

Buildah（またはPodman）でコンテナをビルドする際に、--format dockerオプションを付けてイメージを作成します。

Buildahのドキュメントより抜粋（buildah budの--formatオプションについて）

--format

Control the format for the built image's manifest and configuration >data. Recognized formats include oci (OCI image-spec v1.0, the default) >and docker (version 2, using schema format 2 for the manifest).

Note: You can also override the default format by setting the >BUILDAH_FORMAT environment variable. export BUILDAH_FORMAT=docker

--formatオプションをつけて明示的にフォーマットを指定することで、OCIイメージまたはDocker Image Manifest V 2, Schema 2（以後、Dockerイメージ）でコンテナを作成することができます。

再現テスト

2種類のコンテナイメージ（oci/docker）を作成し、Docker HubにPushして結果を確認します。以降の作業はContainer ToolsのPodman/Buildah/Skopeoを使用します。

実行元のOS情報、Container Toolsの各バージョン
$ cat /proc/version
Linux version 5.12.15-300.fc34.x86_64 (mockbuild@bkernel01.iad2.fedoraproject.org) (gcc (GCC) 11.1.1 20210531 (Red Hat 11.1.1-3), GNU ld version 2.35.1-41.fc34) #1 SMP Wed Jul 7 19:46:50 UTC 2021
$ podman --version
podman version 3.2.3
$ buildah --version
buildah version 1.21.2 (image-spec 1.0.1-dev, runtime-spec 1.0.2-dev)
$ skopeo --version
skopeo version 1.3.1
コンテナイメージの作成
$ cat << EOF > Containerfile
FROM registry.access.redhat.com/ubi8-micro
LABEL description="format test"
EOF
$ buildah bud -t format-test:oci .
$ buildah bud -t format-test:docker --format docker .
$ buildah images
REPOSITORY                                  TAG               IMAGE ID       CREATED         SIZE
localhost/format-test                       docker            0ca3a2a7674a   7 seconds ago   38.9 MB
localhost/format-test                       oci               751e9ba32320   8 seconds ago   38.9 MB

コンテナイメージの内容確認

Skopeoを使って作成した2種類のコンテナイメージの情報を出力します

OCIイメージ
$ skopeo inspect containers-storage:localhost/format-test:oci --raw | jq .
{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:751e9ba32320cfcf6e559dee445f7686cc16a357238498e7e971dbb0b1006492",
    "size": 1609
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "digest": "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
      "size": 1024
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "digest": "sha256:a80a43bc8da68242f26b79784f7b663c5332487735fa5c127f29e5790cb1b7a0",
      "size": 38910976
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "digest": "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
      "size": 1024
    }
  ]
}
Dockerイメージ
$ skopeo inspect containers-storage:localhost/format-test:docker --raw | jq .
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 3208,
    "digest": "sha256:0ca3a2a7674a211a874bd48c65bab8c9fcc6274f6dad0de3981fef12fce4eedd"
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar",
      "size": 1024,
      "digest": "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
    },
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar",
      "size": 38910976,
      "digest": "sha256:a80a43bc8da68242f26b79784f7b663c5332487735fa5c127f29e5790cb1b7a0"
    },
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar",
      "size": 1024,
      "digest": "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
    }
  ]
}

OCIイメージ（vnd.oci.image.）とDockerイメージ（vnd.docker.image.）で情報が異なることが確認できます。

Docker HubへPush

公開用のタグ付け、docker.ioにログイン後、イメージのPushを行います

公開用のタグ付け → docker.ioにログイン → イメージのPush
$ podman tag format-test:oci docker.io/tnk4on/format-test:oci
$ podman tag format-test:docker docker.io/tnk4on/format-test:docker
$ podman login docker.io
$ podman push docker.io/tnk4on/format-test:oci
$ podman push docker.io/tnk4on/format-test:docker

ociの方は詳細が表示されていないことが確認できます。

参考：Quay.io へPushした場合

Red Hatがホストするコンテナレジストリの Quay Container Registry / Quay.ioへPushした場合はOCI/Dockerイメージのどちらでも問題なく情報が表示されます。

公開用のタグ付け → quay.ioにログイン → イメージのPush
$ podman tag format-test:oci quay.io/tnk4on/format-test:oci
$ podman tag format-test:docker quay.io/tnk4on/format-test:docker
$ podman login quay.io
$ podman push quay.io/tnk4on/format-test:oci
$ podman push quay.io/tnk4on/format-test:docker

Quay.ioのFAQより抜粋

Can I use Quay for free?
Yes! We offer unlimited storage and serving of public repositories. We strongly believe in the open source community and will do what we can to help!

Quayを無料で利用できますか？
はい！無料でご利用いただけます。私たちは無制限のストレージとパブリックリポジトリの提供を行っています。私たちはオープンソースコミュニティを強く信じており、できる限りの支援を行います。

別のワークアラウンド（Push時にformatを指定する）

コンテナ作成時ではなく、Push時にformatを指定することでも対応が可能です。
Podman（またはBuildah）でPush時に--format v2s2を指定します。

Push時に--format v2s2を指定
$ podman tag docker.io/tnk4on/format-test:oci docker.io/tnk4on/format-test:v2s2
$ podman push docker.io/tnk4on/format-test:v2s2 --format v2s2

pushしたイメージの情報をskopeoで確認
$ skopeo inspect docker://docker.io/tnk4on/format-test:v2s2 --raw | jq .
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 1609,
    "digest": "sha256:751e9ba32320cfcf6e559dee445f7686cc16a357238498e7e971dbb0b1006492"
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 42,
      "digest": "sha256:4ca545ee6d5db5c1170386eeb39b2ffe3bd46e5d4a73a9acbebc805f19607eb3"
    },
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 15059460,
      "digest": "sha256:bdded0c91b7a97caa17095acfbee6a8d3c43f9c84d2cb75caf3a4c3e3707a837"
    },
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 42,
      "digest": "sha256:4ca545ee6d5db5c1170386eeb39b2ffe3bd46e5d4a73a9acbebc805f19607eb3"
    }
  ]
}

まとめ

Docker HubにOCIイメージをPushした場合の不具合と回避策（ワークアラウンド2種）について解説しました。Docker社が対応を行うまでは引き続きDockerイメージの併用が必要となります。OCIイメージを中心に作業を行なっているとDocker Hubを使う場合に意外に手間がかかります。GitHub ActionsでBuildahを使ったビルドができるようになっていますが、この不具合のためデフォルトのフォーマットはOCIイメージではなくDockerイメージとなっています。OCIイメージの利用が進んでいますので、Docker社には早期に対応して欲しいところです。

参考

Discussion