Outline the transportable objects

[vbatts]

From a single tar archive of tar archives and JSON documents, or a manifest JSON document that points to other objects needing to be fetched.

UserStory:

• As an opensource project, I want to produce an OCI image for the world to consume.

See also https://groups.google.com/a/opencontainers.org/d/msg/dev/VKpZNs-qYoI/RzPhj71ODgAJ

[jonboulle]

Is this essentially the enhancement/replacement of serialization.md?

[vbatts]

@jonboulle sorry, this was more of placeholder thought. The serialization doc does have tar archive info. Though I was thinking more of the manifest. This may be a non-topic, if the culmination of referenced layers in a manifest are handled independently, but the docs need to be cleaned up to show the transportable states of the image.

[vbatts]

Updated the title and comment. Hopefully that helps a bit more.

[vbatts]

Once you've gotten all the objects on disk specified in a manifest, there will be a validation and translation to the runtime-spec bundle, or similar. This needs to be outlined as well.

[philips]

I think there are two things here.

Spec out a directory layout for manifests and blobs that mirrors how the image manifests work. My suggestion is that the manifest is the primary object in the system so the other "things" are adjacent.

$ cd my-oci-image/
$ find .
.
./blobs
./blobs/sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270
./blobs/sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f
./manifests
./manifests/v1.0
./manifests/v1.0-debug

Build a tool that consumes this directory and creates a runnable OCI bundle.

ocitool runtime-bundle file:///path/to/my-oci-image/manifests/v1.0

[wking]

On Wed, Apr 20, 2016 at 03:20:44PM -0700, Brandon Philips wrote:

$ find .
.
./blobs
./blobs/sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270
./blobs/sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f
./manifests
./manifests/v1.0
./manifests/v1.0-debug

I'd expect the format should also include signatures and the name ↔
format://manifest-hash being asserted by those signatures, because the
“I just want to attach one thing” workflow 1 shouldn't require
additional network activity to collect those names and signatures.

And the single-archive-tar use-case needs a HEAD reference or some
such to pick the default manifest.

So how about:

./VERSION
./HEAD
./objects/sha256/5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270
./objects/sha256/e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f
./objects/sha256/ca6e91e8f982603d5ee741db911fdd8814185f4da52df3dba9e90cf67aed9c9a
./objects/sha256/fada3467c61b55140ce331f4f515fe61d1d1b99951893aee822c7c3c394061f6
./objects/sha256/07dec7175b024a30f22b1be7853480472b9b406afc593568b6f19dd7bf08f507
./objects/sha256/19f58930b0fffd0dd3e4ed7a4a4059f45fed9a759f69f8544a45ac0dfd954b36
./objects/sha256/6ce50f12c5a18c8c755d05c9f760ae0d0f71f60885b8937b94a1da52fc9b2898
./objects/sha256/d1ee7338f8ebdcaf78acbd63e640cfd9e1a45a29d23c63656d3158c350c3325d
./manifests/v8.0
./manifests/v8.0-debug

where:

• VERSION contains ‘application/vnd.oci.image.v1.0’ or some such.

• sha256:5b0b… and sha256:e692… are layer tarballs (or some other
  resource referenced from the manifest).

• sha256:ca6e… and sha256:fada… are manifests.

• sha256:07d3… and sha256:19f5… are JSON like TUF's METAFILES 2,
  with an external METAPATH moving to an internal ‘name’:

  {
  "name": "debian 8.0",
  "hashes" : {
  "sha256": "ca6e91e8f982603d5ee741db911fdd8814185f4da52df3dba9e90cf67aed9c9a",
  "sha512": "2c9af2165c9555329e07a3d88d366f7e58767a9067d206022de107ff91426248bf6404aead451c9106df809289c46ea55d2250600c004a4f4dbf97d7648f8fa2",
  "ipfs": "QmVc6zuAneKJzicnJpfrqCH9gSy6bz54JhcypfJYhGUFQu",
  …
  ],
  "custom": …,
  }

  to associate a name and/or custom metadata with a given manifest (in
  its various hashes).

• sha256:6ce5… and sha256:d1ee… are detached signatures for the
  metafile blobs.

• The optional manifests/* contain payloads like:

  {
  "signed": "sha256/07dec7175b024a30f22b1be7853480472b9b406afc593568b6f19dd7bf08f507",
  "signatures": [
  "sha256/6ce50f12c5a18c8c755d05c9f760ae0d0f71f60885b8937b94a1da52fc9b2898",
  "sha256/d1ee7338f8ebdcaf78acbd63e640cfd9e1a45a29d23c63656d3158c350c3325d"
  ]
  }

• The optional HEAD contains ‘manifests/v8.0’ or some other path to
  the default metafile.

And folks who wanted could hit a signature registry to check for
additional signatures (or revocations) for sha256/07de… etc.

Taking this to its logical conclusion, you might also want to also
include blobs for and references to public keys 3, signing
algorithms 4, validity schemes 5, etc. It just depends on how
much of the verification workflow you want to be able to preform based
on the file contents vs. alternative communication channels and how
much you like linked data ;).

[philips]

VERSION doesn't seem necessary. The manifests describe themselves.