buildkit preserves labels from base image

[rittneje]

We have a few images that use ubuntu:jammy as a base. We noticed that the resulting images include two labels - org.opencontainers.image.ref.name=ubuntu and org.opencontainers.image.version=22.04 - which it must have inherited from ubuntu:jammy.

This behavior is both unexpected and undesirable. Labels should never be inherited from the base image, especially not those particular labels.

[jedevc]

This is by design (unfortunately, imo), see https://docs.docker.com/engine/reference/builder/#label.

Labels included in base or parent images (images in the FROM line) are inherited by your image. If a label already exists but with a different value, the most-recently-applied value overrides any previously-set value.

We can't change this default, since users may rely on this today.

Ideally, if upstream images don't want this kind of behavior, they should prefer to use OCI annotations which perform a similar purpose to labels but are not inherited. cc @yosifkit do you know if there's a specific reason that library/ubuntu uses labels and not annotations?

[rittneje]

@jedevc There really should at least be a way to opt out of inheriting labels to address this design flaw. Then eventually that should be the default and people with the niche use case of wanting them inherited should be forced to opt in.

[rittneje]

Also, annotations do not show up in the Artifactory UI. Only labels do. So annotations are not useful for us.

I will also add that adding "annotations" as a distinct concept from "labels" was a very bad idea. Now we have two concepts that serve the exact same purpose.

[yosifkit]

do you know if there's a specific reason that library/ubuntu uses labels and not annotations?

As far as I can tell, it looks like the labels were added in docker-library/official-images#13950. I'm not sure why they were added or if they considered annotations. Because of this inheritance problem, we neither recommend nor deny labels on Docker Official Images. Image maintainers may add labels on the official images that they maintain. For new labels, we ensure that they follow the image spec: https://github.com/opencontainers/image-spec/blob/v1.0.1/annotations.md.

[jedevc]

Thanks @yosifkit ❤️ The policy makes sense, definitely feels tricky to strike a balance here.

@rittneje I'm not convinced we want to try and change such a long-standing behavior in docker, especially when there's a more flexible alternative supported by most tooling that doesn't suffer from this problem. Annotations are not the same as labels, and support being set in multiple different locations on an image - additionally, they don't modify the config for an image (which is why they're not inherited), and also don't change the digest of an image config on a change.

Artifactory not displaying annotations feels like a UI issue on their side, I'd recommend raising with the team there - annotations are increasingly in use in the container image ecosystem.

[rittneje]

@jedevc I highly doubt most users expect or want labels to be inherited. Also I have no control over whether the base image chooses to include labels, so there really is no solution here other than buildkit adding the ability to say not to inherit them. We are raising an issue with Artifactory, but historically getting them to do anything has been difficult.

@yosifkit That policy does not make sense. Labels need to be actively discouraged on official images as they only cause problems. And the OCI annotations are intended to be annotations, not labels.