Registry metadata endpoint at root

[dmcgowan]

In order to aid in client development supporting both v1 and v2 registries, specify a metadata endpoint which provides information related to the capabilities of the registry, which versions are supported, and what the mirror options are. The metadata endpoint would live at the root registry URL and return a JSON configuration value. For example an image with the name "registry.example.com/myimage" would have a metadata endpoint at https://registry.example.com/ and could have a v2 supported registry at https://registry.example.com/v2/.

The JSON value will contain a section for each version of the registry which is supported. The values for each version is defined by the version since many of the keys do not apply to each version. If the metadata endpoint cannot be loaded, then the client should assume a default configuration which is v1 only, no mirrors, and the index is at the endpoint + "/v1/".

JSON value

{
   "endpoints": {
      "v2": {
         "version": "2"                   // Version of registry
         "root": "https://endpoint/v2/",  // V2 root endpoint (default: /v2/)
         "push": true,                    // Whether push is supported or pull-only
         "fallback": "v1",                // Where to fallback on manifest 404 (default: no fallback)
         "mirrors": [                     // Pull mirrors
            {
               "root": "https://mirror/v2/", // Mirror endpoint
               "manifests": true             // Whether mirror contains manifests
            },
         ],
      },
      "v1": {
         "version": "1",                      // Version of registry
         "index": "http://indexendpoint/v1/", // V1 index endpoint (default: /v1/)
         "push": true,                        // Whether push is support or pull-only
         "mirrors": [                         // Layer mirrors (index mirroring not supported)
            {
               "root": "https://mirror/v1/"
            }
         ]                        
      }
   }
}

edit 1: Updated JSON format to add top level key for endpoints, mirrors as array of objects, fallback a pointer instead of a boolean, and version number

[dmcgowan]

Could also add a flag for v1 whether to support push, would be the case where v1 images are still needed to be pulled, but new images should only be pushed to v2.

[stevvooe]

I like this. Let me get out my bikeshed:

JSON value

{
    "Endpoints": [{
        "Version": "v2",
        "Root": "https://endpoint/v2/",  // V2 root endpoint (default: /v2/)
        "Fallback": // .. We may want a more flexible value that bool, maybe "v1" or
        "Mirrors": [
            {
                "Version": "v2",
                "Root": "https://mirror/v2/", ..., // Pull mirrors
                ...
            },...
         ],
    },
    {
        "Version": "v1",
        "Index": "https://indexendpoint/v1/",  // V1 index endpoint (default: /v1/)
        "Mirrors": [],
    },
}

Some ideas:

• The list of endpoints could be an ordered list of fallback points
• They could have references to other list items to specify direct fallback, mirrors, etc.

[stevvooe]

LGTM!

[dmcgowan]

Superseded by #179