rkt Design Proposals

Distribution points

A distribution point represents a method for fetching a container image from an input string. This string does not specify an image's type.

A distribution point can provide one or more image formats. Some Docker registries also provide OCI Images. Rkt can fetch a Docker/OCI image from a registry and convert it on the fly to its native image format, ACI. The docker2aci tool can perform this conversion in advance.

Before distribution points, rkt used ImageTypes. These mapped a specifically formatted input string to things like the distribution, transport and image type. This information is hidden now since all images are appc ACIs.

Distribution points are used as the primary expression of container image information in the different layers of rkt. This includes fetching and referencing in a CAS/ref store.

Distribution points types

Distribution points are either direct or indirect. Direct distribution points provide the final information needed to fetch the image. Indirect distribution points take some indirect steps, like discovery, before getting the final image location. An indirect distribution point may resolve to a direct distribution point.

Distribution points format

A distribution point is represented as a URI with the URI scheme as "cimd" and the remaining parts (URI opaque data and query/fragments parts) as the distribution point data. See rfc3986 for more information on this. Distribution points clearly map to a resource name, otherwise they will not fit inside a resource locator (URL). We will then use the term URIs instead of URNs because it's the suggested name from the rfc (and URNs are defined, by rfc2141, to have the urn scheme).

Every distribution starts the same: cimd:DISTTYPE:v=uint32(VERSION): where

Since the OCI image layout can provide multiple images selectable by a ref, one needs to specify which ref to use in the archive distribution URI (see the above ref query parameter). Since distribution only covers one image, it is not possible to import all refs with a single distribution URI.

TODO(sgotti): Define if oci-image-layout. It should internally handle both archive and directory based layouts or use two different distributions or a query parameter the explicitly define the layout (to avoid guessing if the URL points to a single file or to a directory).*

Note Considering this OCI image spec README section, the final distribution format will probably be similar to the Appc distribution. There is a need to distinguish their User Friendly string (prepending an appc: or oci: ?).

User-friendly distribution strings

The distribution URI can be long and complex. It is helpful to have a friendly string for users to request an image with. Rkt supports a couple of image string input styles. These are mapped to an AppImageType: