'docker history' command: Why does the column label say 'IMAGE' when the column contains layers?

Question

I have been working with Docker for some months now quite intensively, and I have not used the docker history command often (yet).

However, the handful of times I have used it have caused me to develop an assumption that there are a large number of 'dependent images' associated with my 'top-level' image, not layers.

Now I have come to understand that much of the above assumption was based on the fact that, starting long ago, when I issue the docker history command, the title of the leftmost column is IMAGE, whereas in fact, the rows really list the layers associated with a single image, not images.

Here is a screenshot of an example docker history command:

There is a critical difference between images and layers in Docker, which is why this really stands out as a serious question.

I am frankly very surprised by this issue. How could something of such critical importance be flaked out on by Docker?

I have just spent a while hunting around for a discussion of, or answer to, this issue. Surprisingly, even the Docker 'history' command documentation makes no mention of this. The only real 'confirmation' I have seen comes from this link.

Can somebody please tell me why the title of the column from docker history is 'IMAGE', while the entries themselves are layers?

Answer 1

It's complicated ;) This post by Nigel Brown is super useful for understanding this, but I'll pull out the relevant points here.

Historically (pre Docker v1.10), each time a new layer was created as a result of a commit action, Docker also created a corresponding image, which was identified by a randomly generated 256-bit UUID, usually referred to as an image ID (presented in the UI as either a short 12-digit hex string, or a long 64-digit hex string).

So, historically they were images, just intermediate ones with no 'human-friendly' tag (although they could be tagged).

Since Docker v1.10, generally, images and layers are no longer synonymous. Instead, an image directly references one or more layers that eventually contribute to a derived container's filesystem.

And if you do a docker history on a pulled image, you'll see something like (taken from the article):

$ docker history swarm
IMAGE               CREATED             CREATED BY                                      
SIZE                COMMENT  
c54bba046158        9 days ago          /bin/sh -c #(nop) CMD ["--help"]                0 B  
<missing>           9 days ago          /bin/sh -c #(nop) ENTRYPOINT &{["/swarm"]}      0 B  
<missing>           9 days ago          /bin/sh -c #(nop) VOLUME [/.swarm]              0 B  
<missing>           9 days ago          /bin/sh -c #(nop) EXPOSE 2375/tcp               0 B  
<missing>           9 days ago          /bin/sh -c #(nop) ENV SWARM_HOST=:2375          0 B  
<missing>           9 days ago          /bin/sh -c #(nop) COPY dir:b76b2255a3b423981a   0 B  
<missing>           9 days ago          /bin/sh -c #(nop) COPY file:5acf949e76228329d   277.2 kB  
<missing>           9 days ago          /bin/sh -c #(nop) COPY file:a2157cec2320f541a   19.06 MB  

You'll see the IMAGE column reports <missing>, these are not images, but layers that are constituent parts of the image.

So they're not images! What the hell, why is the column named that? (back to your original question). Well, except...:

However, when a layer is committed during an image build on a local Docker host, an 'intermediate' image is created at the same time. Just like all other images, it has a configuration item which is a list of the layer digests that are to be incorporated as part of the image, and its ID or digest contains a hash of the configuration object. Intermediate images aren't tagged with a name, but, they do have a 'Parent' key, which contains the ID of the parent image.

So actually, when you build locally, those constituent layers are images (just like they used to be, even when you pulled them from somewhere else, until v1.10), and are used to facilitate the build cache (part that makes builds fast if you've already built that layer already).

So the answer is...sometimes they are images (technically), sometimes they are layers (and then represented in that column as <missing>). I'd guess it was left as IMAGE for a) historical reasons and b) because they actually are images when something appears there, otherwise it just shows <missing>. I can see how they might be a little confusing, and there certainly might be additional technical detail I've glossed over here, but hope it helps!

Disclaimer: I work for Docker, but my views / posts are my own, etc...