append annotations instead of overwrite?

[rchincha]

oras push with annotations appears to assume a full update. Is there any way to perform an append to existing annotations?

[sajayantony]

+1 on this. I would like to propose an amend command that would

1. Add an annotation to an existing manifest
2. Put the new manifest
3. Delete the old manifest by digest so that we don’t have a dangling manifest but maybe have and option to skip delete(flag)

[qweeah]

Add an annotation to an existing manifest
Put the new manifest
Delete the old manifest by digest so that we don’t have a dangling manifest but maybe have and option to skip delete(flag)

@rchincha Will this functionally cover what you need?

[rchincha]

https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pushing-manifests

Note the two options that are possible.
By digest, it is a read-copy-update operation but by tag, it is a single in-situ update.
Thoughts?

[shizhMSFT]

Amending manifests can have unintended consequences that can affect existing attached artifacts, associated tags, and associated manifest list / index.

• Scenario 1: Amending annotations of a signed image
  • Modifying a manifest will result in a manifest with a new digest. The signature of the previous manifest gets invalidated immediately.
• Scenario 2: Amending annotations of an image tagged with latest, v1.1.0, v1.1, v1.
  • Modifying a manifest will result in a manifest with a new digest, which is not tagged.
  • If the previous manifest gets deleted, all associated tags are deleted.
  • Since there is no common API to reverse search the tags of the manifest being amended, the client has to scan all tags, which is inefficient with a repository full of tags, in order to tag the new manifest with the same tags.
• Scenario 3: Amending annotations of an image manifest, which is in a manifest list.
  • Modifying a manifest will result in a manifest with a new digest. Therefore, the corresponding manifest list is required to be updated.

[shizhMSFT]

+1 on this. I would like to propose an amend command that would

1. Add an annotation to an existing manifest
2. Put the new manifest
3. Delete the old manifest by digest so that we don’t have a dangling manifest but maybe have and option to skip delete(flag)

Although we don't have a command like oras manifest amend --annotation key=value, this operation can be equivalently achieved using the oras CLI built from the main branch by

1. oras manifest fetch localhost:5000/test:latest --descriptor -o manifest.json
2. Edit manifest.json with any tools
3. oras manifest push localhost:5000/test:latest manifest.json
   • Optionally, push with multiple tags once [Multiple tags at the once #355] get resolved.
4. Delete the old manifest by oras manifest delete localhost:5000/test@sha256:xxxx using the digest obtained from step 1.

[rchincha]

A slight enhancement ...

oras manifest amend --annotation key=value
^ a single key/val

(OR) this

oras manifest amend --annotation key=value,key=value,key=value...

[rchincha]

Amending manifests can have unintended consequences that can affect existing attached artifacts, associated tags, and associated manifest list / index.

* **Scenario 1**: Amending annotations of a signed image
  
  * Modifying a manifest will result in a manifest with a new digest. The signature of the previous manifest gets invalidated immediately.

* **Scenario 2**: Amending annotations of an image tagged with `latest`, `v1.1.0`, `v1.1`, `v1`.
  
  * Modifying a manifest will result in a manifest with a new digest, which is not tagged.
  * If the previous manifest gets deleted, all associated tags are deleted.
  * Since there is no common API to reverse search the tags of the manifest being amended, the client has to scan all tags, which is inefficient with a repository full of tags, in order to tag the new manifest with the same tags.

* **Scenario 3**: Amending annotations of an image manifest, which is in a manifest list.
  
  * Modifying a manifest will result in a manifest with a new digest. Therefore, the corresponding manifest list is required to be updated.

Signatures or any other invariant will be invalidated since the image manifest itself is changing, which may be ok and would requiring re-signing etc.

When we compose, extend or distribute images based off of other images, this is really the normal.

[shizhMSFT]

A slight enhancement ...

oras manifest amend --annotation key=value ^ a single key/val

(OR) this

oras manifest amend --annotation key=value,key=value,key=value...

If we decide to do this, a suggested command is

oras manifest amend --annotation key=value --annotation key=value ...

which is consistent with oras push.

[shizhMSFT]

/cc @FeynmanZhou @yizha1 for inputs.

[shizhMSFT]

There are more questions:

• We can amend an image manifest. How about OCI Index / manifest list?
• What's the UX to delete an annotation entry? Note: empty string is a valid value.

[FeynmanZhou]

Although we don't have a command like oras manifest amend --annotation key=value, this operation can be equivalently achieved using the oras CLI built from the main branch by

1. oras manifest fetch localhost:5000/test:latest --descriptor -o manifest.json

2. Edit manifest.json with any tools

3. oras manifest push localhost:5000/test:latest manifest.json

   • Optionally, push with multiple tags once [Multiple tags at the once #355] get resolved.

4. Delete the old manifest by oras manifest delete localhost:5000/test@sha256:xxxx using the digest obtained from step 1.

I think it's significant to support amend annotations to simplify the process above.

The effects on the existing attached artifacts, associated tags, and associated manifest list / index are acceptable but should be explicitly informed to users in the documentation or somewhere.

If we decide to do this, a suggested command is

oras manifest amend --annotation key=value --annotation key=value ...

The sample above only considered the case of appending new annotations. Should Delete or Modify annotations also be considered in the amending case?

[mathieu-benoit]

Just found this thread, I think it would be interesting indeed to have an easy way to add annotations on an existing image (not just via oras push), like we could do with crane mutate for example:

crane mutate --annotation foo=bar myimage

With the current state of oras, I was able to accomplish this like this:

oras manifest fetch myimage > manifest.json
jq '.annotations.foo = "bar"' manifest.json > manifest-tmp.json && mv manifest-tmp.json manifest.json

Just sharing.

[qweeah]

@mathieu-benoit Thanks for sharing. You can actually pipeline commands into one line like below:

IMAGE="myimage"
oras manifest fetch $IMAGE |jq '.annotations.foo = "bar"' |oras manifest push $IMAGE -

Also don't forget that the original manifest should be deleted via oras manifest delete

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[lexrj]

A teammate shared this ticket with me and I wanted to share my thoughts on this ticket as it's pending requirements.

As a user, my expectations for oras push are such that:

• annotations provided are merged with any annotations present in a provided manifest, giving preference for the annotations in --annotations

I would like the option to do the following things, both on oras push and as an update (e.g. oras manifest amend):

• set an annotation. If it already exists, replace it. If it does not, add it.
• remove an annotation, if it exists (the syntax I have seen for this before is key-, which is what kubernetes uses I believe)

I think separately there may be value in an option to a command such as oras manifest amend such as oras manifest amend --replace-annotations and --replace-annotations-file that simply replaces all annotations.

I do not believe, due to the complexities of deleting an existing manifest, that a manifest amend command should include a manifest delete operation. I believe this should be a separate command call made by users.

I do believe some users want to call a command like oras manifest amend image:tag and have it do all of the steps of:

• save tag name
• resolve digest
• push new manifest
• assign tag to new manifest's digest

Though I think this still has too many edge cases because of manifest lists and multiple tags.