Skip to content

Latest commit

 

History

History
134 lines (101 loc) · 6.95 KB

ref-engine-discovery.md

File metadata and controls

134 lines (101 loc) · 6.95 KB

OCI 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.

Glossary

Ref-engine discovery

A service that suggests possible ref engines. This specification defines a ref-engine discovery protocol.

CAS engine

A service that provides access to content-addressable storage.

Merkle root

The root node in a Merkle tree. In the OCI ecosystem, Merkle links are made via descriptors. The Merkle root may be a descriptor (media type application/vnd.oci.descriptor.v1+json), or it may have a different media type. Merkle roots may suggest CAS engines, e.g. via a casEngines entry in their JSON, but that is out of scope for ref-engine discovery.

Ref engine

A service that maps an image name to a set of potential Merkle roots.

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-engine 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).

Ref-engines objects

This section defines the application/vnd.oci.ref-engines.v1+json media type. Content of this type MUST be a JSON object, as defined in RFC 7159 section 4. The object MAY include a refEngines entry. If set, the refEngines entry MUST be an array. Each entry in the refEngines array MUST be an objects with at least a protocol entry specifying the ref-engine protocol. Consumers SHOULD ignore entries which declare unsupported protocol values. The order of entries in the array is not significant.

The ref-engine discovery service MAY also include casEngines entry if it wants to supplement suggestions made by the ref engines. If set, the casEngines entry MUST be an array. Each entry in the casEngines array MUST be an objects with at least a protocol entry specifying the CAS-engine protocol. Consumers SHOULD ignore entries which declare unsupported protocol values. The order of entries in the array is not significant.

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.