Ambiguity in the ImageCreate API when pulling a tag or digest

[cowwoc]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Other

Description

There is a bit of an ambiguity in the way that https://docs.docker.com/reference/api/engine/version/v1.47/#tag/Image/operation/ImageCreate is specified.

On the one hand, it says that fromImage may include a tag or a digest to pull. On the other hand, it says that if tag is empty then all tags for the given image will be pulled.

• Is omitting the tag query parameter equivalent to sending the parameter with an empty value?
• What happens if a user includes a tag or a digest in fromImage but tag is omitted? Will the specific tag or digest get pulled? Or will all the tags get pulled?
• What happens if the user specifies one tag in fromImage but a different tag in the tag property?

Location

https://docs.docker.com/reference/api/engine/version/v1.47/#tag/Image/operation/ImageCreate

Suggestion

Please clarify the above scenarios in the API documentation

[dvdksn]

cc @thaJeztah do you know what the behavior is for these scenarios?

[thaJeztah]

Yeah, it's a bit confusing for sure (most of this was for backward compatibility, but we do want to ultimately add an explicit "all-tags" option instead of the implicit behavior when tag is empty, see moby/moby#42053 and moby/moby#48760).

Any tag or digest passed in fromImage is not used; ISTR this was to be more permissive for clients that would send image:tag instead of image only
https://github.com/moby/moby/blob/d7ad7a9534afb673fcbb6dabb64bae3be720e2b8/api/server/router/image/image_routes.go#L40-L43

The logic to decide whether all tags should be pulled is based on the value of the tag query-argument;
https://github.com/moby/moby/blob/d7ad7a9534afb673fcbb6dabb64bae3be720e2b8/api/server/router/image/image_routes.go#L72-L95

[dvdksn]

OK, thanks 👍🏻

Any tag or digest passed in fromImage is not used

I think in that case, "The name may include a tag or digest" is indeed misleading. Should probably read something along the lines of: "If the name includes a tag or digest, it is ignored. Use the tag property to specify the desired tag or digest."

[thaJeztah]

Hmm... while looking at your docs PR; I actually think I'm wrong; it's ignored a ?tag= is provided, but if that's missing and the fromImage does contain a tag, it looks like we're accepting that tag as well.

I guess we tried to avoid accidentally pulling "all tags".

# pulls latest
curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn:latest'

# pulls "0.1.0" tag
curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn:0.1.0'

# tag query parameter takes precedence; pulls "0.1.0" tag
curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn:0.1&tag=0.1.0'

# no tag in "fromImage" AND no tag in "tag" parameter; pulls all tags
curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn'

For digests.. it looks like there's some inconsistency; specifying the digest in fromImage and no tag parameter provided, pulls by digest;

# pulls by digest
curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn@sha256:641f09e6a0409cc0a9f98e943dd033aa3b914d9141174c39bc0d00cb9519e07b'

# tag + digest in "fromImage"; tag resolution  is skipped and image is pulled by digest
curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn:0.1.0@sha256:641f09e6a0409cc0a9f98e943dd033aa3b914d9141174c39bc0d00cb9519e07b'

This seems inconsistent though; if fromImage contains a digest, the tag parameter is ignored, or at least, the digest takes precedence (but no "all-tags");

curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn@sha256:641f09e6a0409cc0a9f98e943dd033aa3b914d9141174c39bc0d00cb9519e07b&tag=0.1.0'
curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn:0.1@sha256:641f09e6a0409cc0a9f98e943dd033aa3b914d9141174c39bc0d00cb9519e07b&tag=0.1.0'

Passing a tag in fromImage and a valid digest in tag will pull by digest;

curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn:latest&tag=sha256:641f09e6a0409cc0a9f98e943dd033aa3b914d9141174c39bc0d00cb9519e07b'

Passing an incorrect digest through tag is a failure (here I passed a digest for busybox); that looks like a bug at least

curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn@sha256:641f09e6a0409cc0a9f98e943dd033aa3b914d9141174c39bc0d00cb9519e07b&tag=sha256:3A2919d0172f7524b2d8df9e50066a682669e6d170ac0f6a49676d54358fe970b5'
{"message":"invalid tag format"}

curl -XPOST --unix-socket /var/run/docker.sock 'http://localhost/v1.47/images/create?fromImage=thajeztah/angry-unicorn:latest&tag=sha256:3A2919d0172f7524b2d8df9e50066a682669e6d170ac0f6a49676d54358fe970b5'
{"message":"invalid tag format"}

[cowwoc]

Assuming I understood you correctly, you are saying that:

• If fromImage contains only a name and tag is not set then all versions of the image are pulled.
• If fromImage contains only a name and tag is set, then only the version that matches the tag is pulled.
• If fromImage contains a name and a tag, then only the version that matches the tag is pulled.
• If fromImage contains a name and a digest, then only the version that matches the digest is pulled.

In short, so long as we make sure to specify a tag or a digest in fromImage then Docker will do the right thing. Is that a fair assumption to make?