Adding annotation/label to OCI container-image without creating the container first - docker

Question

For adding some annotations/labels to a image, we first have to create the container from the image, and then we can add some annotations/labels using buildah-config: buildah-config [options] containerID
But this requires first creating a container from image, then adding the required annotation/label, and then committing the changes back to an image.
But creating a container just for making some small change to the image configuration seems a unnecessary step which would take additional time and memory.
Is there a better way to add annotations/labels to a image?

Answer 1

For an image on a registry (or in an OCI Layout structure on the filesystem) there are various tools to modify that image. From go-containerregistry (by Google), there's crane mutate:
$ crane mutate --help
Modify image labels and annotations. The container must be pushed to a registry, and the manifest is updated there.
Usage:
crane mutate [flags]
Flags:
-a, --annotation stringToString New annotations to add (default [])
--append strings Path to tarball to append to image
--cmd strings New cmd to set
--entrypoint strings New entrypoint to set
-e, --env stringToString New envvar to add (default [])
-h, --help help for mutate
-l, --label stringToString New labels to add (default [])
-t, --tag string New tag to apply to mutated image. If not provided, push by digest to the original image repository.
Global Flags:
--insecure Allow image references to be fetched without TLS
--platform platform Specifies the platform in the form os/arch[/variant][:osversion] (e.g. linux/amd64). (default all)
-v, --verbose Enable debug logs
And from regclient (by myself), there's regctl image mod:
$ regctl image mod --help
EXPERIMENTAL: Applies requested modifications to an image
Usage:
regctl image mod <image_ref> [flags]
Flags:
--annotation stringArray set an annotation (name=value) (default )
--annotation-base stringArray set base image annotations (image/name:tag,sha256:digest) (default )
--buildarg-rm string delete a build arg (default "")
--buildarg-rm-regex string delete a build arg with a regex value (default "")
--config-time-max string max timestamp for a config (default "")
--create string Create tag
--data-max stringArray sets or removes descriptor data field (size in bytes) (default )
--expose-add stringArray add an exposed port (default )
--expose-rm stringArray delete an exposed port (default )
--external-urls-rm remove external url references from layers (first copy image with "--include-external") (default )
--file-tar-time-max stringArray max timestamp for contents of a tar file within a layer (default )
-h, --help help for mod
--label stringArray set an label (name=value) (default )
--label-to-annotation set annotations from labels (default )
--layer-rm-created-by string delete a layer based on history (created by string is a regex) (default "")
--layer-rm-index uint delete a layer from an image (index begins at 0) (default )
--layer-strip-file string delete a file or directory from all layers (default "")
--layer-time-max string max timestamp for a layer (default "")
--rebase rebase an image using OCI annotations (default )
--rebase-ref string rebase an image with base references (base:old,base:new) (default "")
--replace Replace tag (ignored when "create" is used)
--time-max string max timestamp for both the config and layers (default "")
--to-oci convert to OCI media types (default )
--volume-add stringArray add a volume definition (default )
--volume-rm stringArray delete a volume definition (default )
Global Flags:
--logopt stringArray Log options
--user-agent string Override user agent
-v, --verbosity string Log level (debug, info, warn, error, fatal, panic) (default "warning")
For example:
$ regctl manifest get localhost:5000/library/alpine:latest
Name: localhost:5000/library/alpine:latest
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest: sha256:bc41182d7ef5ffc53a40b044e725193bc10142a1243f395ee852a8d9730fc2ad
Manifests:
Name: localhost:5000/library/alpine:latest#sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870
Digest: sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/amd64
Name: localhost:5000/library/alpine:latest#sha256:5da989a9a3a08357bc7c00bd46c3ed782e1aeefc833e0049e6834ec1dcad8a42
Digest: sha256:5da989a9a3a08357bc7c00bd46c3ed782e1aeefc833e0049e6834ec1dcad8a42
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/arm/v6
Name: localhost:5000/library/alpine:latest#sha256:0c673ee68853a04014c0c623ba5ee21ee700e1d71f7ac1160ddb2e31c6fdbb18
Digest: sha256:0c673ee68853a04014c0c623ba5ee21ee700e1d71f7ac1160ddb2e31c6fdbb18
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/arm/v7
Name: localhost:5000/library/alpine:latest#sha256:ed73e2bee79b3428995b16fce4221fc715a849152f364929cdccdc83db5f3d5c
Digest: sha256:ed73e2bee79b3428995b16fce4221fc715a849152f364929cdccdc83db5f3d5c
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/arm64
Name: localhost:5000/library/alpine:latest#sha256:1d96e60e5270815238e999aed0ae61d22ac6f5e5f976054b24796d0e0158b39c
Digest: sha256:1d96e60e5270815238e999aed0ae61d22ac6f5e5f976054b24796d0e0158b39c
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/386
Name: localhost:5000/library/alpine:latest#sha256:fa30af02cc8c339dd7ffecb0703cd4a3db175e56875c413464c5ba46821253a8
Digest: sha256:fa30af02cc8c339dd7ffecb0703cd4a3db175e56875c413464c5ba46821253a8
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/ppc64le
Name: localhost:5000/library/alpine:latest#sha256:c2046a6c3d2db4f75bfb8062607cc8ff47896f2d683b7f18fe6b6cf368af3c60
Digest: sha256:c2046a6c3d2db4f75bfb8062607cc8ff47896f2d683b7f18fe6b6cf368af3c60
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/s390x
$ regctl image config localhost:5000/library/alpine:latest
{
"created": "2022-08-09T17:19:53.47374331Z",
"architecture": "amd64",
"os": "linux",
"config": {
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:994393dc58e7931862558d06e46aa2bb17487044f670f310dffe1d24e4d1eec7"
]
},
"history": [
{
"created": "2022-08-09T17:19:53.274069586Z",
"created_by": "/bin/sh -c #(nop) ADD file:2a949686d9886ac7c10582a6c29116fd29d3077d02755e87e111870d63607725 in / "
},
{
"created": "2022-08-09T17:19:53.47374331Z",
"created_by": "/bin/sh -c #(nop) CMD [\"/bin/sh\"]",
"empty_layer": true
}
]
}
$ regctl image mod localhost:5000/library/alpine:latest \
--create mod --to-oci \
--annotation new.annotation=value \
--label some.label=1234
localhost:5000/library/alpine:mod
$ regctl manifest get localhost:5000/library/alpine:mod
Name: localhost:5000/library/alpine:mod
MediaType: application/vnd.oci.image.index.v1+json
Digest: sha256:5e1e3ed73857b08895477418bdd2b73cc9536886d84d98ef986eacca08e100ea
Annotations:
new.annotation: value
Manifests:
Name: localhost:5000/library/alpine:mod#sha256:f457cc17d630de3464ee3cd796fe83527a3daf3d1d28f710ed65b7162c29a632
Digest: sha256:f457cc17d630de3464ee3cd796fe83527a3daf3d1d28f710ed65b7162c29a632
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/amd64
Name: localhost:5000/library/alpine:mod#sha256:a442ff642289b8b9a4268451c29fc7ce8f3685ba08b32adb1fd9ddd36b4f46e4
Digest: sha256:a442ff642289b8b9a4268451c29fc7ce8f3685ba08b32adb1fd9ddd36b4f46e4
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/arm/v6
Name: localhost:5000/library/alpine:mod#sha256:003520fdc1749c2bd2d49781b24ae6937a219576541d20754124c24467e75ffc
Digest: sha256:003520fdc1749c2bd2d49781b24ae6937a219576541d20754124c24467e75ffc
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/arm/v7
Name: localhost:5000/library/alpine:mod#sha256:624a37e9b645a5286db52b2a8536f43bb64e0352fa10e847f4f049b4773046fc
Digest: sha256:624a37e9b645a5286db52b2a8536f43bb64e0352fa10e847f4f049b4773046fc
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/arm64
Name: localhost:5000/library/alpine:mod#sha256:9fbcc84ca534fa1d3b0047226860e39321da082615bdef03946edd5225952217
Digest: sha256:9fbcc84ca534fa1d3b0047226860e39321da082615bdef03946edd5225952217
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/386
Name: localhost:5000/library/alpine:mod#sha256:08246b80173b3ace4446aca1e26406d1cef1eaea29126ab3ebe964e0fbba4dd9
Digest: sha256:08246b80173b3ace4446aca1e26406d1cef1eaea29126ab3ebe964e0fbba4dd9
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/ppc64le
Name: localhost:5000/library/alpine:mod#sha256:945b2dab97c5518c276e53df551871ec089736f3abc7fe62003923b04ed9bcb5
Digest: sha256:945b2dab97c5518c276e53df551871ec089736f3abc7fe62003923b04ed9bcb5
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/s390x
$ regctl image config localhost:5000/library/alpine:mod
{
"created": "2022-08-09T17:19:53.47374331Z",
"architecture": "amd64",
"os": "linux",
"config": {
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Labels": {
"some.label": "1234"
}
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:994393dc58e7931862558d06e46aa2bb17487044f670f310dffe1d24e4d1eec7"
]
},
"history": [
{
"created": "2022-08-09T17:19:53.274069586Z",
"created_by": "/bin/sh -c #(nop) ADD file:2a949686d9886ac7c10582a6c29116fd29d3077d02755e87e111870d63607725 in / "
},
{
"created": "2022-08-09T17:19:53.47374331Z",
"created_by": "/bin/sh -c #(nop) CMD [\"/bin/sh\"]",
"empty_layer": true
}
]
}

Answer 2

But if you modify an image in any way the image digest will change and thus you have a different image.