Representing architecture in image reference strings

[debarshiray]

@DaliborKr is working on implementing support for cross-architecture containers in Toolbx, and we are wondering if there's a way to include the name of the CPU architecture in the image reference string.

If someone has the same image (eg., registry.fedoraproject.org/fedora:43) twice in their local containers/storage image store for two different CPU architectures, then they are represented as:

rishi@topinka:~$ podman images
REPOSITORY                                       TAG         IMAGE ID      CREATED        SIZE
<none>                                           <none>      300c52885194  7 hours ago    227 MB
registry.fedoraproject.org/fedora                43          f0a2e675b6a5  7 hours ago    186 MB

It's not obvious that the first line represents the image for ppc64le and the second for amd64.

So, we are wondering if there's a way to encode the architecture in the image reference string. We can use skopeo copy or something else to tag the image in the image store, but we don't know what the tag should be.

The OCI Image Format Specification seems to be only about the contents of an image, not the string reference. The Docker Image Specification has some details on the image ID, tag and repository, but not much more.

There is a grammar describing image references in the go.podman.io/image/v5/docker/reference package and its Docker counterpart at github.com/distribution/reference, but doesn't say anything about CPU architectures.

Similarly, we don't see anything in github.com/containers/buildah/util, from where I had lifted some code about image references in the past.

Right now, we are thinking of appending the architecture as a suffix. eg., registry.fedoraproject.org/fedora:43-ppc64le. These are already used by Fedora for its official images, but it's not clear if this is common practice.

Are there any standards or conventions or suggestions on this?

[debarshiray]

New year's ping. :)

[Luap99]

It's not obvious that the first line represents the image for ppc64le and the second for amd64.

Right I think this is a larger design issue with podman/docker that the local store naming is not really aware to manifest lists,
#26621

As for naming I think appending the arch in the tag is common enough, at least I have seen it in several projects. Though really I think making users having to name arch specific is not the way to go and we should keep working with manifest lists so there is only one name that can refer to many images.
It is up to podman and other tools to decide how to properly store them locally

[DaliborKr]

Hello, following up on this discussion with the approach we implemented in Toolbx for cross-architecture container support.

The problem (recap)

As discussed above and in #26621, pulling the same image for two different architectures causes the second pull to overwrite the tag of the first one, leaving it as <none>. Additionally, podman images do not display architecture information, making it impossible to distinguish between variants. This causes two problems:

• The image name is no longer readable, which is not great for a Toolbx user who expects to be able to work with images and reuse them by name in the long term.
• Once a non-native image replaces the tag of a native one, subsequent Toolbx operations that look up images without an explicit new --arch flag may unintentionally use the wrong architecture.

Considered approaches

We evaluated three options:

1. Display the architecture as a separate column in the toolbox list only, without modifying the image name -> works with both Skopeo and Podman, but two images with identical repository+tag in local storage create an ambiguity that breaks Toolbx's image resolution logic (which relies on unique name-based lookups), so it solves only the readability problem.

2. Append architecture to the repository path (e.g., registry.fedoraproject.org/fedora-toolbox:43/arm64) -> avoids tag conflicts, but this format is not recognized as a valid image reference by Podman or Skopeo. Actually, Flatpak references use this approach to preserve architecture information (e.g., app.devsuite.Ptyxis/x86_64/stable).

3. Append architecture as a tag suffix (e.g., registry.fedoraproject.org/fedora-toolbox:43-arm64) -> valid for both Podman and Skopeo, and already used in practice (e.g., the Fedora Toolbx image registry publishes images with this pattern).

Chosen solution

We went with option 3 (tag suffix). The implementation works as follows:

• Native images are pulled normally with podman pull — no changes.
• Non-native images are downloaded using skopeo copy --override-arch, which stores them under a modified tag with the architecture suffix:

skopeo copy --override-arch arm64 
docker://registry.fedoraproject.org/fedora-toolbox:43 
containers-storage:registry.fedoraproject.org/fedora-toolbox:43-arm64

• The suffix is applied only to images from distributions that Toolbx natively supports (Fedora, RHEL, Ubuntu, Arch Linux), where the tag format is predictable. Custom images are left as-is, because users working with custom images are already expected to handle Toolbx-specific requirements and the image architecure.

Result

After creating containers for multiple architectures, local storage looks like this:

$ toolbox list
IMAGE NAME
registry.fedoraproject.org/fedora-toolbox:43
registry.fedoraproject.org/fedora-toolbox:43-arm64
registry.fedoraproject.org/fedora-toolbox:43-ppc64le

Limitations

• There is no OCI or Podman standard for encoding architecture in tags (as @debarshiray mentioned), so this is a Toolbx-specific convention limited to images natively supported by Toolbx, where we know the tag format we can expect.
• As @Luap99 noted, manifest-list-aware local storage would be the proper long-term solution. Until that is available, the tag suffix approach provides a practical workaround that avoids the <none> problem and keeps images distinguishable.