From Fedora Project Wiki

Container Images Labels

Summary

The org.opencontainers.image.name and org.opencontainers.image.license labels in Fedora container images get changed to org.opencontainers.image.title and org.opencontainers.image.licenses to more closely align with The OpenContainers Annotations Spec.

Owner


Current status

Detailed Description

Starting with Fedora 40, the Fedora container images contain labels in the org.opencontainers.image namespace: 

$ skopeo inspect --config docker://registry.fedoraproject.org/fedora:39 | jq .config.Labels
{
  "license": "MIT",
  "name": "fedora",
  "vendor": "Fedora Project",
  "version": "39"
}
$ skopeo inspect --config docker://registry.fedoraproject.org/fedora:40 | jq .config.Labels
{
  "io.buildah.version": "1.39.2",
  "license": "MIT",
  "name": "fedora",
  "org.opencontainers.image.license": "MIT",
  "org.opencontainers.image.name": "fedora",
  "org.opencontainers.image.url": "https://fedoraproject.org/",
  "org.opencontainers.image.vendor": "Fedora Project",
  "org.opencontainers.image.version": "40",
  "vendor": "Fedora Project",
  "version": "40"
}

They seem to be modeled after The OpenContainers Annotations Spec. That specification is about image manifest annotations and not about labels per se, yet the similarity is very close.

The specification however does not list org.opencontainers.image.name and org.opencontainers.image.license, instead it mentions org.opencontainers.image.title and org.opencontainers.image.licenses.

The proposal is to change the labels to match the annotation specification to align with the spec's guidance:

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.


Feedback

In https://pagure.io/fedora-kiwi-descriptions/pull-request/251, Neal suggested to add the new (correct) labels but keep the old ones as well. The problem is that the labels get inherited by any layered image which uses Fedora base images. And tools like docker build do not make it easy to remove the labels. You can overwrite them one by one but getting rid of them is not directly supported. So we are forcing maintainers of layered images to deal with (overwrite) labels that shouldn't even be there to start with. I actually started digging into the issue because I noticed "org.opencontainers.image.name": "fedora" in our FreeIPA container images (https://github.com/freeipa/freeipa-container).

We can add the correct labels org.opencontainers.image.title and org.opencontainers.image.licenses to Fedora 42 and 43 images before Fedora 44 release, so that any dependency / tooling can adapt and start using them with the released images.

In https://pagure.io/fedora-kiwi-descriptions/pull-request/251, Neal asked if the non-namespaced legacy labels should be dropped as part of this change. Jan does not have a preference and would welcome other (FESCO) opinions -- the legacy labels have been around much longer so chances that something somewhere depends on them is much bigger; on the other hand, the overall move seems to be towards annotations and not labels, so it does not really matter if the legacy labels stay there.

Similar question / proposal was done by Stephen in https://discussion.fedoraproject.org/t/f44-change-proposal-containerimageslabels-selfcontained/179010/3.

In https://discussion.fedoraproject.org/t/f44-change-proposal-containerimageslabels-selfcontained/179010/5 Simon wonders if for one release the labels being removed should have information about the new label names. Jan worries that such value can potentially break (unlikely) automated uses worse than just not having the labels at all.

In https://discussion.fedoraproject.org/t/f44-change-proposal-containerimageslabels-selfcontained/179010/7 Göran proposes to have a release note about this change. Jan does not object but worries that having a release note about such triviality might pollute the release notes and decrease their usefulness.

Benefit to Fedora

This change makes Fedora better align with existing external specification.

Scope

  • Proposal owners:
    • PR https://pagure.io/fedora-kiwi-descriptions/pull-request/251 should be all that is needed to get this change in.
    • PRs against Fedora 43 and 42 can be filed to add the correct labels but not remove the .name and .license, so that any setup or tooling can start using them on the released container images, making migration easier.
  • Other developers:
    • If other developer's packages or tooling depend on the org.opencontainers.image.name and org.opencontainers.image.license labels in Fedora base container images, they will need to adapt to the new names.
  • Policies and guidelines: N/A (not needed for this Change)
  • Trademark approval: N/A (not needed for this Change)
  • Alignment with the Fedora Strategy:
    • TL;DR

Upgrade/compatibility impact

Any setup which relies on the org.opencontainers.image.name and org.opencontainers.image.license container image labels will need to be updated.


Early Testing (Optional)

Do you require 'QA Blueprint' support? No.

How To Test

Pull fresh registry.fedoraproject.org/fedora:rawhide image by your podman, docker, docker-compose, or Kubernetes workload and see it working as it did before, even if the two labels have changed.

User Experience

No user visible behaviour change.

Dependencies

None.

Contingency Plan

  • Contingency mechanism: (What to do? Who will do it?) Nothing bad happens if this change is not merged for the release, it just won't get done.
  • Contingency deadline: N/A
  • Blocks release? No


Documentation

N/A

Release Notes

Retrieved from "https://fedoraproject.org/w/index.php?title=Changes/ContainerImagesLabels&oldid=762235"