Clarrify usage of predefined annotations as labels within image config

[sudo-bmitch]

Currently the annotations.md indicates it is used for the the annotations fields in image manifests and descriptors. And it also indicates it is a replacement for label-schema.org. However, without better tooling support for setting image annotations at build time, most users are using the org.opencontainers.image.* annotations as image labels that we define in the config. There should be clarification whether the predefined annotation keys are also appropriate for image labels in annotation.md.

[jonjohnsonjr]

It seems like we suggest this, already?

From here:

• Labels object, OPTIONAL

The field contains arbitrary metadata for the container. This property MUST use the annotation rules.

[sudo-bmitch]

It seems like we suggest this, already?

I'm not sure that suggests is even the right word, feels fairly ambiguous to me. The rules section is a different heading from the predefined keys. And the following could be read as the image manifest being a different specification from the config:

Keys using the org.opencontainers.image namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications

If OCI thinks these are interchangable, that's fine with me, and it would be helpful if that was called out in the spec where annotations are described. That way we have somewhere to point users that may be hesitant to use these annotations as labels.

[jonjohnsonjr]

@vbatts added this in #371 -- do you have any opinions? I don't have much familiarity with how folks use labels in practice.

[ChristianCiach]

I was just bitten by this. I think most people don't really know the difference between labels and annotations. At least I didn't, until I found out that Harbor parses the annotations, but not the labels: goharbor/harbor#13498 (comment)

[jonjohnsonjr]

Regarding the harbor issue: just speaking from the perspective of a registry, I think that annotations are preferred here. Parsing labels requires reading a config blob, which is otherwise unnecessary for registry operations. Registries (usually) already need to parse manifests for ref counting purposes, so annotations are readily available.

My feedback here isn't really actionable, just trying to explain why that would be the case. Labels are easier for clients to deal with, whereas annotations are easier for registries to deal with (and hard for clients for historical reasons). I'm not really sure how to resolve that difference.