Tags are essentially undefined in the spec

[jonjohnsonjr]

The spec references "tags" quite a bit, but never defines them. I'm curious what everyone here (mostly registry operators) think a tag actually is.

My understanding of a tag is that it is effectively a git ref, i.e. it is a pointer to a manifest (or image index) digest that is namespaced to a repository.

I've been part of a conversation where users expected a repository to support having a tag for each platform so that they could push each platform's image individually and have the registry assemble a manifest list for them (cc @tianon please correct me if I'm wrong here).

Similarly, on this thread, some users expect the registry to support having a tag for each media type.

I wonder if it's worth clarifying somewhere (maybe not the spec, but just in this issue) so we can point to the answer of why we can't do this. It's clear that we can support pulling heterogeneous media types and platforms (that's the point of an image index), but we would require clients to assemble them rather than the registry (due to the trust model -- I expect the digest of what I pull to be what I pushed; you can't easily sign something the registry synthesizes).

cc @stevvooe @dmcgowan would love to hear your thoughts here.

PS: related, there is a TAG_INVALID error: During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned.. cc @atlaskerr related to #47 this is a schema-1-ism.

[mikebrow]

A tag name must be valid ASCII and may contain lowercase and uppercase letters, digits, underscores, periods and dashes. A tag name may not start with a period or a dash and may contain a maximum of 128 characters.

from: https://docs.docker.com/engine/reference/commandline/tag/

TagRegexp = match([\w][\w.-]{0,127})

[mikebrow]

What is a tag? it's a string that passes the above regexp.
If a tag name is not provided but is required "latest" may be used as the default.

[jonjohnsonjr]

So that's the format of the tag. Should we inline that into the spec? I see a regex for repositories but not tags.

I'm more interested in the semantics of a tag. It may be that we don't want to define how tags should work in order to grant registry operators flexibility in implementation, but right now it's apparently confusing for clients.

[mikebrow]

So that's the format of the tag. Should we inline that into the spec? I see a regex for repositories but not tags.

I think so.. let's see if anyone else chimes in.

Yeah there's a TODO for adding a primer, and I think this should be a part of that.

A repository, may have a number of images each image in the repository is referenced by one or more tag names. I think the difficulty is that the terms image and repository are often used interchangeably, and some tags appear to imply semantics, but really are just useful naming conventions which from the registry perspective are arbitrary naming conventions.

[bsatlas]

During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned.

Does this mean that the org.opencontainers.image.ref.name annotation in a manifest and the URI tag name have to match?

[jonjohnsonjr]

Does this mean that the org.opencontainers.image.ref.name annotation in a manifest and the URI tag name have to match?

I don't think so. This is a vestigial idea from schema 1, see here, where the repo and tag are embedded in the manifest.

Note the SHOULD only be considered valid when on descriptors on index.json within image layout., where this annotation should be on descriptors pointing to manifests and not on the manifests themselves (if I'm reading that correctly).

[bsatlas]

Ah that makes sense!

Anyways, I do think you bring up a good point that there isn't a lot of "advice" for how to implement distribution. Maybe we should think about making a separate concepts directory with misc guidance documentation.

[stevvooe]

A tag is a graph edge from a name to digest, possibly decorated with a type. It could be represented with a descriptor.

To be honest, I'd like to see a first class tag type based on descriptors:

{
  digest
  mediaType
  name // tag goes here
  ...
}

[SteveLasker]

Hi @jonjohnsonjr
As you saw in the discussion, I was hoping to have image:tag references be multi-dimensional. A tag could represent:

• an artifact by name
• a version of the artifact using :tag
• pivot on the artifact type (image, helm, msix, arm or cfn template, ...)

just like extensions on a file system allow a pivot of oci-spec.pptx, oci-spec.docx, oci-spec.ms
"Picking my battles", feeling the resistance, I've resorted to using namespaces:

• demo42.azurecr.io/samples/image/hello-world:1.0
• demo42.azurecr.io/samples/helm/hello-world:1.0
• demo42.azurecr.io/samples/cnab/hello-world:1.0
• demo42.azurecr.io/samples/arm/hello-world:1.0

At this point, an image:tag is:

• a pointer to a digest that can represent a specific artifact (image, helm, cnab, ...)
• versioned using the :tag

Just to tease this out a bit more:
One of the great debates has been what should be in a specific repo. What are the pivots of a repo?
Should a repo be one thing, only pivoted by version and os/platform?
This gets really sticky when grouping runtimes and SDKs.
If you look at the current jdk or dotnet repos, they contain the runtime, sdk and depdendencies that make one hell of a mess.
After loooooooooong debate on discoverablity, ease of use, and customer usability studies, we finally landed on product groupings. Working with the folks at Docker hub, we were able to present these as follows:

• https://hub.docker.com/_/microsoft-windows-base-os-images
  This is a product landing page, grouping all the Windows images.
  However, each repo is one thing. You'll notice:
• https://hub.docker.com/_/microsoft-windows-servercore docker pull mcr.microsoft.com/windows/servercore:1809
• https://hub.docker.com/_/microsoft-windows-nanoserver docker pull mcr.microsoft.com/windows/nanoserver:1809
• https://hub.docker.com/_/microsoft-windows-iotcore docker pull mcr.microsoft.com/windows/iotcore:1809

The dotnet repos will also transistion to this new model shortly.

The point i'm making is we've used a repo to represent a single thing, with multiple architectures and versions.
A collection of similar things are grouped in a namespace.
mcr.microsoft.com/[productFamily]/product:version

As with most things, guidance would have been helpful. We created the mess of multiple things in a repo, becuase we copied the existing mess. It was hard to justify doing something different, becuase the mess was the standard.

[jonjohnsonjr]

To be honest, I'd like to see a first class tag type based on descriptors

I was thinking of something like this:

GET https://index.docker.io/v2/library/ubuntu/tags/list

{
   "name": "library/ubuntu",
   "tags": [
      "latest"
   ],
   "manifests": [{
      "digest": "sha256:7a47ccc3bbe8a451b500d2b53104868b46d60ee8f5b35a24b41a86077c650210",       
      "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
      "size": 2035,
      "annotations": {
         "org.opencontainers.image.ref.name": "latest"
      }
   }]
}

But then read this:

SHOULD only be considered valid when on descriptors on index.json within image layout

😞

[jzelinskie]

There is interesting discussion here, but not really any call to action. A lot of the discussion is unrelated and could use its own issue.

Do we need to improve the wording around tags in the spec? If not, let's close this and continue discussions in new, focused issues.

[jonjohnsonjr]

We might just want to add some documentation about tags once opencontainers/.github#9 lands.

The spec only mentions tags in passing without any description or guidance. If that's an intentional choice to keep registries flexible, that's fine, but I wanted to point out there's a gap in the docs.

[vbatts]

@jonjohnsonjr will you try your hand at a PR for this?

[vbatts]

like jimmy said, good discussion, but if anything this is just teasing out particular clarity needed.
I'm closing this for now.