Skip to content

Commit

Permalink
image-layout: add an initial image layout spec
Browse files Browse the repository at this point in the history
In order to build tooling that converts the set of OCI Image objects
into an OCI Runtime object we need an Image Layout that test tools can
be built around.

Longer term this Image Layout could be used to define a "single object
image" that is a tar/zip/etc that could be posted over https/ftp/etc.

The layout comes from several different discussions:

opencontainers#23
opencontainers#92

Signed-off-by: Brandon Philips <brandon.philips@coreos.com>
  • Loading branch information
Brandon Philips committed May 27, 2016
1 parent d0e591d commit 5616a30
Showing 1 changed file with 45 additions and 0 deletions.
45 changes: 45 additions & 0 deletions image-layout.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
## Open Container Initiative Image Layout Specification

The OCI Image Layout is a slash separated layout of OCI content-addressable
This layout MAY be used in a variety of different transport mechanisms from archive formats (e.g. tar, zip) or used in shared filesystem environments (e.g. nfs) or in networked file fetching systems (e.g. http, ftp, rsync).
Given an image layout a tool can convert a given ref into a runnable OCI Image Format by finding an appopriate manifest from the manifest list, unpacking the filesystem serializations in the correct order, and then converting the image configuration into an OCI Runtime config.json.

The image layout has two top level directories:

- "blobs" contains content-addressable blobs
- "refs" contains descriptors pointing to an image manifest list

This is an example image layout:

```
$ cd example.com/app/
$ find .
.
./blobs
./blobs/sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
./blobs/sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270
./blobs/sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f
./refs
./refs/v1.0
./refs/v1.1
```

The blobs directory MAY contain objects which are not referenced by any of the refs.
Each object in the refs subdirectory MUST be of type `application/vnd.oci.descriptor.v1+json`.
And the `mediatype` of this descriptor object SHOULD be `application/vnd.oci.image.manifest.list.v1+json` although future versions of the spec may use a different mediatype.

This illustrates the expected contents of a given ref and the manifest list it points to.

```
$ cat ./refs/v1.0
{"size": 4096, "digest": "sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51", "mediatype": "application/vnd.oci.image.manifest.list.v1+json"}
```
```
$ cat ./blobs/sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.list.v1+json",
"manifests": [
{
...
```

0 comments on commit 5616a30

Please sign in to comment.