Proposal: platform access in `imagetools inspect`

Context

To get information about images, users can use docker buildx imagetools inspect. Like the rest of most of the docker cli printing tools, it supports the --format flag for specifying go templates.

Problem

The data parameter passed during parameter execution (which takes on the value of {{ . }} in the top-level template) is different between multi-platform images and single-platform images.

The Image, Provenance and SBOM fields are different, being a simple struct in a single-platform image, and a map of those simple structs in a multi-platform image.

This means that writing a single --format template that works irrespective of whether the image is single-platform (with a manifest) or multi-platform (with an index) is quite tricky.

Proposed solution

When users are analyzing images for information, usually we'd expect users to be interested in one of a few scenarios:

• Inspecting the image for the current platform
• Inspecting the image for a specified platform
• Inspecting the image for all platforms

To resolve this, we can create new functions for the template:

• platform
  • {{ platform nil }} returns the data for the current platform, in the same form as a single platform
  • {{ platform "linux/amd64" }} returns the data for the linux/amd64 platform, in the same form as a single platform
• platforms
  • {{ range platform, data := platforms }} iterates over all platforms, where platform takes the value of the platform string, and data takes the form as a single platform

The data struct returned from all of these functions only needs to be a simple struct, no need for maps that are sometimes present and sometimes not.

Backwards compatibility

Since this only adds new functions, and doesn't remove any functionality --format strings that previously worked won't break.

However, since imagetools is marked as experimental, we could consider breaking some behavior:

• We could keep .Name and .Manifest the same as today's behavior
• We could ensure that .Image always returns the current platform's image data (and never maps)
• We could ensure that .Provenance/.SBOM always return the current platform's provenance and sbom data (and never maps)

Effectively, this means that {{ . }} = {{ platform nil }}.

This makes the base case of "inspecting the image for the current platform" much easier -- then for iterating, or getting specified platforms, the platforms and platform functions are easily available.

cc @crazy-max @tonistiigi

Start in util/imagetools/printers.go, particularly the single-platform and multi-platform data paths linked in the issue, and trace how --format templates receive their data. Review the Go template function integration needed for platform and platforms. Done means templates can inspect the current, specified, or all platforms using consistent single-platform data while preserving existing behavior.