#OCI Labels vs Annotations

1 messages · Page 1 of 1 (latest)

heavy cedar
#

I'm looking for a practical rule of thumb on when to use Container.WithLabel vs Container.WithAnnotation. While searching the web, I came across some articles suggesting that annotations apply to manifests and indices while labels apply to images, but what are the practical consequences of that? When should I use which?

paper plover
# heavy cedar I'm looking for a practical rule of thumb on when to use Container.WithLabel vs ...

👋 The answer is in the OCI image spec. https://github.com/opencontainers/image-spec/blob/main/annotations.md
and https://github.com/opencontainers/image-spec/blob/main/annotations.md#back-compatibility-with-label-schema specifically 🙏

GitHub
image-spec/annotations.md at main · opencontainers/image-spec

OCI Image Format. Contribute to opencontainers/image-spec development by creating an account on GitHub.

heavy cedar
#

Thanks. I've already read through the spec and followed the issues and PR on GitHub, but I'm still not seeing a practical explanation for why one would use labels over annotations beyond "corporate policies" and compatibility with Dockerfiles using the LABEL statement (aren't those the same as annotations? 😕). I'm curious - was Container.WithLabel mainly added for backwards compatibility? Would you recommend using Container.WithAnnotation exclusively in 2025?

GitHub
Implement labels for Dockerfile build · Issue #4245 · dagger/dagger

This allows a user to add labels the Dockerfile build input Label { key: String! value: String! } type Directory { dockerBuild(dockerfile: String, platform: Platform, labels: [Label!]): Container! }

GitHub
Implement label API by grouville · Pull Request #4387 · dagger/da...

Closes #4245
Closes #3887
Allows user to have the complete control over the labels of a given container:

Add a label (withLabel API)
Remove a label (withoutLabel API)
Print the value of a single l...