extension proposal

[vbatts]

👯

The goal of this PR is to enable API extensions to the distribution-spec (registry API), so that implementations may experiment, and then once ironed out can propose the API paths be documented canonically here in the OCI distribution-spec.

There will be a place in this spec repo for official extensions to live once ratified. But importantly, it should provide a method for registry/client implementors to iterate on extensions before surfacing them to be solidified in the specification.

The challenges faced are:

• how to span registry-wide vs specific repo/app contexts
• honor ACL handling
• not pollute every existing endpoint

Fixes #74

Signed-off-by: Vincent Batts vbatts@hashbangbash.com

[vbatts]

@opencontainers/distribution-spec-maintainers PTAL
@josephschorr I would imagine the pub-sub to be under extensions here
@justincormack @jonjohnsonjr I would imagine a signature extension here, so that a signature payload on a digest could be pushed to a registry, then the signature extension allows discovering the digests of signatures associated

[mikebrow]

some comments

[mikebrow]

the /v2/ext/ string, in view of the distribution spec, suggests we are reserving ext as a logical registry name to be used for registry extension apis. We may need something like `/v3-ext/0' to make that happen?

[dmcgowan]

For registry level operations under /v2 in the past we prepended _. I think it is best to keep that convention here to not interfere with repository naming.

We could have a wider discussion on the role of /v2 and the potential to rev that or just make that not required. Personally I think the /v2 should remain an implementation detail and avoid having the version show up there in the spec. Like other things discussed, I think that belongs as part of the discovery design.

[mikebrow]

note: https://github.com/opencontainers/distribution-spec/blob/master/spec.md#api-version-check

Agree we need long term plan/path for versioning, both for distribution and it's extensions.

[mikebrow]

maybe reserve prepended _ for registry operations (legacy) and prepend _ext-[0-9]+ for extensions listed here such as _ext-0

edited to add... or whatever the regex ends up for naming be it numeric or alpha numeric.

[josephschorr]

I think we should try to limit the number of new top-level paths, as they can easily conflict with paths already exposed by registries. I'd prefer if we kept all extensions under the registry root path, whether that be /v2 or something else moving forward

[vbatts]

@dmcgowan are you saying you would prefer /v2/_ext/$name/...?
@josephschorr is ^ inline with what you're saying?

keep in mind that $name-extension would be something like "signatures" for notary-v2, or "events" for the pub-sub proposal.

[dmcgowan]

Yeah, /v2/_ext/... works. It's not pretty but we can't override the namespace there. I agree with @josephschorr on limiting the number of top level paths. Making them ugly helps I guess ;)

[sajayantony]

1. What would be the guidance be for extension authors to avoid naming collisions/squatting?
   Should we consider /v2/_ext/oci-artifacts or /v2/_ext/signatures or /v2/_ext/oci/signatures/v1/.

2. Also would providing guidance around /v2/_ext itself. Is there an expectation of returning a list of supported extensions or are the names something that is discovered out of band and we just 404 on /v2/_ext/oci/signatures

[josephschorr]

@vbatts Do you have any thoughts on having an API-driven discovery mechanism for back-compatibility between versions of extensions, or do you fully intend all new versions of extensions to be completely independent?

[vbatts]

is this to say, clients could stay using the older version of an extension?
If so, no. That is up to the registry maintainer. I think the $name of any given extension ought to link to the its markdown doc describing it. If it changes, then the $name and doc should change. The registry owner can choose the lifecycle they support here.

[josephschorr]

Hmm... I have concerns we'll run into the same problems that we're running into with /v2 in regards to back and forward compatibility. At minimum, I think we should have extensions have a defined way of publishing support for specific things or versions

[SteveLasker]

would /v2/_ext/oci-artifacts/v1/{namespace}/repo/manifests/{digest}/links?n=10 be inline with what we're discussing here?

• oci-artifacts would have a links extension.
• it would have a version v1
• it would follow the namespace/repo path consistency, but be rooted in a named extension /oci-artifacts

[vbatts]

from a discussion that @dmcgowan and I had today.

While I thought that all the endpoints of any given extension would be sandboxed in its prefix, Derek points out how that could make the ACLs a bit too tricky, without wholly expecting an extension to copy API patterns.

So we walked through both.
We used the notary v2 use-case as our first concrete example.

Notes below (copied from https://hackmd.io/Ljkrt0LORmeVznREeGOWuQ):

GET /v2/_ext/

{
  "0" : {},
  "sigs": {"doc":"http://github.com/opencontainers/distribution-spec/trees/master/ext/ext-sigs.md"}
}

/v2/_ext/sigs/   (reserved for sigs extension)

GET /v2/_ext/sigs/<hash>/<digest>/<name>
POST /v2/_ext/sigs/<hash>/<digest>/<name>
DELETE /v2/_ext/sigs/<hash>/<digest>/<id>

GET /v2/<repo name>/sigs/<hash>/<digest>
POST /v2/<repo name>/sigs/<hash>/<digest>
PUT /v2/<repo name>/sigs/<hash>/<digest>/<hash>/<digest>
DELETE /v2/<repo name>/sigs/<hash>/<digest>/<hash>/<digest>
                            |<--signed---->|<--signature-->|       

{
  "0": {
    "mediaType":"...signature...blob",
    "size": 100,
    "digest": "sha256:deadbeef"
  }
}

What ever mediaType of the signature object itself should be parseable to reference the digest of the blob that it is a signature for. (for garbage collection)

[josephschorr]

@vbatts The concern I have there is overlap: if I currently have a registry that supports multiple levels of nesting, and I have a repository named mynamespace/arepo/sigs (for whatever reason), now I have a conflict on the paths. Does that means I get the repository responses back, or do I get the sigs for mynamespace/arepo (it might exist on its own, afterall). A similar problem does exist today, but its currently limited in the API, where moving forward this wouldn't be the case.

Perhaps all extensions under the existing API should be prefixed with a character not supported by the current repo names? Like... GET /v2/<repo name>/_/sigs/<hash>/<digest>?

[dmcgowan]

@josephschorr when the API was originally being designed a similar issue also came up with tags, hence the odd tags/list endpoint for listing tags. It may have been a limitation of the handlers we were using at the time, but there was always two parts matched at the end to get around the ambiguity (@stevvooe for more context). I kind of like the idea of differentiating with a "_", maybe "_sigs" is enough. As long as we apply the rule consistently for new endpoints.

[jzelinskie]

Why not just adopt something like the .well_known and let the servers define their own URL prefixes and try and stay as much out of their way as possible? Imposing versioning and all of this other stuff in the URL seems pretty non-ideal.

[josephschorr]

@jzelinskie I'm highly concerned about overlap: its guaranteed that registries, today, have /v2/... reserved for registry use. If we allow extensions to place themselves wherever they please at the top level, we will likely quickly run into conflicts with existing per-implementation endpoints. .well-known is a good idea, but it should ideally be discoverable as part of the existing OCI endpoints.

[samuelkarp]

For new extensions that are being proposed, but have not yet been accepted into the spec, do we want to set a standard for naming that distinguishes a proposed-extension from a standard-extension? I'm thinking along the lines of vendor prefixes for CSS; this could allow a registry operator to experiment and provide an endpoint for a feature where there isn't yet consensus in the community.

[sequix]

What will this extension covers? Everything in the brainstorm?

[vbatts]

scope of the extensions:

 extensions are meant as a way to extend on the generic basic workflows available in the distribution-spec

A way to have a handshake between client-server for additional features capable. e.g. search, signatures, discoverability. etc

The hope of having a server expose which features it implements vs. a newer version (i.e. /v2/) that implements new features, in synchrony.
It's okay to add a batch of OPTIONAL features to the spec, with language around "if you use this OPTIONAL http endpoint then you MUST use the corresponding ones".

I'm really wondering whether this is even the correct approach.

If these features are the right and good for distribution-spec (the API), then just put them in the spec and rev the version.

(Having a call with @dmcgowan @jzelinskie @mikebrow @jdolitsky @vbatts)

[vbatts]

This basically needs community discussion around "how can i experiment with bringing in new features, or have my own bespoke feature"

[SteveLasker]

What was the consensus here?
At the root:
/v2/_ext/oci-artifacts/v1/{namespace}/repo/manifests/{digest}/links
or, at the repo
/v2/{namespace}/repo/manifests/{digest}/_ext/oci-artifacts/v1/links

Basically, should _ext/ be a reserved extension anywhere in the uri?

[SteveLasker]

@vbatts, @dmcgowan, @justincormack, in today's OCI weekly call, we discussed moving forward with #111 where we document v2/_ext/ as a reserved namespace for extensions. The question was then: should we use numbered items, and let people fight for reserving a number while they develop and hopefully ship their extension. Or, named elements that have no order. Just uniqueness.

[vbatts]

now that 1.0 is tagged, and a number of conversations that touched on this proposal have progressed, I intend to dust this off and find the path forward.

[SteveLasker]

Thanks @vbatts, here's a prototypical example for the reference types: opencontainers/artifacts#29
A direct link to the referrers API

[rchincha]

... or as part of repository names.

[vbatts]

oh for sure. In the updated push I include some string formatting regular expression. With the _ prefix on the extension name, that differentiates all extensions, from any <name> of a manifest reference.

[vbatts]

updated PTAL

[sudo-bmitch]

Are "endpoints" a reference to "components"?

[vbatts]

ah ok. we need examples

[sudo-bmitch]

For anyone that wasn't on the call today, endpoints refers to _<extension>/<component>/<module>. Not sure if we want to include /v2/ and /v2/<repository> in there.

[vbatts]

@opencontainers/distribution-spec-maintainers PTAL

[mikebrow]

LGTM for initial push

[vbatts]

👏