api/image/list: Return `Containers` count #50146

vvoland · 2025-06-05T12:02:57Z

needs: api: bump to 1.51 #50145
replaces: api/image/list: Add container-count parameter #47501
related to: Add support for shared-size parameter for images queries #42531
needed by: docker images --tree doesn't show "Used" badge with graphdrivers docker/cli#6122

This parameter was already supported for some time in the backend (for purposes related to docker system prune).
It was also already present in the imagetypes.ListOptions but was never actually handled by the client.

Make it available by default in the response.

- How to verify it

- Description for the changelog

`GET /images/json` now sets the value of the `Containers` field for all images to the count of containers using the image.

- A picture of a cute animal (not mandatory but encouraged)

thaJeztah · 2025-06-05T12:06:41Z

api/server/router/image/image_routes.go

+		Filters:        imageFilters,
+		SharedSize:     sharedSize,
+		Manifests:      manifests,
+		ContainerCount: containerCount,


ISTR we had a discussion to (as alternative) list the IDs of containers instead of just a count. That could make the information more actionable (not just "if it's in use, and by how many", but also being able to discover which containers are using this)

Yeah, something to consider. For now just rebased the last PR.

Oh! Right I just read the cli ticket, and we did do that, but it's in the manifests; could we somehow construct a manifest in the non-containerd case (in which we can put the container ID)?

[ { "Containers": -1, "Created": 1749073960, "Id": "sha256:f1f9df63a741c97c5b4b02c12ec89e4864774185c333d366eb3b50d9f82cf267", "Labels": { "org.opencontainers.image.source": "https://github.com/burgerdev/weird-images" }, "ParentId": "", "Descriptor": { "mediaType": "application/vnd.oci.image.index.v1+json", "digest": "sha256:f1f9df63a741c97c5b4b02c12ec89e4864774185c333d366eb3b50d9f82cf267", "size": 856 }, "Manifests": [ { "ID": "sha256:8e9bc7f8de6ac3d86a483310f6fe31c1de68b128af06215fdf28a969cba1b4f0", "Descriptor": { "mediaType": "application/vnd.oci.image.manifest.v1+json", "digest": "sha256:8e9bc7f8de6ac3d86a483310f6fe31c1de68b128af06215fdf28a969cba1b4f0", "size": 1045, "platform": { "architecture": "arm64", "os": "linux" } }, "Available": true, "Size": { "Content": 1847842, "Total": 6054434 }, "Kind": "image", "ImageData": { "Platform": { "architecture": "arm64", "os": "linux" }, "Size": { "Unpacked": 4206592 }, "Containers": [ "48f88941ddbdcda83b147ae7c08b1e8a6007bfb780b85920455c734635c933db" ] } }, { "ID": "sha256:aa257ed292b265869388405afec449cec0a4dc67fc8127bcc206de19dd919277", "Descriptor": { "mediaType": "application/vnd.oci.image.manifest.v1+json", "digest": "sha256:aa257ed292b265869388405afec449cec0a4dc67fc8127bcc206de19dd919277", "size": 566, "annotations": { "vnd.docker.reference.digest": "sha256:8e9bc7f8de6ac3d86a483310f6fe31c1de68b128af06215fdf28a969cba1b4f0", "vnd.docker.reference.type": "attestation-manifest" }, "platform": { "architecture": "unknown", "os": "unknown" } }, "Available": true, "Size": { "Content": 2084, "Total": 2084 }, "Kind": "attestation", "AttestationData": { "For": "sha256:8e9bc7f8de6ac3d86a483310f6fe31c1de68b128af06215fdf28a969cba1b4f0" } } ], "RepoDigests": [ "test@sha256:f1f9df63a741c97c5b4b02c12ec89e4864774185c333d366eb3b50d9f82cf267" ], "RepoTags": [ "test:latest" ], "SharedSize": -1, "Size": 6056518 } ]

Hm... I guess we can't because we won't have the OCI digest etc 🤔 😢

thaJeztah · 2025-06-06T14:17:43Z

Quick summary of a discussion we had earlier Today;

We considered if adding a "fake / constructed" []manifest for the non-containerd situation would work (i.e., a single-platform image to be shown as a multi-platform image with 1 platform), but this would likely become a bit "too much" trying to shoe-horn things.
The ContainerCount field is already there, just not propagated with a value; while its purpose was intended for docker system df (and never should've made its way to other endpoints), it's there, so re-using that field can be a viable option.
OTOH, either a []containerID or a more dedicated InUse bool could make sense if this was all "green-field"
Some work is still needed, and may determine what direction to take;
- If we are already collecting the list of containers as part of this response, we may not need to make this "optional"; we can decide to just propagate the field, and be done.
- In that case, we could still decide to add a new field, if we would prefer keeping the option open to split the response types (for system df and container ls), with the option to deprecate the ContainerCount field.

The goal ultimately is to change the docker image ls output to the format used by docker image ls --tree, also when --tree is used, and show the corresponding columns (which includes whether an image is in use);

IMAGE           ID             DISK USAGE   CONTENT SIZE   EXTRA
ubuntu:24.04    a0e45e2ce6e6       78.1MB             0B   U
nginx:alpine    6769dc3a703c       48.2MB             0B
<untagged>      0fa55949643d       1.18GB             0B   U
alpine:latest   aded1e1a5b37       7.83MB             0B

We don't want the CLI to be responsible for "detecting" if the containerd image-store is used, or not, and having a field that's available regardless if the underlying variants are shown is useful for this. Having a []ContainerID slice available at all times could also be useful, however, would be duplicating information if --tree is used (as in that case each of the underlying manifests would already have information about container(s) using the manifest).

vvoland · 2025-06-12T11:47:06Z

For graphdrivers, the container count need some extra cycles (it shouldn't be much though):

moby/daemon/images/image_list.go

Lines 201 to 216 in b5d26e5

    
           if opts.ContainerCount { 
        
           	// Lazily init allContainers. 
        
           	if allContainers == nil { 
        
           		allContainers = i.containers.List() 
        
           	} 
        
           	// Get container count 
        
           	var containers int64 
        
           	for _, c := range allContainers { 
        
           		if c.ImageID == id { 
        
           			containers++ 
        
           		} 
        
           	} 
        
           	// NOTE: By default, Containers is -1, or "not set" 
        
           	summary.Containers = containers 
        
           }

For containerd, we already have that number anyway because we need it for Manifests:

moby/daemon/containerd/image_list.go

Lines 413 to 415 in b5d26e5

    
           if opts.ContainerCount { 
        
           	image.Containers = summary.ContainersCount 
        
           }

Considering that the Containers is already in the image.Summary type.. I'd lean more towards just providing it by default without an opt-in.

WDYT?

thaJeztah · 2025-06-13T09:42:57Z

api/swagger.yaml

@@ -2195,9 +2195,6 @@ definitions:
        description: |
          Number of containers using this image. Includes both stopped and running
          containers.
-
-          This size is not calculated by default, and depends on which API endpoint
-          is used. `-1` indicates that the value has not been set / calculated.


-1 indicates that the value has not been set / calculated.

We could keep this; even though we no longer return by default, but to explain it could be

This parameter was already supported for some time in the backend (for purposes related to docker system prune). It was also already present in the imagetypes.ListOptions but was never actually handled by the client. Make it available by default in the response. Signed-off-by: Paweł Gronowski <[email protected]>

thaJeztah

LGTM, thanks!

vvoland · 2025-06-13T10:54:16Z

Hmm interesting failure, haven't seen that one before:

 === RUN   TestContainerRestartWithCancelledRequest
    restart_test.go:278: timeout waiting for restart event
--- FAIL: TestContainerRestartWithCancelledRequest (3.21s)

https://github.com/moby/moby/actions/runs/15631616328/job/44037276284?pr=50146#step:7:1277

thaJeztah · 2025-06-13T11:18:05Z

Initially thought if it would be related to those locking changes, but we didn't merge it yet;

fix: daemon: state of stopped container visible to other queries when container is stopped #50136

vvoland · 2025-06-13T11:32:20Z

Yeah me too!

vvoland added this to the 28.3.0 milestone Jun 5, 2025

vvoland self-assigned this Jun 5, 2025

vvoland added area/api kind/enhancement Enhancements are not bugs or new features but can improve usability or performance. impact/api impact/changelog area/images labels Jun 5, 2025

vvoland mentioned this pull request Jun 5, 2025

docker images --tree doesn't show "Used" badge with graphdrivers docker/cli#6122

Closed

thaJeztah reviewed Jun 5, 2025

View reviewed changes

vvoland force-pushed the image-list-containers branch 2 times, most recently from 37209f7 to 59d3bb6 Compare June 5, 2025 12:12

vvoland force-pushed the image-list-containers branch 2 times, most recently from 393e7d1 to 5ac634d Compare June 12, 2025 18:07

vvoland changed the title ~~api/image/list: Add container-count parameter~~ api/image/list: Return Containers count Jun 12, 2025

vvoland force-pushed the image-list-containers branch 3 times, most recently from 60ae6ab to 3b56444 Compare June 12, 2025 18:20

vvoland marked this pull request as ready for review June 12, 2025 18:20

thaJeztah reviewed Jun 13, 2025

View reviewed changes

vvoland force-pushed the image-list-containers branch 2 times, most recently from 7ad4213 to ccb3151 Compare June 13, 2025 09:45

vvoland force-pushed the image-list-containers branch from ccb3151 to cfcbfab Compare June 13, 2025 09:46

thaJeztah approved these changes Jun 13, 2025

View reviewed changes

vvoland merged commit 72145a8 into moby:master Jun 13, 2025
188 of 190 checks passed

AkihiroSuda mentioned this pull request Jun 30, 2025

Add HealthStatus attribute on the docker ps command #50281

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

api/image/list: Return `Containers` count #50146

api/image/list: Return `Containers` count #50146

Uh oh!

vvoland commented Jun 5, 2025 •

edited

Loading

Uh oh!

thaJeztah Jun 5, 2025

Uh oh!

vvoland Jun 5, 2025

Uh oh!

thaJeztah Jun 5, 2025

Uh oh!

thaJeztah Jun 5, 2025

Uh oh!

thaJeztah commented Jun 6, 2025

Uh oh!

vvoland commented Jun 12, 2025

Uh oh!

thaJeztah Jun 13, 2025

Uh oh!

thaJeztah left a comment

Uh oh!

vvoland commented Jun 13, 2025 •

edited

Loading

Uh oh!

thaJeztah commented Jun 13, 2025

Uh oh!

vvoland commented Jun 13, 2025

Uh oh!

Uh oh!

Uh oh!

api/image/list: Return Containers count #50146

api/image/list: Return Containers count #50146

Uh oh!

Conversation

vvoland commented Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thaJeztah Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

vvoland Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jun 6, 2025

Uh oh!

vvoland commented Jun 12, 2025

Uh oh!

thaJeztah Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

vvoland commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thaJeztah commented Jun 13, 2025

Uh oh!

vvoland commented Jun 13, 2025

Uh oh!

Uh oh!

Uh oh!

api/image/list: Return `Containers` count #50146

api/image/list: Return `Containers` count #50146

vvoland commented Jun 5, 2025 •

edited

Loading

vvoland commented Jun 13, 2025 •

edited

Loading