add "feature flags", and API to expose

[vbatts]

Rather than incrementing the distribution spec version as certain optional features are added, this API and mapped values of "feature flags" will be used by registries to indicate whether new features are implemented. (Like PEP or similar extensions)

[mikebrow]

Rather... or as well as, we already have the v2 semantic as a legacy issue. What do you think about plain ole name value pairs as is done by feature gates in kube? https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/

[vbatts]

I'm thinking more simply like

GET /v2/features

Add get back a response like:

["OEP-1", "OEP-4"]

like "OCI Extension Proposals", where we have markdown docs describing the feature (similar to https://www.python.org/dev/peps/ or https://github.com/kubernetes/enhancements/tree/master/keps)

[mikebrow]

ok so no false positives... just a set of distribution extension proposals (DEPs) for the "certain optional" extension points.

[vbatts]

DEP is fine. Sounds like an abbreviation for "dependency" and I wondered if there would be a proposal that spans specs. But regardless.
Looking at xEP examples, the first proposal is setting up the proposal process itself. I'll take a stab at that

[mikebrow]

spec spanning ... never happen :) xEPs is fine pronunciation zeps or eh'ps?

[dmcgowan]

I like the extension proposal idea, I think that is a good way to separate the core of the spec from additional features in the future. As I have stated before, I think the specification needs to stay focused on the distribution of images (push and pull) rather than on registry operation. Just as we wouldn't expect the git protocol to continuously be added to with Github API features, we wouldn't expect this protocol to expand for all the needs of operating a registry. However, there are many different registry operators and agreeing on common APIs is good, I am fine with defining those here.

As for the /v2/features endpoint itself. We have discussed adding an endpoint like this for awhile but were never sure of what the scope of it might be. Simple is nice, but I might advocate for having a single endpoint which could fulfil requirements about getting the API version as well as more contextual metadata such as mirrors. So in that case, it might look like {"extensions":[]} rather than [].

Lastly, I think we need to consider that the extensions may need to define some configuration. Adding new endpoints via extensions may be easy, but that may end up putting a burden on the operators as well as the extension authors when it comes to defining the path. From an operational perspective, the service which implements the extension may be (and in some cases should be) different from the service handling the core specification API. For example today the authorization server and "distribution" server (such as a docker/distribution instance) would always run separately since they have different security profiles and scale requirements. An authorization server handles a smaller volume of requests and requires both a private key to sign tokens and user database access. While the "distribution" server only needs to be configured with storage backend access (which may be configured through something like IAM) and a public key for the authorization server. For a search extension, access to a completely different search backend would be necessary with a lower volume of requests. For pub sub, there was discussion about being able to send authorization keys, something a "distribution" server mentioned earlier should never have access to do. All that is to say that we should be flexible in how we let the registries configure their service extensions and not make an assumption they will be at the same URL prefix.

[vbatts]

I think the specification needs to stay focused on the distribution of images

Fair, I think these are strictly related. Also, the registry is a CAS storage, so when much of these mechanics are already here, it makes sense to leverage it.

as for the endpoint itself ...

good point!
Perhaps a structure more like:

{
  "extensions": {
    "OEP-1": {
      "version": "0.1",
      "url.base": "https://example.com/v1/"
    },
    "OEP-4": {
      "version": "0.1",
      "url.prefix": "/sig"
    } 
  }
}

which is easy enough to walk through the keys of the extensions, and then also have fields to give that kind of information.

[jzelinskie]

Let's not reinvent the wheel anywhere.
I think some applications reuse the RFC for .well-known to accomplish this.
If Kubernetes does something, copying that might work, too.

[dmcgowan]

The .well-known approach would cover a bit more than what is discussed here, primarily it was discussed as a way to "discover" registries and configurations across an entire domain. We still need something that could cover the capabilities of a single registry host. For example, /.well-known/ is always at the root path, but a registry may already be served as a sub path /v2/. We do need to solve that discovery from <domain> to <host>/v2 though. If we were to add features in a well known document, then we would always have to start at the <domain> (even if the client just has a host/mirror) and have that document synchronize with the capabilities of individual registry hosts. I still think we should keep the two separate, previously we suggested discovery for 1.1 but we wanted to figure out features before we finalize 1.0.

We still need to figure out the extension approach and formatting either way, but I am all for following a pattern that has proven successful in other projects. Any standard isn't going to help us with the formatting for defining the extensions though.