Upcoming changes to container registries (V2 schema 1)

Updated 18 Jul 2022

Starting 11th July 2022 Red Hat intends to make some changes to the way the Docker Registry HTTP API at registry.redhat.io and registry.access.redhat.com is handled. Customers consuming container images from either registry by sha256 digest, rather than by tag, will need to use digests for V2 Schema 2 manifests. Customers using their own tooling around container images will need to adapt to these changes by that date.

The changes relate to the Content from docs.docker.com is not included.deprecated Docker V2 Schema 1 image manifest format, and to the technology we use to provide the container registry API.

Timeline

On 11th July 2022, digests for V2 Schema 1 image manifests will no longer be supported for image pulls. Such by-digest requests will receive a 404 (not found) response with data like this:

{"errors":[{"code":"UNSUPPORTED","message":"V2 schema 1 manifest digests are no longer supported for image pulls. Use the equivalent V2 schema 2 manifest digest instead. For more information, see https://access.redhat.com/articles/6138332"}]}

Then, in the weeks following 11th July 2022, requests to both the registry.redhat.io and registry.access.redhat.com API endpoints will start to be satisfied behind the scenes using the Quay.io Container Registry. This change is intended to be transparent to customers already using V2 schema 2 manifests. All content will continue to be served from the same domains, so no firewall changes are necessary.

Actions required

If you are currently using digests to retrieve V2 Schema 1 image manifests you will need to take action before 11th July 2022, preferably by using V2 Schema 2 image manifest digests instead, or alternatively by using tags. You may otherwise experience:

- failure to deploy services
- failure to restart existing services
- failure to scale up existing deployments

To know whether a digest you currently use is for a V2 Schema 1 image manifest, inspect the schemaVersion field of the retrieved image manifest. For example, this command shows that the digest is for a V2 Schema 2 image manifest:

$ skopeo inspect --raw docker://registry.redhat.io/rhel7/etcd@sha256:f3de7e64562d2237afff095c4fc6937d64092343072834dcb9319129b8f4b60a | jq .schemaVersion
   2

A comma-separated values (CSV) file is attached to aid in converting any recorded V2 schema 1 manifest digests to the equivalent V2 schema 2 manifest digests. Each row refers to a single image. Fields include the repository name, the image tag name, the V2 schema 1 digest, and the V2 schema 2 digest which should be used instead.

If you are using a manifest digest which does not appear in the file, please verify (using skopeo) whether you are using a V2 schema 1 manifest digest. If so, you can either record the V2 schema 2 manifest digest using the tag you originally used to get the V2 schema 1 manifest digest, or, if the image was created after the mapping file was produced, wait for the mapping file to be updated. This file will be updated to include content produced up to 11th July 2022 on or shortly after that date. After this date, please ensure only to record V2 Schema 2 manifest digests.

Additional information

Registry client software that supports V2 Schema 1 but not V2 Schema 2 will also see a small change to the content of the image manifest: the repository value will not match the name of the repository used to fetch the manifest.

One easy way to convert the v1 schemas is during the push to add -f, --format string; Manifest type (oci, v2s2, or v2s1) to use in the destination (default is manifest type of source, with fallbacks) and select v2s2 to create the schema 2 image manifest.

Article Type

General