-
Notifications
You must be signed in to change notification settings - Fork 7.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docker image tag spec is ambiguous #20893
Comments
You can find the reference format in the CNCF Distribution org; https://github.com/distribution/reference The Go documentation is a good starting point; https://pkg.go.dev/github.com/distribution/reference w.r.t. ambiguity between "host" or "path"; the first element is considered a hostname if it contains a period; there's also a special case for |
Ah thanks for pointing me in the right direction. Could this still be considered a docs bug (or feature-request) to link to those locations and/or include the tidbits about period and |
Probably "both" 😅 I think the current simplified way of presenting the format in the docs was (somewhat) intentional, to not overwhelm the user, and for "most" cases it did the job. That said, this part of the docs is pretty old, and I think a bit of a refresh with a bit more detail (and examples) won't hurt. A link to the reference repo documentation (for those that need the full details) definitely won't be out of place. The format definitely has its fair share of "quirks"; the format organically grew from the early beginnings of Docker when there was only 1 registry (the "docker index") and originally only 10 images maintained by Docker, so there was no ambiguity. Once the docker index was opened up for users to push their images, namespaces were introduced ("yourname/yourimage:latest"), and to keep backward compatibility, the official images (e.g. And finally, when the registry code was open-sourced to allow running your own registry, the format was extended to allow a So, yes, so some quirks were needed for this! There was no formal specification (the implementation was the spec), and I don't think anyone at the time anticipated how popular containers would become 🙈 |
Yeah, it definitely makes sense to keep it simple in this context. I think you could present something even simpler, provided the link to the reference repo was added. Currently, the docs are a straddling the line in a bit of a worst-of-both-worlds way, they look like they're being precise, but they aren't -- and then there's no link for someone who just wants the grammar anyway 😂 |
Is this a docs issue?
Type of issue
I can't find what I'm looking for
Description
The documented format for an image tag is,
Along with,
This is ambiguous and it seems impossible to write a parser for it. There are two equally valid ways to parse:
quay.io/namespace/image:tag
HOST=quay.io
,PATH=namespace/image
,TAG=tag
HOST=
,PATH=quay.io/namespace/image
,TAG=tag
Location
https://docs.docker.com/reference/cli/docker/image/tag/#extended-description
Suggestion
I'd like to see the documentation for this format updated and expanded to be more precise and comprehensive, such that it is unambiguous how to parse such an example.
The text was updated successfully, but these errors were encountered: