faq
faq copied to clipboard
docker-library
Unclear difference between "Shared" and "Simple" tags
Section "What's the difference between "Shared" and "Simple" tags?" is unclear. I read it four times and still not sure if I understand what it means and what type should I choose. Maybe more simple explanation could be written.
So there might need to be more background on what a "manifest list" is, which is basically a reference list of [tag]->[image variant ID], where multiple tags can link to the same image variant.
A simple tag doesn't have a manifest list so you would otherwise need to type say amd64/debian:buster-slim. It doesn't consult a manifest list, it only ever pulls one image.
With a "shared tag" it consults a manifest list so a tag like debian will take extra information given by your local docker environment to identify architecture (amd64) and then other assumed defaults like "latest" so your query is turned into amd64/debian:latest which then expands into amd64/debian:buster as the "latest" tag to Debian means the latest stable release which for them is Buster.
docker tag doc does not mention the conception of shared tags. So how can I create shared tag on my side? Or is it only docker-hub preference?
Making a shared tag is just creating a manifest list and then pushing that manifest to the registry so that it takes the place of a tag like my-image:latest
https://github.com/estesp/manifest-tool#createpush
See https://github.com/docker-library/faq#whats-the-difference-between-shared-and-simple-tags for where we've tried to document this better. :+1:
Maybe we could improve it by linking the words "manifest list" over to somewhere else like https://docs.docker.com/registry/spec/manifest-v2-2/#manifest-list ?
It's kind of a complex subject overall, so I'm not sure how to best adjust that section to make it more understandable. :grimacing:
Another way to look at this that's perhaps simpler is that "simple tags" will usually be a single platform (Windows vs Linux) and "shared tags" will be a combination of multiple platforms (so might have vastly different interface/behavior depending on which platform they're run from, but overall should represent roughly the same thing).