Initial import of specs #6

vbatts · 2016-04-04T20:32:23Z

Per the proposal for this image-spec group, this is bringing in the base for the distributable image format from https://github.com/docker/distribution/blob/bf9f80eaffb0eabc768762bc4ff03ded277ea594/docs/spec/manifest-v2-2.md and https://github.com/docker/docker/blob/99a396902f0ea9d81ef87a683489b2435408f415/image/spec/v1.md

jonboulle · 2016-04-04T20:35:05Z

serialization.md

@@ -0,0 +1,573 @@
+# Docker Image Specification v1.0.0


jonboulle · 2016-04-04T20:41:22Z

actually before going any further, some big open questions:

What are the compatibility requirements (if any?) with the existing Docker V2 format - are we considering this a fork?
What need is there to preserve language referencing other Docker specifications/technologies, as it does today?

vbatts · 2016-04-04T20:55:47Z

@jonboulle good question. That topic did not come up during the TOB discussions. In some ways this would be considered a fork, though by defining itself a mediatype, then IIRC it could be sourced by a docker v2.s2 manifest and still have predictable processing of the document.

philips · 2016-04-05T16:47:06Z

manifest.md

+}
+```
+
+# Backward compatibility


probably makes sense to drop this section?

Does this mean we intend to drop compatibility?

philips · 2016-04-05T17:01:14Z

@vbatts I closed and reopened this to trigger Travis CI. Seems to work.

vbatts · 2016-04-05T17:04:09Z

cool. I initially did not sign the WIP commit for this reason! :-)

brendandburns · 2016-04-05T21:50:14Z

manifest.md

+Its use is optional, and relatively few images will use one of these manifests.
+A client will distinguish a manifest list from an image manifest based on the Content-Type returned in the HTTP response.
+
+## *Manifest List* Field Descriptions


Why italics for Manifest List? (I might expect code font)

much of this is just carry over styling that has yet to be visited.

philips · 2016-04-06T20:22:07Z

@stevvooe Probably a good idea for vbatts to rebase on top of a clean doc. Sorry vbatts.

stevvooe · 2016-04-06T20:42:43Z

manifest.md

+
+The following media types are used by the manifest formats described here, and the resources they reference:
+
+- `application/vnd.oci.image.manifest.v1+json`: Image manifest format


If we are starting a fork, should there not be a base commit before changing mediatypes? Do we intend to do a full compatibility break with Docker V2.2?

It might be appropriate to declare a mapping of equivalent mediatypes from OCI. For example V2.2 becomes, V1 of OCi and it is compatible with application/vnd.docker....

I did commit the two as separate commits first before starting the WIP commit. 70c1c83 and fd4580c

I'm not sure I follow the compatible thought. Could explain that further?

stevvooe · 2016-04-06T21:42:35Z

@philips @vbatts @duglin @jonboulle I agree with much of the sentiment in the review of this specification, but the V2.2 manifest schema is already quite flexible for the purposes of describing a configuration target and set of image layers. It was designed to be quite generic and went through almost a year of revisions before being merged. Arguably, the flexibility of the format has not yet been fully realized.

While I understand that compatibility may not be the primary goal, let's make sure breaks are based on technical merit. Let's consider defining a baseline that is at least structurally compatible. This would mean we maintain all the fields, as they are. Additions, such as ociVersion can be added without breaking the format. We can maintain a registry of backwards compatible media types to the docker equivalent.

Does this seem reasonable?

from https://github.com/docker/docker/blob/99a396902f0ea9d81ef87a683489b2435408f415/image/spec/v1.md Signed-off-by: Vincent Batts <[email protected]>

from https://github.com/docker/distribution/blob/bf9f80eaffb0eabc768762bc4ff03ded277ea594/docs/spec/manifest-v2-2.md Signed-off-by: Vincent Batts <[email protected]>

vbatts · 2016-04-07T13:49:38Z

@stevvooe understandable that fields can be added without breaking, but regardless I think this would be a new mediatype and binding ourselves to not breaking the docker v2.s2 format could limit conversation. By having a departure into its own mediatype, it allows to build on the year of iteration and not limit ourselves.

Also, having the "untouched" commits, they are here c22ca79 and c1ff36f

Some points, even like the ".wh." diff type rootfs is something that will be revisited.

philips · 2016-04-07T13:52:47Z

@vbatts +1 on a new media type.

If at all possible I would like to keep the image layers bit-for-bit compatible for the initial v1 release to make it possible for people to use existing s3 objects for layers.

vbatts · 2016-04-07T14:03:02Z

@philips bit-for-bit compatible [with the docker v2.s2] for the initial v1 release [of the oci image spec] ?

philips · 2016-04-07T14:09:27Z

@vbatts It would be ideal if the serialization format for the layer was bit-for-bit compatible for the sanity of the container registries like gcr.io, quay, hub, etc so they don't need to duplicate 98% of the data to change some JSON inside a tarball. If necessary we can make changes to the manifest.

philips · 2016-04-07T16:39:34Z

LGTM for now. This discussion has gotten too splintered to be useful.

vbatts · 2016-04-07T16:46:30Z

hold on. I'm trying to get the simple line cleanups done. Then I'll take
the WIP off.

On Thu, Apr 7, 2016 at 12:39 PM, Brandon Philips [email protected]
wrote:

LGTM for now. This discussion has gotten too splintered to be useful.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#6 (comment)

vbatts · 2016-04-07T18:32:03Z

All. I've rebased this PR to be only the initial import of the the specs cited, and opened #12 for the adjustments.

philips · 2016-04-07T19:19:16Z

LGTM!

stevvooe · 2016-04-07T19:45:26Z

@vbatts Reading back, I wasn't very clear above. I agree that we should have new mediatypes. The spec would have a table declaring which mediatypes are compatible with the docker mediatypes.

I don't want to limit the conversation but let's make sure that if a break is done, there is a very good technical reason for doing so.

LGTM

philips · 2016-04-08T00:45:05Z

I am going to click the button tomorrow morning unless anyone has objections.

These quasi-entities (which are missing the usual closing semicolon) have been floating around since c22ca79 (serialization: docker v1 image format media type, 2016-04-04, opencontainers#6). Generated with: $ sed -i 's/&lt/</;s/&gt/>/' $(git grep -l [email protected]) Signed-off-by: W. Trevor King <[email protected]>

Covering all cases turned up by: $ git grep '\*array' runtime-spec does this pretty consistently, and the first such usage appeared in image-spec with f3d0f78 (config: reformat and add optional/required, 2016-09-20, opencontainers#333). And before that, c22ca79 (serialization: docker v1 image format media type, 2016-04-04, opencontainers#6) had landed some: <code>array of strings</code> Signed-off-by: W. Trevor King <[email protected]>

Add artifactType

jonboulle reviewed Apr 4, 2016
View reviewed changes

serialization.md

@@ -0,0 +1,573 @@

# Docker Image Specification v1.0.0

Copy link

Contributor

jonboulle Apr 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

update

vbatts force-pushed the import_docker_formats branch 2 times, most recently from 4a582d8 to bf5c3f6 Compare April 4, 2016 20:52

philips reviewed Apr 5, 2016
View reviewed changes

philips closed this Apr 5, 2016

philips reopened this Apr 5, 2016

brendandburns reviewed Apr 5, 2016
View reviewed changes

stevvooe reviewed Apr 6, 2016
View reviewed changes

vbatts added 2 commits April 7, 2016 09:35

serialization: docker v1 image format media type

c22ca79

from https://github.com/docker/docker/blob/99a396902f0ea9d81ef87a683489b2435408f415/image/spec/v1.md Signed-off-by: Vincent Batts <[email protected]>

manifest: docker v2.s2 as the manifest

c1ff36f

from https://github.com/docker/distribution/blob/bf9f80eaffb0eabc768762bc4ff03ded277ea594/docs/spec/manifest-v2-2.md Signed-off-by: Vincent Batts <[email protected]>

vbatts force-pushed the import_docker_formats branch 2 times, most recently from 68a5d22 to 155b8ac Compare April 7, 2016 13:44

vbatts force-pushed the import_docker_formats branch from 155b8ac to a7abc10 Compare April 7, 2016 15:27

vbatts force-pushed the import_docker_formats branch 2 times, most recently from bb25b9c to c1ff36f Compare April 7, 2016 18:28

vbatts mentioned this pull request Apr 7, 2016

Begin adjustments on the imported specs #12

Merged

vbatts changed the title ~~[WIP] Import docker formats~~ Initial import of specs Apr 7, 2016

philips merged commit 6a4fccc into opencontainers:master Apr 8, 2016

wking mentioned this pull request Apr 22, 2016

Detail compatibility requirements of v1.0 #42

Closed

vbatts deleted the import_docker_formats branch April 27, 2016 19:23

wking mentioned this pull request Jun 16, 2016

*: Fix '&lt' -> '<' and '&gt' -> '>' typos #146

Merged

wking mentioned this pull request Nov 5, 2016

*: Replace '*array*' with '*array of {type}*' #447

Merged

sajayantony added a commit to sajayantony/image-spec that referenced this pull request Aug 8, 2022

Merge pull request opencontainers#6 from sajayantony/oci-playground

e5d2973

Add artifactType


		The following media types are used by the manifest formats described here, and the resources they reference:

		- `application/vnd.oci.image.manifest.v1+json`: Image manifest format

Initial import of specs #6

Initial import of specs #6

Uh oh!

Conversation

vbatts commented Apr 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonboulle commented Apr 4, 2016

Uh oh!

vbatts commented Apr 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

philips commented Apr 5, 2016

Uh oh!

vbatts commented Apr 5, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

philips commented Apr 6, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevvooe commented Apr 6, 2016

Uh oh!

vbatts commented Apr 7, 2016

Uh oh!

philips commented Apr 7, 2016

Uh oh!

vbatts commented Apr 7, 2016

Uh oh!

philips commented Apr 7, 2016

Uh oh!

philips commented Apr 7, 2016

Uh oh!

vbatts commented Apr 7, 2016

Uh oh!

vbatts commented Apr 7, 2016

Uh oh!

philips commented Apr 7, 2016

Uh oh!

stevvooe commented Apr 7, 2016

Uh oh!

philips commented Apr 8, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants