regclient / regclient

Current Behavior

I am using a Docker Registry on Artifactory in our company network. I work with Windows Docker Containers built using Docker Desktop and/or Docker Engine. I want to use regctl to see if my images are based on the latest windows base images as released by Microsoft. To do this, I can use:

$ regctl image check-base myartifactory-repo-url/mypath/myimage:mytag --base mcr.microsoft.com/dotnet/framework/runtime:4.8-windowsservercore-ltsc2022

It accurately gives me a zero or non-zero exit code as expected, depending on whether my image is in need of an update.

However, as I have numerous images with different base images, I want to use the OCI annotation org.opencontainers.image.base.name to identify the base label. To this end, I added LABEL org.opencontainers.image.base.name=mcr.microsoft.com/dotnet/framework/runtime:4.8-windowsservercore-ltsc2022 to my Dockerfiles. However, when I point regctl at the image, I get the following behavior:

$ regctl image check-base myartifactory-repo-url/mypath/myimage:mytag
image does not have a base annotation, base image must be provided

If I verify the image with regctl image inspect, the label exists with the expected name and value:

    "Labels": {
      "redacted": "redacted",
      "OS_Version": "ltsc2022",
      "org.opencontainers.image.base.name": "mcr.microsoft.com/dotnet/framework/runtime:4.8-windowsservercore-ltsc2022",
      "org.opencontainers.image.source": "https://redacted-path-to-where/you/find/the/Dockerfile",
      "org.opencontainers.image.version": "1.2.3redacted"
    },

Note that I'm not currently using ...base.digest. Looking into the regctl source code, to produce the error message given above, only the ...base.name annotation is actually checked, so this does not have any influence:

regclient/image.go

Line 248 in 281b077

if baseName, ok := annot[types.AnnotationBaseImageName]; ok {

Expected Behavior

When I set the label org.opencontainers.image.base.name, regctl should pick up on this and be able to determine the name of the base image for the update check.

Steps To Reproduce

Use the following Dockerfile (Change to ltsc2019 if you are on Windows 10):

FROM mcr.microsoft.com/dotnet/framework/runtime:4.8-windowsservercore-ltsc2022
LABEL org.opencontainers.image.base.name=mcr.microsoft.com/dotnet/framework/runtime:4.8-windowsservercore-ltsc2022

Run docker build -t myregistry/exampleimage:ltsc2022. Adjust the image name and tag to your registry and liking, actual values don't matter.
Run docker push. I only have our company Artifactory around to try.
run regctl image check-base myregistry/exampleimage:ltsc2022.
See error message.

Version

$ .\regctl-windows-amd64.exe version
VCSTag:     v0.5.4
VCSRef:     48a20981b2db4f72fdcafb16af46e3bf6d8f86d5
VCSCommit:  48a20981b2db4f72fdcafb16af46e3bf6d8f86d5
VCSState:   clean
VCSDate:    2023-11-09T20:47:01Z
Platform:   windows/amd64
GoVer:      go1.21.4
GoCompiler: gc

Environment

Running as binary or container: binary
Host platform: Windows 11 Pro, 64bit
Registry description: Company-local Artifactory, Repository has Package-Type "Docker", Repository-Layout "simple-default"
Windows containers, not Linux containers running on Windows

Anything else

I might be confused about the relationship of Docker Labels and OCI Annotations. However, two days of googling have given me the impression that they are the same - or should at least be treated as such.

Labels and annotations are different fields in an image. Labels are part of the config blob, while annotations are defined on the image or index manifest. They have the same syntax, but tooling looking in one place won't see it if you create them in another. Buildx just released 0.12 yesterday with the option to specify annotations using an --annotation flag (see buildx PR 2020).

With regctl, there are a few options to configure annotations. To convert labels to annotations, there's:

regctl image mod --label-to-annotation --replace $image

Or you can set the specific annotations with:

regctl image mod --annotation-base ${base_image},${base_digest} --replace $image

Both of those commands require push access to the image repo, and will change the digest of the referenced image since they are modifying it (there's also a --create option to create a different image/tag, leaving the original image unchanged).

Thank you for this clarification. As Buildx is not yet available for Windows containers (only for Linux containers on Windows), I'm stuck with post-processing the images - which in my case should be doable.

Huge Edit: I was into putting together a new report on how the regctl commands above just don't do anything. While testing my steps to reproduce, I suddenly started to get my desired response from check-base - but only for the one image I was toying with, even though the SHA of the image hasn't changed (docker pull claims "image up to date"). So there may also be some artifactory caching distribution somethign somethign magic at play here, that means that updates to existing images don't show up immediately.

So what I'll do now is to put the --replace solution into the nightly (re)build and see what's what after the weekend.

If the annotation is only on the index, the underlying image digest will be unchanged, and docker may not indicate the change. The layers are also unchanged, so a pull should be nearly instantaneous if you've pulled the other image. There are options to add the annotation to all manifests ([*] in front of the annotation name) but if you are only checking the index, those aren't needed. The annotations and changed digest will be visible in regctl manifest get.

Testing has revealed: If I run regctl image mod --label-to-annotation --replace $image during our nightly build, Artifactory reports the annotations expected by regctl image check-base by the time I am trying to do the update check.

So, problem solved. Thank you!