allow oras command to skip referrer index clean up

[qweeah]

What is the version of your ORAS CLI

1.0.0

What would you like to be added?

To all oras commands causing referrers update, a new flag --gc should be added to skip deleting the dangling referrers index:

• By default, --gc is not set, dangling referrers index will not be clean
• If --gc is set, clean dangling referrers index when needed

This flag should be added to below commands

• oras attach
• oras cp
• oras manifest push
• oras manifest delete

Why is this needed for ORAS?

Referrer index is the alternative that OCI-1.0 compliant registries can utilize to support artifact reference types, see OCI spec 1.0-rc.2.

If a referrers index i exists for a certain subject artifact a. When adding or removing referrers for a, content of i will be updated and a new referrers index will be created and retagged following the tag schema. The index i contains obsolete content without any tag referenced.

When running commands like oras attach and oras cp, it's possible that the used token scope doesn't cover delete, or the registry might disable deletion, so it's better to provide oras an option to skip cleaning the dangling referrers index.

Also checked OCI spec, cleanup is optional for registry clients.

Are you willing to submit PRs to contribute to this feature?

• Yes, I am willing to implement it.

[FeynmanZhou]

Let me provide more context about this proposal. As I mentioned in #915 , ORAS CLI attempts to delete the dangling referrers index (outdated referrers index) by default for garbage collection purposes when attaching/pushing/copying an artifact in the OCI v1.0 compliant registry (referrers API is not supported).

However, Cleaning up dangling referrers index when pushing content to the OCI v1.0 compliant registry is not defined in OCI Distribution Spec v1.1.0-RC.2. This is not an officially recommended behavior from the OCI Distribution Spec. In fact, most of the OCI registries support garbage collection. Clean up might be out of the scope of a registry client like ORAS.

I think ORAS can give the responsibility to users or registry operators instead of helping users clean up those dangling referrers index from the registry automatically. Having a --gc flag to enable users to delete the outdated referrers index manually when pushing or operating artifacts in the registry would be much more flexible.

[FeynmanZhou]

linking oras-project/oras-go#510

[SteveLasker]

What is the expected behavior of this command if the user has push but not delete rights?

[sajayantony]

--gc seems overloaded without context. Are we GCing blobs, manifests, indexes, tags and list might go on. I can see the appeal of having a nice short flag, but it is really overarching. It would be clearer if the flag was indicative of the action like cleaning up referrers or tag-schema etc.

[qweeah]

What is the expected behavior of this command if the user has push but not delete rights?

which command are you referring to? Generally, the cmd execution should success if user doesn't enforce referrers GC.

[qweeah]

--gc seems overloaded without context. Are we GCing blobs, manifests, indexes, tags and list might go on. I can see the appeal of having a nice short flag, but it is really overarching. It would be clearer if the flag was indicative of the action like cleaning up referrers or tag-schema etc.

Trying to avoid tag schema or any other terms that normal user won't be able to understand. How about --gc-referrers? User should be able to understand referrers.

[FeynmanZhou]

opencontainers/distribution-spec#406 had a discussion about GC. It seems OCI Distribution-spec will not define GC policy and behavior for OCI registries in the short term.

[sajayantony]

Also wanted to include the option to consider manually scripting this. Manifest delete of a tagged digest to some extent is like pushing to latest.

Can the user script and pipe the output into manifest delete? Is this flag even needed since this is until we have referrers as default and this flag becomes obsolete and a no-op.

I not really certain this is necessary since manifest deletes of untagged manifests are handled by registries differently.

[qweeah]

Also wanted to include the option to consider manually scripting this. ... Can the user script and pipe the output into manifest delete?

This requires a change in oras-go, to return an aggregate error including all the dangling referrers index nodes that failed to be cleaned. I want to point out that if registry deletion is disabled, the piped command will still fail.

Is this flag even needed since this is until we have referrers as default and this flag becomes obsolete and a no-op.

No, but the proposed change is aiming for registries without referrers API. We can keep it in oras v1 which serves as long term support for OCI 1.0 registries and remove it in oras v2.

[sajayantony]

Even if we keep the flag scope it so that we don't end up with things like --insecure which caused and overly generic term to that could not be used again. I would say make it specific so that it avoids overarching implications. Steer clear of using generic terms that can apply to a wide range of things. Instead, opt for more specific terms that highlight the unique aspects of what you are naming.

For e.g --skip-delete-referrers to me this flag is clearer and yes it can apply to other commands and hopefully will not be passed by the user and we avoid confusion of the topic of GC that is a whole new can of worms.

[qweeah]

For e.g --skip-delete-referrers to me this flag is clearer and yes it can apply to other commands and hopefully will not be passed by the user and we avoid confusion of the topic of GC that is a whole new can of worms.

Agree. GC is too generic and we should avoid it. --skip-delete-referrers sounds good to me.

[FeynmanZhou]

--skip-delete-referrers sounds good to me.

[qweeah]

Had a discussion offline with @FeynmanZhou @yizha1 and @shizhMSFT, want to point out that to avoid breaking change, @shizhMSFT suggested to set --skip-delete-referrers default to false, which is the same behavior as the stable release oras 1.0.0.

opencontainers/distribution-spec#406 had a discussion about GC. It seems OCI Distribution-spec will not define GC policy and behavior for OCI registries in the short term.

I agree that removing unused referrers index goes beyond the common scope of registry clients, so we will change the default value to true in oras 2.0 release if needed.