docker build with OCI layouts does not preserve OCI annotations set on individual layers

[xnox]

Description

I am using docker build
The FROM image is in OCI format
The FROM image has OCI annotations on the OCI manifest and in each OCI layer
I am using containerd backend and output to OCI format as well
The produced image tarball did not preserve OCI annotations on neither the OCI manifest nor the OCI layer

Please consider preserving OCI image.layer annotations during such builds

Note, these are different than the image.manifest level annotations

[tonistiigi]

Annotations on a FROM image belong to that image. They are not inherited or copied to your build result.

[xnox]

Annotations on a FROM image belong to that image. They are not inherited or copied to your build result.

Yes, I am talking about annotations on the layer. They are not typically set.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:de13bd2af1370e0c15101ad4aceb5e3cad377e7134b396b5d870c17967e66354",
    "size": 2473
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:94209f9e5d6233ea0ed8a537c724e7dc3182de20438ff4d7ad45c155505de97f",
      "size": 2832511,
      "annotations": {
        "org.opencontainers.image.authors": "Authors for golden images",
        "org.opencontainers.image.created": "2025-10-15T15:46:07Z",
        "org.opencontainers.image.source": "https://github.com/organization/repository/tree/main/images/blah",
        "org.opencontainers.image.vendor": "Organization"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:9696f4818c65d03d552967597498c2dfcb0c8cc6aa2dfaefc5ea054ada4a1a1a",
      "size": 3125237,
      "annotations": {
        "org.opencontainers.image.authors": "Authors for golden images",
        "org.opencontainers.image.created": "2025-10-15T15:46:07Z",
        "org.opencontainers.image.source": "https://github.com/organization/repository/tree/main/images/blah",
        "org.opencontainers.image.vendor": "Organization"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:acfb0b872e8ba75a2db5875f0dbbcffe141f6ccd0e2790c00b65c35c3c8076d9",
      "size": 417014,
      "annotations": {
        "org.opencontainers.image.authors": "Authors for Go apps department ",
        "org.opencontainers.image.created": "2025-10-15T15:46:07Z",
        "org.opencontainers.image.source": "https://github.com/organization/repository/tree/main/images/blah",
        "org.opencontainers.image.vendor": "Organization"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:5184222d8983f78e1d3e4746edc4ec747c6a8f0a5522d6e579848c62e09c23ba",
      "size": 172101,
      "annotations": {
        "org.opencontainers.image.authors": "Authors for Go apps department",
        "org.opencontainers.image.created": "2025-10-15T15:46:07Z",
        "org.opencontainers.image.source": "https://github.com/organization/repository/tree/main/images/blah",
        "org.opencontainers.image.vendor": "Organization"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:4072975bfef6e00ccd67d563bbdc1a03b06127b3b733950768e08ef49eba29e7",
      "size": 130078,
      "annotations": {
        "org.opencontainers.image.authors": "Authors for a particular app",
        "org.opencontainers.image.created": "2025-10-15T15:46:07Z",
        "org.opencontainers.image.source": "https://github.com/organization/repository/tree/main/images/blah",
        "org.opencontainers.image.vendor": "Organization"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.image.authors": "Authors for particular app customized for an environment",
    "org.opencontainers.image.created": "2025-10-15T15:46:07Z",
    "org.opencontainers.image.source": "https://github.com/organization/repository/tree/main/images/blah",
    "org.opencontainers.image.vendor": "Organization"
  }
}

If you see above the last dictionary of annotations is on the image; and yes those should be updated with every dockerfile build.

But the annotations attached to layers; which get reused and appended too in subsequent builds, ideally should persist those annotations in a similar fashion how in config history is preserved.

This way, when multiple teams pass golden / derived images between themselves, the annotations can denote which layers were build by golden images team; which layers came from a department; and which layers are unique to a particular app or deployment. If those annotations would be preserved.

With currently OCI / containerd build backend, even though the layers digests are preserved in subsequent builds, the annotations attached to a layer are currently stripped and dropped.

And for example, if layers do not have annotations, it would make sense to transfer previous base image annotations to the last layers prior to start of adding new layers; and add new layers with annotations & new final image annotatins.

[xnox]

adjusted title and the initial description to make this more clear.