[release/2.7] Adding deprecated schema v1 page

[adrian-plata]

No description provided.

[GordonTheTurtle]

Please sign your commits following these rules:
https://github.com/moby/moby/blob/master/CONTRIBUTING.md#sign-your-work
The easiest way to do this is to amend the last commit:

$ git clone -b "release/2.7" git@github.com:adrian-plata/distribution.git somewhere
$ cd somewhere
$ git rebase -i HEAD~842359065760
editor opens
change each 'pick' to 'edit'
save the file and quit
$ git commit --amend -s --no-edit
$ git rebase --continue # and repeat the amend for each commit
$ git push -f

Amending updates the existing PR. You DO NOT need to open a new one.

[adrian-plata]

@thaJeztah, @andrewhsu, and @tonistiigi PTAL. Are there any additional things to add to this list?

[dmcgowan]

I would mention that it can be done by downloading the manifest, converting to schema 2, then uploading. Or simply by doing a docker pull then docker push.

[adrian-plata]

something like "Updating an image manifest from schema 1 to schema 2 is done by downloading the manifest, convert it from schema 1 to schema 2, and then uploading it.

You can also run docker pull and then docker push. This will update the
image to schema 2. "?

[thaJeztah]

Having a practical example of how to do this would be good yes. Something like;

The easiest way to upgrade an image from image manifest version 2, schema 1 to image manifest version 2, schema 2 is to docker pull the image, and docker push the image with a current version of Docker. Doing so will automatically convert the image to use the latest specification.

We may want to add a note/warning that that doesn't upgrade outdated images (which may container vulnerabilities). Something along the lines of;

Note: converting an image to image manifest version 2, schema 2 converts the manifest
format, but does not update the contents of the image itself. Images using manifest version 2, schema 1
are likely created a long time ago and may contain unpatched vulnerabilities.
We recommend looking for an alternative image or, if this is an image you maintain, rebuilding the image.
To update an image, and patch vulnerabilities, the image has to be re-built using an up-to-date base
image. Refer to the update FROM statement section below for more details.

[thaJeztah]

Left some thoughts/suggestions

[thaJeztah]

Should we make this Update deprecated image manifest version 2, schema 1 images to schema 2 ?

[thaJeztah]

I feel there's something missing on this page (some introduction sentence explaining that image manifest v2, schema 1 is deprecated.

@dmcgowan should there be a deprecation note on https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-1.md ?

[thaJeztah]

Having a practical example of how to do this would be good yes. Something like;

The easiest way to upgrade an image from image manifest version 2, schema 1 to image manifest version 2, schema 2 is to docker pull the image, and docker push the image with a current version of Docker. Doing so will automatically convert the image to use the latest specification.

We may want to add a note/warning that that doesn't upgrade outdated images (which may container vulnerabilities). Something along the lines of;

Note: converting an image to image manifest version 2, schema 2 converts the manifest
format, but does not update the contents of the image itself. Images using manifest version 2, schema 1
are likely created a long time ago and may contain unpatched vulnerabilities.
We recommend looking for an alternative image or, if this is an image you maintain, rebuilding the image.
To update an image, and patch vulnerabilities, the image has to be re-built using an up-to-date base
image. Refer to the update FROM statement section below for more details.

[thaJeztah]

LGTM

but perhaps @dmcgowan can fact-check the correct naming of the schemas

[dmcgowan]

LGTM

[dmcgowan]

vndr and static checking need to be fixed, can be done separately

[andrewhsu]

For use in moby/moby#39736