well-known-uri-ref-engine-discovery.md

OCI Well-Known URI Ref-Engine Discovery

This is version 0.1 of this specification.

To faciliate communication between image publishers and consumers, this specification defines a ref-engine discovery protocol which publishers MAY use to direct consumers towards reference engines. Publishers who choose not to support this specification can safely ignore the remainder of this document.

Having retrieved a set of reference engines (via this and other protocols), consumers can use those ref engines to recover a set of Merkle roots potentially associated with a given image name. Consumers who choose not to support this specification can safely ignore the remainder of this document. Consumers who choose to support this specification MAY attempt to discover and use ref engines via other channels, and only fall back to this protocol if those ref engines do not return a satisfactory Merkle root.

oci-host-ref-engines well-known URI registration

This specification registers the oci-host-ref-engines well-known URI in the Well-Known URI Registery as defined by RFC 5785.

URI suffix: oci-host-ref-engines

Change controller: The Open Container Initiative

Specification document(s): This specification

Related information: None

Images associated with a host's oci-host-ref-engines

Publishers SHOULD populate the oci-host-ref-engines resource with ref engines which are capable of resolving image names that match the host-based-image-name rule with a host part that matching their fully qualified domain name and its subdomains or deeper descendants. For example, https://b.example.com/.well-known/oci-host-ref-engines SHOULD prefer ref engines capable of resolving image names with host parts matching b.example.com, a.b.example.com, etc. Some publishers MAY provide discovery services for generic image names (for example, to provide a company policy for ref-engine suggestions). Those publishers MAY provide those recommendations via a ref-engines resource at a URI of their choosing, but they SHOULD NOT serve the generic resource from oci-host-ref-engines to avoid distracting consumers following the protocol discussed in the following paragraph.

Consumers discovering ref engines for an image name that matches the host-based-image-name rule SHOULD request the oci-host-ref-engines resource from the host matching the host part. If retrieving that resource fails for any reason, consumers SHOULD walk the DNS ancestors of host. For example, if the host extracted from the image name is a.b.example.com and the well-known URI failed for a.b.example.com, the client would fall back to b.example.com and, if that too failed, to example.com.

Ref-engines media types

Servers supporting the oci-host-ref-engines URI MUST support requests for media type application/vnd.oci.ref-engines.v1+json. Servers MAY support other media types using HTTP content negotiation, as described in RFC 7231 section 3.4 (which is also supported over HTTP/2). For example, servers MAY support application/vnd.oci.regexp-ref-engines.v1+json to provide more targetted suggestions about specific subsets of image names.

Example 1

$ curl -H 'Accept: application/vnd.oci.ref-engines.v1+json' https://a.b.example.com/.well-known/oci-host-ref-engines
{
  "refEngines": [
    {
      "protocol": "oci-index-template-v1",
      "uri": "https://{host}/ref/{name}"
    },
    {
      "protocol": "docker",
      "uri": "https://index.docker.io/v2",
      "authUri": "https://auth.docker.io/token",
      "authService": "registry.docker.io",
    }
  ]
}

The oci-index-template-v1 protocol is registered. The docker protocol is currently unregistered, and is given as sketch of a possible extention protocol.

Example 2

$ curl -H 'Accept: application/vnd.oci.ref-engines.v1+json' https://example.com/.well-known/oci-host-ref-engines
{
  "refEngines": [
    {
      "protocol": "oci-index-template-v1",
      "uri": "https://{host}/ref/{name}"
    }
  ],
  "casEngines": [
    {
      "protocol": "oci-cas-template-v1",
      "uri": "https://a.example.com/cas/{algorithm}/{encoded:2}/{encoded}"
    }
  ]
}

The oci-index-template-v1 protocol is registered. The oci-cas-template-v1 protocol is registered.