Tags are essentially undefined in the spec about distribution-spec HOT 14 CLOSED

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

from distribution-spec.

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

from distribution-spec.

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})

from distribution-spec.

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.

from distribution-spec.

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.

from distribution-spec.

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.

from distribution-spec.

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?

from distribution-spec.

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).

from distribution-spec.

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.

from distribution-spec.

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
  ...
}

from distribution-spec.

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.

from distribution-spec.

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

😞

from distribution-spec.

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.

from distribution-spec.

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.

from distribution-spec.