Docker Hub won't provide Version 2, Schema 1 Image Manifests (content-type: application/vnd.docker.distribution.manifest.v1+json)

[maltfield]

This is a bug report to notify the Docker Hub team that Docker Hub is returning an error when attempting to download a Version 2, Schema 1 image manifest with the Accept header set to application/vnd.docker.distribution.manifest.v1+json

Problem

The OCI specification requires backwards compatibility such that OCI registries (like Docker Hub) must support Version 2, Schema 1 image manifests

• https://github.com/distribution/distribution/blob/bf9f80eaffb0eabc768762bc4ff03ded277ea594/docs/spec/manifest-v2-1.md

Unfortunately, when asking Docker Hub for a Version2, Schema1 image manifest, it returns the following error

{"errors":[{"code":"MANIFEST_UNKNOWN","message":"OCI manifest found, but accept header does not support OCI manifests"}]}

steps to reproduce

curl -so "token.json" "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/hitch:pull"
token=$(cat token.json | jq -jr ".token")

# get image index
curl -o manifest.json -s -H "Authorization: Bearer ${token}" https://registry-1.docker.io/v2/library/hitch/manifests/1.8.0-1
tail -c100 manifest.json; echo

# download image manifest (hash from image index above) for linux + amd64
curl -s -H 'Accept: application/vnd.docker.distribution.manifest.v1+json' -H "Authorization: Bearer ${token}" https://registry-1.docker.io/v2/library/hitch/manifests/sha256:a640f78641befbe8a4696dde47c51aeadfa1e5e81087a7534982b6bb4d76f54a

example execution

user@disp1427:~$ curl -so "token.json" "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/hitch:pull"
token=$(cat token.json | jq -jr ".token")
user@disp1427:~$ 

user@disp1427:~$ curl -o manifest.json -s -H "Authorization: Bearer ${token}" https://registry-1.docker.io/v2/library/hitch/manifests/1.8.0-1
tail -c100 manifest.json; echo
s":"unknown"},"size":841}],"mediaType":"application\/vnd.oci.image.index.v1+json","schemaVersion":2}
user@disp1427:~$ 

user@disp1427:~$ curl -s -H 'Accept: application/vnd.docker.distribution.manifest.v1+json' -H "Authorization: Bearer ${token}" https://registry-1.docker.io/v2/library/hitch/manifests/sha256:a640f78641befbe8a4696dde47c51aeadfa1e5e81087a7534982b6bb4d76f54a
{"errors":[{"code":"MANIFEST_UNKNOWN","message":"OCI manifest found, but accept header does not support OCI manifests"}]}
user@disp1427:~$ 

Solution

The solution to this ticket is for Docker Hub to check the Accept header of the requests. If the user is asking for a Version 2, Schema 1 Image Manifest, then that's what Docker Hub should return.

If Docker Hub doesn't have a copy of the Version 2, Schema 1 Image Manifest, then it should generate one on-the-fly, as is clearly stated in the Backwards compatibility section of the Version 2, Schema 2 spec:

• https://distribution.github.io/distribution/spec/manifest-v2-2/#backward-compatibility

If the manifest being requested uses the new format, and the appropriate media type is not present in an Accept header, the registry will assume that the client cannot handle the manifest as-is, and rewrite it on the fly into the old format.

[jcarter3]

Given that this format has been deprecated for many years and current tooling is working to remove support, can you explain the use case for requesting a downgrade for the manifest format?

[maltfield]

@jcarter3 The use-case is for backwards compatibility. As defined in the spec for Version 2, Schema 2

• https://distribution.github.io/distribution/spec/manifest-v2-2/#backward-compatibility

If the manifest being requested uses the new format, and the appropriate media type is not present in an Accept header, the registry will assume that the client cannot handle the manifest as-is, and rewrite it on the fly into the old format.

[jcarter3]

What you linked is not the OCI distribution spec, but rather documentation from the CNCF distribution project. That project removed the downgrade functionality 1 year ago, and it seems the documentation was not updated to match. New tools don't support the v1 format, and so I'm curious on the actual use case (not just a theoretical) on needing to pull a deprecated format via what might be unsupported tooling. Mainly: trying to differentiate if this is a theoretical issue, or a "production tooling now breaks" issue.

Version 2 Schema 1 is still served if that is how it was pushed, it is just the downgrade path of Schema 2 -> Schema 1 that might be changing.