Add `platform` option to `docker_image_export` and `docker_image_load`

[AnthonyGrondin]

SUMMARY

Since API 1.48+ docker allows passing in the --platform flag when loading a docker image from a .tar archive file, to only load a specific platform.

Example:

docker image load -i image.tar --platform=linux/amd64

The command also fails, if the user attempts to load a platform that is not present in the archive. This should be helpful, to prevent a playbook from loading an invalid image for a given platform.

In the same manner, also added in 1.48+ docker CLI allows passing the --platform flag when invoking docker save, to create an archive with only the selected platform variant.

Example:

docker image save --platform=linux/riscv64 -o alpine-riscv.tar alpine:latest

So in TL;DR, the platform option should be added to both docker_image_export and docker_image_load, to allows platform filtering and unlock more functionalities from the docker CLI, such as making sure a playbook never exports / load an invalid image for a given platform.

ISSUE TYPE

• Feature Idea

COMPONENT NAME

• docker_image_export
• docker_image_load

ADDITIONAL INFORMATION

• Related issue: https://github.com/ansible-collections/community.docker/issues/79

[felixfontein]

The import API supports a platform query parameter since 1.48: https://docs.docker.com/reference/api/engine/version/v1.48/#tag/Image/operation/ImageLoad

The export API does not seem to support that, at least not in the API documentation: https://docs.docker.com/reference/api/engine/version/v1.48/#tag/Image/operation/ImageGetAll Some more investigation is needed here (basically looking at moby's sources).

[kristianheljas]

It seems like API documentation issue.

The parameter was added to ImageGet endpoint (images/{name}/get) for exporting single image.

But as seen from the client source, the moby client does use ImageGetAll endpoint with the platform parameter.

Support was added in this commit.

Also tested the parameter with both endpoints and they worked fine.

If its OK to proceed I'd be happy to contribute.

[kristianheljas]

Submitted a PR to update the docs: https://github.com/moby/moby/pull/49726

[felixfontein]

If its OK to proceed I'd be happy to contribute.

That's fine from my side - but be warned that idempotency for docker_image_load will be non-trivial. For export it should be pretty easy though.

[kristianheljas]

Huh, this is starting to seem like quite a bite indeed.

On the tarball side, could write some OCI image manifest parser to extract platform information (currently parsed manifest.json does not contain any arch info).

Getting platform information from docker daemon is indeed more problematic. Exposing platform specific got only recently added (images/json with version 1.47 last august and images/{name}/json got it in 1.48 less than 2 months ago).

So until 1.47 support could be dropped, there's no way to make the modules idempotent...

Alternative could be to always export image from docker to be able to obtain platform information from OCI manifests, but that doesn't sound reasonable either I think.

At least I learned a thing or two about image tarballs today :)