c8d: image load is not atomic, and always overwrites image

Author: thaJeztahCreated Oct 7, 2024Updated Sep 28, 2026

Labelskind/enhancementkind/bugarea/imagescontainerd-integrationarea/ux

Description

This may be partially "by design" (but possibly worth a discussion). When loading an image from a tar, the loaded image unconditionally replaces existing image(s).

1. Failing to load image replaces existing image with empty index

The following example loads a multi-platform image from a tar (not all variants are present in the tar);

bash

$ docker image load -i image.tar
Loaded image: alpine:latest

$ docker image ls --tree
IMAGE                   ID             DISK USAGE   CONTENT SIZE   USED
alpine:latest           beefdbd8a1da       20.6MB         11.1MB
├─ linux/s390x          2b5b26e09ca2       3.46MB         3.46MB
├─ linux/ppc64le        c7a6800e3dc5       3.57MB         3.57MB
├─ linux/arm64/v8       9cee2b382fe2       13.6MB         4.09MB
├─ linux/amd64          33735bd63cf8           0B             0B
├─ linux/arm/v6         50f635c8b04d           0B             0B
├─ linux/arm/v7         f2f82d424957           0B             0B
├─ linux/386            b3e87f642f5c           0B             0B
└─ linux/riscv64        80cde017a105           0B             0B

When trying to load a platform-variant from the tar that's not included, an error is produced, but the image is replaced regardless, so now resulting in an empty image reference;

bash

$ docker image load -i image-multiple.tar --platform=linux/ppc64le
requested platform (linux/ppc64le) not found: not found

docker image ls --tree
IMAGE           ID             DISK USAGE   CONTENT SIZE   USED
alpine:latest   beefdbd8a1da           0B             0B

2. Loading different variant of the same manifest-index replaces existing variants

The following loads a single variant from a tar;

bash

$ docker image load -i image-multiple.tar --platform=linux/amd64
Loaded image: alpine:latest

$ docker image ls --tree
IMAGE                   ID             DISK USAGE   CONTENT SIZE   USED
alpine:latest           beefdbd8a1da       12.1MB         3.63MB
├─ linux/amd64          33735bd63cf8       12.1MB         3.63MB
├─ linux/arm/v6         50f635c8b04d           0B             0B
├─ linux/arm/v7         f2f82d424957           0B             0B
├─ linux/arm64/v8       9cee2b382fe2           0B             0B
├─ linux/386            b3e87f642f5c           0B             0B
├─ linux/ppc64le        c7a6800e3dc5           0B             0B
├─ linux/riscv64        80cde017a105           0B             0B
└─ linux/s390x          2b5b26e09ca2           0B             0B

Loading a different variant from the same image replaces the available variants of the multi-platform image with the newly imported variant;

bash

$ docker image load -i image-multiple.tar --platform=linux/s390x
Loaded image: alpine:latest

$ docker image ls --tree
IMAGE                   ID             DISK USAGE   CONTENT SIZE   USED
alpine:latest           beefdbd8a1da       11.9MB         3.46MB
├─ linux/s390x          2b5b26e09ca2       11.9MB         3.46MB
├─ linux/amd64          33735bd63cf8           0B             0B
├─ linux/arm/v6         50f635c8b04d           0B             0B
├─ linux/arm/v7         f2f82d424957           0B             0B
├─ linux/arm64/v8       9cee2b382fe2           0B             0B
├─ linux/386            b3e87f642f5c           0B             0B
├─ linux/ppc64le        c7a6800e3dc5           0B             0B
└─ linux/riscv64        80cde017a105           0B             0B

:question: do we want to have an option to append to the existing image, in situations where the root manifest-index is the same?

Source: moby/moby

View original on GitHub View discussion on GitHub