Discussion: Capabilities API

[SteveLasker]

As registries capabilities evolve, it will take time for all registries to enable the capabilities. Having a list of capabilities isn't limited to Notary or Artifacts. This issue tracks the design of an API for discovering the capabilities of a specific registry implementation, or even the capabilities of a specific repo within the registry. The response should provide the product/project/instance of the registry and a version, enabling an artifact client to cache the capabilities for subsequent interactions with the registry.

Existing Patterns

Discovering capabilities is a well-known pattern, such as smart device phones that implement capabilities based on the cost/model of the hardware or version of the software. Providing a list of capabilities enables applications to be written and released as one application (or client), that may check the capability of the device for what the application may provide. A device may have location services, wifi, bluetooth, a light, headset, nfc, multiple windows. The application checks the capability of the device, possibly prompting the user for authorization to use that capability, and proceeds based on that capabilities enablement or authorization of the user.

This same pattern can be used for registries. It's proposed to land this capability check with the artifact.manifest to set the stage for future capability checks.

Examples

1. What manifests are supported by the registry? (docker.manifest, docker index, oci manifest, oci index, artifact.manifest, ...)
2. _catalog api
3. Max size of each manifest type
4. Max size of layers
5. Max number of layers/blobs, possibly per manifest
6. Max size of annotations
7. Does the referrers/ API support filtering based on artifactType and/or annotations
8. Does the registry/repo support searching
9. Does the registry support eventing?
10. Does the registry/repo support metadata

Design Discussion

A name/value api can be provided, enabling a list of capabilities the registry can respond with, allowing registry clients with the ability for how they may proceed.

There should be a set of standard registry properties, simply defined in the root, with a set of registry specific capabilities defined with an annotation style prefix.

/oras/v1/capabilities?capabilityName
For example:
/oras/v1/capabilities?supportedManifests would respond with:

{
  "registry": "com.azure.registry",
  "version": "6.4.202107062010",
  "lastUpdate": "2021-08-10T20:18-06:00",
  "manifestSupport": {
    "application/vnd.docker.distribution.manifest.v1+json": {
      "maxLayerSize": "200000",
      "maxManifestSize": "4000"
    },
    "application/vnd.docker.distribution.manifest.v2+json": {
      "maxLayerSize": "200000",
      "maxManifestSize": "4000"
    },
    "application/vnd.docker.distribution.manifest.list.v2+json": {
      "maxLayerSize": "200000",
      "maxManifestSize": "4000"
    },
    "application/vnd.oci.image.manifest.v1+json": {
      "maxLayerSize": "200000",
      "maxManifestSize": "4000"
    },
    "application/vnd.oci.image.index.v1+json": {
      "maxLayerSize": "200000",
      "maxManifestSize": "4000"
    },
    "application/vnd.cncf.oras.artifact.manifest.v1": {
      "maxLayerSize": "200000",
      "maxManifestSize": "4000"
    }
  },
  "repositories":
    {
      "pathMaxLength": "256",
      "depth": 99999
    },
  "_catalog": "true",
  "com.azure.registry.quarantine": "enabled",
  "com.azure.registry.cmk": "enabled",
  "com.azure.registry.geo-replication.regions": [
    "eastus",
    "westus"
  ]
}

The capabilities MAY be implemented at the repository level: /oras/v1/{repository}/capabilities?capabilityName

Now or Later

For the immediate timeframe, the ORAS libraries will likely just query if the referrers/ API exists to proxy the support of the artifacts.manifest. If we can land a solid design of this API in the next several weeks, we can ship the ORAS libraries to be more robust.

Tagging OCI Distribution Spec extension proposal for possible alignment.

[sajayantony]

Currently looking at this this a thought experiment for now and don't feel there is a end-to-end use case that is specific to ORAS or the reference capabilities. I believe we should first work with the OCI distribution spec unless this is scoped to only ORAS endpoints.

[SteveLasker]

I agree it's non-blocking for now. And, I'd like to see it in distribution. For now, I was thinking we incubate here and propose back to distribution as we have some implementation. I think it will become more important as we start implementing the oras and nv2 libraries to identify if the registry supports a certain capability. Rather than have each feature have a unique trial/error, this is a bit more scalable, with a result that can be cached for subsequent calls.
That said, let's place this in the parking lot to reference as we continue to find capability check needs.

[michaelb990]

+1 @sajayantony -- I'd prefer keeping this issue out of the scope of the artifacts-spec work to ensure we stay focused on only what we need to enable references in a registry. From my POV, it should be easy to check whether or not a registry supports references -- just call the referrers API and see if you get a success or error response.

If this is something that people want to start working on now, I'd encourage it to be moved to the distribution-spec.