How to set layer annotation?

[rgl]

How can I set the layer title annotation? or even, any annotation to a layer?

Currently, I'm trying:

oras push \
    --plain-http \
    --artifact-type application/octet-stream \
    --annotation org.opencontainers.image.title=vmlinuz \
    "$zot_host/tinkerbell-debian-osie/vmlinuz:latest" \
    "$t/live/vmlinuz"

But this ends up with:

# jq </opt/zot/data/tinkerbell-debian-osie/vmlinuz/blobs/sha256/0df89107166152b5d09ae4dc3247cf52157339c303d5d31dfbe31979e21426d5 
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/octet-stream",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "digest": "sha256:0f6e36da407dcb3124b09cc78ff0522a809ee6f1e3d9b55b1d2e683b4d88b2ec",
      "size": 7035328,
      "annotations": {
        "org.opencontainers.image.title": "/tmp/tmp.LEeZgNO4F7.debian-osie/live/vmlinuz"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "2023-05-09T17:49:36Z",
    "org.opencontainers.image.title": "vmlinuz"
  }
}

Which did not set the layer annotation, instead it set the manifest / root level annotation.

[sajayantony]

Currently I don't think there is support for layer annotations.
One way I can think of would be to use --oci-layout to create the image and get the manifest

❯ mkdir ./layout
❯ oras push --oci-layout ./layout:v1 ./log.txt
Uploading e3b0c44298fc log.txt
Pushed [oci-layout] ./layout:v1
Digest: sha256:ae31301052c0a0ad6d2166605018bb3dedb9b3a0889611ee83bf6fdbded0aad7

❯ oras manifest get --oci-layout ./layout:v1 --pretty > manifest.json
❯ vim ./manifest.json  ## Edit the manifest manually and add a layer annotation. 

# update the layout with the new manifest.
❯ oras manifest push --oci-layout ./layout:v2 ./manifest.json
Pushed [oci-layout] ./layout:v2
Digest: sha256:c4ccaaae59c8b2659e533ad1c3e0238792d970f6146e85ae5c721f7a622e3c80

❯ oras manifest get --oci-layout ./layout:v2
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.unknown.config.v1+json",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "size": 0,
      "annotations": {
        "org.opencontainers.image.title": "log.txt",
        "foo" : "bar"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "2023-05-09T22:05:24Z"
  }
}

# Copy your image to the target registry
❯ oras cp --from-oci-layout ./layout:v2 localhost:5001/test-oci:layer-annotations
Exists  e3b0c44298fc log.txt
Copied [oci-layout] ./layout:v2 => [registry] localhost:5001/test-oci:layer-annotations
Digest: sha256:c4ccaaae59c8b2659e533ad1c3e0238792d970f6146e85ae5c721f7a622e3c80

[qweeah]

@rgl You can use annotation file flag --annotation-file, see docs here.

E.g. if you want to add "foo":"bar" annotation for layer of the file /tmp/tmp.LEeZgNO4F7.debian-osie/live/vmlinuz, you need to 1) prepare below json (say it's named as anno.json)

{
  "/tmp/tmp.LEeZgNO4F7.debian-osie/live/vmlinuz": {
    "foo": "bar"
  }
}

2. run oras push with --annotation-file specified

oras push \
    --plain-http \
    --artifact-type application/octet-stream \
    --annotation org.opencontainers.image.title=vmlinuz \
    "$zot_host/tinkerbell-debian-osie/vmlinuz:latest" \
    "$t/live/vmlinuz" \
    --annotation-file anno.json

[sajayantony]

Upvoted. @qweeah thanks for pointing out the annotation file docs.

[rgl]

Thanks for pointing the --annotation-file!

How about setting the actual file title? Do I really have to first change the the files directory before the push in order for oras to create a relative file path title annotation?

[qweeah]

The path of the annotation file can be relative or absolute, there is no requirement.

[qweeah]

The file path used as key of a layer's annotations MUST be identical to the layer's org.opencontainers.image.title, oras will do full match when applying the annotation file.

You are using the absolute path $t/live/vmlinuz so the key has to be $t/live/vmlinuz

[rgl]

So I really have to first change the current directory before oras push to have a "clean“/relative file title annotation?

[qweeah]

Also, worth mentioning that it's not a good practice to use absolute path when pushing artifacts, when you pull the uploaded $zot_host/tinkerbell-debian-osie/vmlinuz:latest, the layer vmlinuz will be downloaded to exactly into /tmp/tmp.LEeZgNO4F7.debian-osie/live/.

If you expect the artifact to be downloaded relatively into $WORK_DIR/live/ymlinuz, you may run the command like

pushd $t
echo '{"live/vmlinuz":{"foo":"bar"}}' > anno.json
oras push \
    --plain-http \
    --artifact-type application/octet-stream \
    --annotation org.opencontainers.image.title=vmlinuz \
    "$zot_host/tinkerbell-debian-osie/vmlinuz:latest" \
    "live/vmlinuz" \
    --annotation-file anno.json
popd

[qweeah]

So I really have to first change the current directory before oras push to have a "clean“/relative file title annotation?

Yes