improve documentation

[yosifkit]

Creating a catch-all issue so we can list areas for improvement.

• SharedTags: explain what they are and when they are used
• reword in readme: "While official images are in the process of completing image indexes to make this work naturally"
• drop opensuse example: https://github.com/docker-library/official-images/blob/92a97a0d25fc3fd25cae28428f8be9849e4a02d4/README.md#instruction-format
• explicit time-since-last-update limit?
• image name guidelines?
• tightly-coupled software suites made of many images vs loosely-coupled
  • each image must fit the "generally useful" category on their own if they are to warrant their own library file
• limit build context (generally no Dockerfiles in upstream repo)
  • I.E. changes to files in the build context should be kept minimal to help keep our build context diffs easy to read so that we can continue to review quickly. If it becomes a large file that changes every release, it may make sense to include it in the upstream release (or released as a fully maintained project/example that can be downloaded by the image)
  • Add API-Firewall official image #11100 (comment)
• inclusion criteria (improve documentation #6282 (comment))
• embed/extend old best practices documentation
  • no alpine-pkg-glibc or mixing of Alpine releases with Edge or other releases packages (Explicitly disallow the use of "alpine-pkg-glibc" #10794)
• better detail on GPG/verification (perhaps a dedicated guide); Clarify gpg verification #11063
• [RFC] Let the community play a bigger role in the approval process #4615 (comment)
• document rc alias in image tags (generic pre-release marker): docker-library/docs #2349
• image tag best practice/definition. rough idea: [software-version]-[variant]-[related-package-versions]-[os-version]
• consider https://diataxis.fr/ (perhaps we choose one quadrant that we aim all our image documentation towards?)
• document jq-template somewhere/better (what is meaning of def in this template? golang#540)

"Since every change of every image is reviewed by humans, one of the criteria is that new images are "reasonably popular" to be able to get the most out of the available time we have."

[tianon]

SharedTags: explain what they are and when they are used

https://github.com/docker-library/faq#whats-the-difference-between-shared-and-simple-tags !! 😄

explicit time-since-last-update limit?

I'm not sure this is something we can add a generic limit for -- for example, cirros doesn't get many upstream updates, hello-world only updates for Windows, etc.

[samuelkarp]

Per offline conversation with @tianon: Another good thing to clarify in the documentation would be inclusion criteria (i.e., "Is $project a good fit to be included in the library?").

[Arkemlar]

Please take a look on this one to include that doc improvement docker-library/docs#2349

[kcrane3576]

Since this appears to be a catch-all, I would like to add a request for more transparency and a specific link that outlines requirements for ALL Official Docker Images. I just opened a support ticket because I was running into an issue pulling two very specific images that were either outdated and/or the path to them had changed (consul:1.15.4 and openjdk:21-windowsservercore-ltsc2022).

For awareness, per my support ticket, since 1.16 consul has updated the api path to manifests to be: hashicorp/consul. Also, openjdk:21-windowsservercore-ltsc2022 has been deprecated (on me).

The real issue for us here is that when these changes to how to retrieve Official Docker Images is implemented, how are teams made aware?

It seems like we are missing a significant piece of the documentation and over the past few months we have run into multiple issues obtaining this data. For most Official Docker Images, you update the ‘image’ to be ‘library/{image}’ in the path. We would just like to have access to the logic or map that dictates how we are supposed to construct our api calls.

I would greatly appreciate any help/insight here. Also, not looking for manual steps. If we need to add some logic to check ahead of time somewhere, that is fine.

[tianon]

@kcrane3576 I'm having a really hard time trying to understand what it is you're asking for, but it sounds like maybe you're having trouble understanding how to know if official images are deprecated / unsupported? Unfortunately, the best we can do with Docker Hub (where we publish our images) is a note on the image description.

(Either way, this probably isn't on-topic for this issue, which is more about documentation about the official images program in general, and we don't have any APIs directly.)

[kcrane3576]

My apologies. I will try to explain the issue from my end a little better. For awareness, the root goal for me is to always be able to pull the `docker-content-digest` or Digest no matter what quirks are required within the url. Okay, so my understanding of dealing with 'Official Docker Images' is that you have to amend the url to pull the manifests to include '/library/'. So this: curl "https://registry-1.docker.io/v2/$TARGET_NS_REPO/manifests/$TAG" \ -H "Authorization:Bearer $TOKEN" \ | jq '.fsLayers' Based on my previous threads, this makes sense and non 'Official Docker Images' are handled on more of a case by case basis. Now I am being told instead of '/library/' for consul images, it has to be '/hashicorp/'. Which would result in: curl " https://registry-1.docker.io/v2/hashicorp/$TARGET_NS_REPO/manifests/$TAG" \ -H "Authorization:Bearer $TOKEN" \ | jq '.fsLayers' The information I would like to have is ALL of the other url amendment requirements for Dockerhub Official Images. - IF image is consul: - THEN update url to be: " https://registry-1.docker.io/v2/hashicorp/$TARGET_NS_REPO/manifests/$TAG" - IF image is x: - THEN update url to be: " https://registry-1.docker.io/v2/{x_requirement}/$TARGET_NS_REPO/manifests/$TAG "

…

On Wed, Nov 29, 2023 at 7:27 PM Tianon Gravi ***@***.***> wrote: @kcrane3576 <https://github.com/kcrane3576> I'm having a really hard time trying to understand what it is you're asking for, but it sounds like maybe you're having trouble understanding how to know if official images are deprecated / unsupported? Unfortunately, the best we can do with Docker Hub (where we publish our images) is a note on the image description. (Either way, this probably isn't on-topic for this issue, which is more about documentation about the official images program in general, and we don't have any APIs directly.) — Reply to this email directly, view it on GitHub <#6282 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARGWFTXEITFNHM6P47JDA3YG7HGPAVCNFSM4IB27F6KU5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TCOBTGI4TCMJYGA4A> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[kcrane3576]

My bad, the first curl reference should be: So this: curl "https://registry-1.docker.io/v2/library/$TARGET_NS_REPO/manifests/$TAG <https://registry-1.docker.io/v2/$TARGET_NS_REPO/manifests/$TAG>" \ -H "Authorization:Bearer $TOKEN" \ | jq '.fsLayers' Based on my previous threads, this makes sense and non 'Official Docker Images' are handled on more of a case by case basis. ...

…

On Wed, Nov 29, 2023 at 7:43 PM Kyle Crane ***@***.***> wrote: My apologies. I will try to explain the issue from my end a little better. For awareness, the root goal for me is to always be able to pull the `docker-content-digest` or Digest no matter what quirks are required within the url. Okay, so my understanding of dealing with 'Official Docker Images' is that you have to amend the url to pull the manifests to include '/library/'. So this: curl "https://registry-1.docker.io/v2/$TARGET_NS_REPO/manifests/$TAG" \ -H "Authorization:Bearer $TOKEN" \ | jq '.fsLayers' Based on my previous threads, this makes sense and non 'Official Docker Images' are handled on more of a case by case basis. Now I am being told instead of '/library/' for consul images, it has to be '/hashicorp/'. Which would result in: curl " https://registry-1.docker.io/v2/hashicorp/$TARGET_NS_REPO/manifests/$TAG" \ -H "Authorization:Bearer $TOKEN" \ | jq '.fsLayers' The information I would like to have is ALL of the other url amendment requirements for Dockerhub Official Images. - IF image is consul: - THEN update url to be: " https://registry-1.docker.io/v2/hashicorp/$TARGET_NS_REPO/manifests/$TAG" - IF image is x: - THEN update url to be: " https://registry-1.docker.io/v2/{x_requirement}/$TARGET_NS_REPO/manifests/$TAG " On Wed, Nov 29, 2023 at 7:27 PM Tianon Gravi ***@***.***> wrote: > @kcrane3576 <https://github.com/kcrane3576> I'm having a really hard > time trying to understand what it is you're asking for, but it sounds like > maybe you're having trouble understanding how to know if official images > are deprecated / unsupported? Unfortunately, the best we can do with Docker > Hub (where we publish our images) is a note on the image description. > > (Either way, this probably isn't on-topic for this issue, which is more > about documentation about the official images program in general, and we > don't have any APIs directly.) > > — > Reply to this email directly, view it on GitHub > <#6282 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AARGWFTXEITFNHM6P47JDA3YG7HGPAVCNFSM4IB27F6KU5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TCOBTGI4TCMJYGA4A> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

-- Thank you for your time, Kyle Crane ***@***.***

[whalelines]

Thanks for the clarification @kcrane3576 , hopefully I can do the same for you.

The hashicorp/consul repository is not a Docker Official Image (DOI). The consul DOI has not moved to become hashicorp/consul, it has been deprecated and is no longer maintained. We retain the existing tags of the consul DOI so as to minimize the chance of breaking its users' existing workflows. But as the consul DOI page on Docker Hub states, that repository is deprecated and if people want recent versions of Hashicorp Consul, they should use the hashicorp/consul repository instead, which is maintained by Hashicorp, not Docker.

So when curling for information for DOI, you will always add the library namespace. If it is not under library, it is not DOI.

[kcrane3576]

@whalelines If I am understanding correct, essentially consul will no longer a DOI after 1.16

• For awareness that doesn't explain why I couldn't pull the 1.15 from a path with /library/ (fixed since my original thread)

Assuming I am correct, my question should be updated.

Are there any DOI that don't follow the pattern of requiring /library/ in the path?

• If so, I would like ALL of that information to be available for customers.

Again, my main goal here is to always be able to pull the docker-content-digest or Digest (for DOI).

[kcrane3576]

So when curling for information for DOI, you will always add the library namespace. If it is not under library, it is not DOI.

I appreciate the clarification above. This was exactly the information I needed.

• Not sure it was all working exactly that way yesterday, but it is today.