Clarification in spec needed: Deletion by tag vs. deleting tags. about distribution-spec

[tianon]

I'm not a distribution spec maintainer, but for what it's worth, "b" is the behavior of the original/reference implementation (which IMO is the behavior most supported by the existing spec wording as well).

[sudo-bmitch]

a) Deleting by tag deletes the underlying manifest and might thus also delete other tags referencing the same manifest.

I hope there aren't any registries out there that delete other tags.

b) Deleting a tag deletes the tag itself, not the underlying manifest. Note that implementations might garbage-collect manifestes without any tags.

This is close to my understanding of most registries. But saying "not the underlying manifest" implies that all registries would preserve the manifest, and I would not be surprised if some exist that immediately delete manifests as soon as the last tag is removed. That wouldn't be a full GC (you still need grace time to push a multi-platform collection of manifests), but a simple ref-count that destroys content as soon as the count goes from 1 to 0.

c) Whether deleting by tag also deletes the underlying manifest is up to the implementation.

It would be unexpected to me if an implementation destroyed the underlying manifest while other tags still reference it.

GC and content retention policies continue to be an implementation detail. Some registries retain content indefinitely, others are designed to be ephemeral destroying even tagged content after a short time, and organizations impose legal requirements on this to either preserve or ensure content is destroyed according to their company policies.

Looking over the spec, I think the clarification should be "what is a tag". We currently have the definition:

Tag: a custom, human-readable manifest identifier

I think it would be helpful to clarify that a tag is a pointer to a manifest and a manifest is stored by digest. Then the tag delete API would indicate that it is explicitly deleting the tag. While the manifest delete API is deleting both the manifest and any tags pointing to that manifest.

This intentionally avoids the question of whether implementations may or should delete the underlying manifest because I think it depends on both the scenario (particularly whether there other tags pointing to the manifest) and the implementation.

[NiklasBeierl]

@sudo-bmitch

Looking over the spec, I think the clarification should be "what is a tag". We currently have the definition:

Tag: a custom, human-readable manifest identifier

Hmm, I think that this is good enough for a definition. The clarification is really needed in the Deleting tags section. What contributes to the ambiguity is that the same endpoint used for deleting manifests and tags:

DELETE /v2/<name>/manifests/<tag>      # The action in question
DELETE /v2/<name>/manifests/<digest>  # Deletes an actual manifest
                      ⬆️
             Both say "manifests"

[sudo-bmitch]

The clarification is really needed in the Deleting tags section.

My suggestion included a recommended change to that section.