Docker compatibility: Filter query parameter is ignored for image endpoint

[skorhone]

Is this a BUG REPORT or FEATURE REQUEST? (leave only one on its own line)

/kind bug

Description

Docker /image/json should support filter query parameter. In docker engine documentation, filter parameter is described as:

• filter - only return images with the specified name

Tools such as testcontainers require support for filter query parameter.

Steps to reproduce the issue:

1. podman system service --log-level=debug --time=0 unix:///tmp/podman.sock

2. curl --unix-socket /tmp/podman.sock "http://localhost/images/json?filter=testcontainersofficial%2Fryuk%3A0.3.0"

Describe the results you received:

Query returns all the images in local registry.

Describe the results you expected:

Query should return only images with specified name

Additional information you deem important (e.g. issue happens only occasionally):

Output of podman version:

Version:      2.0.0
API Version:  1
Go Version:   go1.13.8
Built:        Thu Jan  1 02:00:00 1970
OS/Arch:      linux/amd64

[mheon]

That filter parameter does not look correct - we're expecting a map of filter name to filter parameters, JSON encoded (for this, probably the reference filter). If this works at all with Docker, it's not a documented part of their API.

[skorhone]

It is documented here: https://docs.docker.com/engine/api/v1.24/#32-images

[skorhone]

It seems that parameter has been removed from documentation in 1.25. My initial google search found the 1.24 documentation, so I didn't check how other versions of api looked :-)

As you've observed more recent versions such as version 1.25 and version 1.40 of documentation no longer has parameter: https://docs.docker.com/engine/api/v1.25/#operation/ImageList . I don't have docker to test with, but I suspect that while not documented parameter is still allowed and processed correctly.

Considering it's the last query parameter in list and that there is no mention on removing it from api, it could be a documentation bug (unintended change) on docker side.

Edit: It was actually mentioned in docker engines changelog. For some reason it wasn't documented in API changelog

[skorhone]

It seems filters=reference= is functionally equivalent. I'll create an issue to docker-java project.

To keep podman backwards compatible with other tools, I suggest that you add this functionality.

[skorhone]

Deprecated filter parameter is getting removed from Moby.

moby/moby#40491

[bsideup]

@skorhone correction: it is getting removed from API 1.41 (to be released) and higher:

The parameter remains available when using API version 1.40 or below.

Which means that the latest released Docker still supports the parameter and works with the tooling that uses it and wants to be compatible with 1.24 version of Docker's API.

[skorhone]

Yes, but to continue to use that filter, you need to specify the exact version of api you want to use. If you do not specify version (in path), you will be effectively using latest version - and latest no longer supports it starting from 1.41.

While I was testing use of podman with testcontainers, I don't recall seeing in my tcpdumps that testcontainers would specify api version in requests. This is one of the reasons why I thought you would be interested in this - and to me, a fix seemed like a trivial to implement.

Also, I don't think I've said or at least I didn't intend to say that support for parameter has been dropped out in 1.40. I just mentioned, that it no longer exists in that version of documentation :-)

When it comes to podman, I think we can close this issue. I don't think podman should support a feature that original authors have deprecated long ago.

@mheon Considering all this, should I close this issue?

[bsideup]

FTR docker-java will use the lowest supported API version (1.24). You can of course close the issue, but it will remain a compatibility blocker. Just saying.

[skorhone]

Resolved with #6878