Proposal: Annotation for URL to artwork/logo for an OCI Image

[AlexGustafsson]

Proposal

Add an annotation like org.opencontainers.image.artwork which contains a URL to an image (as in a logo or the like) for an OCI image, much like a favicon.

User stories

• As an OCI image author I'd like the project's logo to be seen alongside information about the OCI image on sites such as Docker Hub, GHCR, Quay and tools such Renovate, Socket(.dev).

• As a developer of a service collecting information about container images, I'd like to show the users artwork / a logo for the image to help the user easily recognize the service contained in an OCI images.

Background

OCI images are maintained in different ways, in different places. Be it pushing an image built locally or pushing an image in a CI/CD pipeline with code hosted here on GitHub. Some code hosting sites may also act as an OCI registry. Some developers might push to several registries. Some sights may mirror the images or make them discoverable through various UIs.

Today, the standardized annotations provide a lot of good information about to ensure that the OCI image developers can annotate their images once and ensure that information is spread across all of these sites. Similarly, developers of such sites can reuse the information contained in the annotations to display information about the OCI images.

However, there is no standardized way to communicate what artwork / logo should be associated with the OCI image. This requires OCI image developers to upload an image to each site separately. For developers of services not used directly by the OCI image developer, the only choice is to try to identify artwork based on heuristics or simply falling back to a placeholder.

[sudo-bmitch]

Hi @AlexGustafsson. Do you know of any projects doing this already with their own annotations? OCI is typically a trailing spec, standardizing behavior that others have already proven to work.

[tianon]

As much as I like the thought, this seems like a privacy problem -- perhaps if it referenced a blob inside the image, but that's much more complicated for registries to implement support for (especially as it would have to be part of the layers/config somehow).

(If it's not already something you're familiar with, see https://en.wikipedia.org/wiki/Spy_pixel for more details on the privacy attack vector.)

[AlexGustafsson]

I share your concerns, @tianon.

One mitigation from a website's point of view is to configure a restrictive content security policy, allowing only some known "well-behaved" sites to serve their users images. Allowing images hosted on GitHub, for example. It would make it more inconvenient for smaller registries.

Registries could also decide to proxy images for caching and pre-processing purposes much like GitHub's avatars (in that they have a proxying server which processes and caches various sizes).

Referencing a blob inside of the image does have the upside of solving the transport of the image, so to say. If it's a plain URL, registries would need to fetch the images beforehand or expose the URL to the user, increasing the privacy issues as you've mentioned. Referencing a blob requires implementations to consider the risks and serve the images themselves.

As for precedence for including a blob for such things. In Docker buildx v0.11, Docker started to include provenance by default. It's treated as a manifest referencing a blob of their custom content type. I'd say that this shows that registries already have to deal with different types of manifests being referenced. I'm not sure at which layer you imagined the image would be included, @tianon. But doing it like with the provenance blob would be the least obtrusive way I guess?

Example "chain" of manifests to the Docker provenance blob.

=== RUN   TestX
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    // ... additional manifests
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:6238d167848ccace8ff61fbcdeb11edb19ceea63cde3895855faebb7a05fd9d3",
      "size": 567,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:3a7be4a90352f2217eebbc8d5a6333bdd2d468cdf90c5173c307c55c3e4edc06",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    }
]

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:2ed41686faa7eab0a4bd69d3bbb64dfe0e32209efc9c89d1ecd8ccd273acc4c9",
    "size": 167
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:f94abb66332036dbf3b2ef8fa341cdca811e08812abbc221391f605ece43b38d",
      "size": 17534,
      "annotations": {
        "in-toto.io/predicate-type": "https://slsa.dev/provenance/v0.2"
      }
    }
  ]
}

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.2",
  // ...
}

[AlexGustafsson]

@sudo-bmitch I haven't seen it done through annotations, no. I know that Docker Hub uses an API for their "library images" (https://hub.docker.com/api/media/repos_logo/v1/library%2Ftraefik, for example). For other users they are using Gravatar to host images, such as for home-assistant: https://www.gravatar.com/avatar/461df105cc6cfcf386ebd5af85b925dc?s=120&r=g&d=404. The hash is the md5sum of the user's/organization's email, hello@home-assistant.io in this case. The user needs to configure an email to use for this purpose.

[AlexGustafsson]

One similar form of annotation came to mind; open graph. It's essentially what OCI annotations are trying to achieve but for HTML documents. See for example the "social preview" of GitHub:

<meta property="og:title" content="GitHub - opencontainers/image-spec: OCI Image Format">
<meta property="og:description" content="OCI Image Format. Contribute to opencontainers/image-spec development by creating an account on GitHub.">
<meta property="og:image" content="https://opengraph.githubassets.com/6150aa2d7484717f30936e1093580b9e4022e7785b60a1f2d640aecf760822e3/opencontainers/image-spec">

[sudo-bmitch]

I'd like to see an exact solution implemented using OCI images. Different problems being solved could miss issues like the one Tianon mentions. This could be a fork of a popular registry and build tooling to show a full end to end PoC, but preferably it would be something merged by a project and in active use, where the only change would be an OCI annotation name rather than a project specific annotation.

Without that, I'm okay with leaving the issue open for you and others to discuss, but I wouldn't be willing to approve a PR.

[AlexGustafsson]

Thank you for your time and insight, @sudo-bmitch!

[AlexGustafsson]

I've found a few "initiatives":

The zot registry initially used annotations (project-zot/zot#833). That support seems to since have been removed, now only referenced in their UI - but no APIs. They then seemed to be looking for artifacts of a certain zot-specific type (project-zot/zot#1018). Now they seem to be looking into leveraging the referrers API to identify a logo artifact: project-zot/zui#289.

The harbor registry is using artifacts for the purpose: https://goharbor.io/docs/2.3.0/administration/user-defined-oci-artifact/.

I'll investigate it a bit more and update this issue if there's anything worth mentioning. It seems rather clear that there doesn't seem to be anyone trying to use annotations for this (at least any more). Instead the need seems to be a standard way to communicate an OCI artifact to use as a logo.