Adds Docker Image v1 Spec Documention #9560

Merged
merged 1 commit into from Jan 12, 2015

Projects

None yet
@jlhawn
Contributor
jlhawn commented Dec 8, 2014

Docker-DCO-1.1-Signed-off-by: Josh Hawn josh.hawn@docker.com (github: jlhawn)

@jlhawn
Contributor
jlhawn commented Dec 8, 2014

From issue #9538:

If you were to complain that Docker's image format and runtime specification, as massively adopted as it is, is not appropriately documented, and it could be made easier to produce alternate implementations - then I would completely agree with you. In response, I would encourage the project maintainers to improve the specs documentation based on your suggestions.

Well, here it is 🐋

@SvenDowideit @fredlf Please review and give feedback.

@jessfraz
Contributor
jessfraz commented Dec 8, 2014

😍

@jlhawn
Contributor
jlhawn commented Dec 8, 2014

also @vbatts @dmp42 @crosbymichael @tianon @jfrazelle @unclejack @docker/distribution-trust @nathanleclaire @cpuguy83 @huslage and anyone else in the community that comes across this - please read through it and comment on anything that isn't clear or anything that requires more explanation, keeping in mind that this is not a new specification but is only documentation of how images are currently create/formatted in Docker.

I was thinking we could also generate a list of 'issues' with this specification to include in the bottom - something that could help us drive design of the next major version of the specification. Here are a few things I can think of for example:

- image IDs are an implementation detail of storage drivers in Docker and shouldn't be part of the specification.
- there is extraneous or useless info in some of the fields:
    - container id?
    - config *and* containerConfig? containerConfig seems to be only useful for the build system and nothing else.
- why is OnBuild in the runConfig and not top-level in the image JSON?
- is every field of the `runconfig.Config` struct necessary or useful?
- etc...
@jlhawn
Contributor
jlhawn commented Dec 8, 2014

also @metalivedev ;-)

@icecrime icecrime and 1 other commented on an outdated diff Dec 8, 2014
image/spec/v1.md
+ ISO-8601 formatted combined date and time at which the image was created.
+ </dd>
+ <dt>
+ container <code>string</code>
+ </dt>
+ <dd>
+ The identifier of the container which was used to create the image.
+ </dd>
+ <dt>
+ config <code>struct</code>
+ </dt>
+ <dd>
+
+ The execution parameters which should be used as a base when running a container using the image.
+
+ <h4>Container RunConfig Field Descriptions</h4>
@icecrime
icecrime Dec 8, 2014 Member

This container config has been a strong point of confusion for me and several others. As far as I can tell:

  • This provide defaults values for settings if not specified at run time (e.g: CpuShares)
  • Some of these settings are completely ignored (e.g.: Tty, Attach*, ...)
  • As far as I understand, this whole idea of "default container config" is out of v2 image format so although this is a purely v1 documentation, don't you think it might be relevant to add a "deprecation warning"?
@jlhawn
jlhawn Dec 8, 2014 Contributor

good points @icecrime

I mentioned above:

  • is every field of the runconfig.Config struct necessary or useful?

I can update this document to clarify this - only I'm not entirely sure which fields are ignored. I guess I can dig up the code to find out exactly what's going on: https://github.com/docker/docker/blob/58ce0146e16e2e63b7a94d34a48722a9c7400c18/daemon/daemon.go#L418

Do you happen to know which fields are used? @erikh I think you have some expertise with runconfig, could you shed any light on this?

@icecrime
icecrime Dec 9, 2014 Member

I think it's all in runconfig.Merge. Fields used:

  • Cmd
  • CpuShares
  • Entrypoint
  • Env
  • ExposedPorts (and its legacy counterpart PortSpecs)
  • Memory
  • MemorySwap
  • User
  • Volumes
  • WorkingDir
@metalivedev metalivedev commented on an outdated diff Dec 9, 2014
image/spec/v1.md
+```
+
+### Image JSON Field Descriptions
+
+<dl>
+ <dt>
+ id <code>string</code>
+ </dt>
+ <dd>
+ Randomly generated, 256-bit, hexadecimal encoded. Uniquely identifies the image.
+ </dd>
+ <dt>
+ parent <code>string</code>
+ </dt>
+ <dd>
+ Randomly generated, 256-bit, hexadecimal encoded. Uniquely identifies the parent image. If there is no parent image then its value is <code>""</code>.
@metalivedev
metalivedev Dec 9, 2014 Contributor

The parent id is not randomly generated -- it is the id of the parent (so it has a definite referent and is not random).

@metalivedev metalivedev commented on an outdated diff Dec 9, 2014
image/spec/v1.md
+ Cmd <code>array of strings</code>
+ </dt>
+ <dd>
+ Default arguments to the entry point of the container.
+ </dd>
+ <dt>
+ Image <code>string</code>
+ </dt>
+ <dd>
+ The ID of the image which the container runs.
+ </dd>
+ <dt>
+ Volumes <code>struct</code>
+ </dt>
+ <dd>
+ TODO: Entries are in some format... I dunno.
@metalivedev
metalivedev Dec 9, 2014 Contributor

Who can flesh this out?

@metalivedev metalivedev and 2 others commented on an outdated diff Dec 9, 2014
image/spec/v1.md
+ etc/
+ my-app-config
+ bin/
+ my-app-binary
+ my-app-tools
+```
+
+Docker then commits the `c3167915dc9d` directory as a plain Tar archive with entries for the following files:
+
+```
+/etc/my-app-config
+/bin/my-app-binary
+/bin/my-app-tools
+```
+
+The TarSum checksum for the archive file is then computed and placed in the JSON metadata along with the execution parameters and our image is built!
@metalivedev
metalivedev Dec 9, 2014 Contributor

Then where does the JSON metadata go? What is the final format for the layer data + metadata?

@jlhawn
jlhawn Dec 9, 2014 Contributor

Good point. We should definitely include documentation of what the format of docker load and docker save is. It describes how they are joined together. It's basically another Tar archive which includes the JSON metadata and archives for all of the image layers.

For example, here's what the full archive of library/busybox is (in tree format):

.
├── 5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e
│   ├── VERSION
│   ├── json
│   └── layer.tar
├── a7b8b41220991bfc754d7ad445ad27b7f272ab8b4a2c175b9512b97471d02a8a
│   ├── VERSION
│   ├── json
│   └── layer.tar
├── a936027c5ca8bf8f517923169a233e391cbb38469a75de8383b5228dc2d26ceb
│   ├── VERSION
│   ├── json
│   └── layer.tar
├── f60c56784b832dd990022afc120b8136ab3da9528094752ae13fe63a2d28dc8c
│   ├── VERSION
│   ├── json
│   └── layer.tar
└── repositories

Where the content of the VERSION files is simply:

1.0

And the repositories file is another JSON file which describes names/tags:

{  
    "busybox":{  
        "latest":"5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e"
    }
}
@jlhawn
jlhawn Dec 10, 2014 Contributor

I think I'll just add the above comment to the document...

@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

No exclamation point here

@metalivedev metalivedev commented on an outdated diff Dec 9, 2014
image/spec/v1.md
+ my-app.d/
+ default.cfg
+ bin/
+ my-app-binary
+ my-app-tools
+```
+
+We've simply removed `/etc/my-app-config` and created a file and directory at `/etc/my-app.d/default.cfg`. We've also replaced `/bin/my-app-tools` with a different file. Now when Docker commits this directory, because it has a parent image, it first compares the `f60c56784b83` directory tree with parent snapshot `c3167915dc9d` looking for files and directories that have been added, modified, or removed. It finds the following change set:
+
+```
+Added: /etc/my-app.d/default.cfg
+Modified: /bin/my-app-tools
+Deleted: /etc/my-app-config
+```
+
+It then creates a Tar Archive which contains *only* this changeset: The added and modified files in their entirety, and for each deleted item it creates an entry for an empty file at the same location but prefixes the basename of the file with `.wh.`. These `.wh.` prefixed files are known as whiteout files. The resulting Tar archive for `f60c56784b83` has the following entries:
@metalivedev
metalivedev Dec 9, 2014 Contributor

Suggested: "The filenames prefixed with .wh. are known as "whiteout" files."

Is the name the only indication of the special nature of these files? That is, if I had a file named .wh.somename actually in my tree, would the file be unpacked to the layer? I'm kind of hoping there is some permissions bit or something set that together with the name means it is a special file.

@metalivedev metalivedev commented on an outdated diff Dec 9, 2014
image/spec/v1.md
+Deleted: /etc/my-app-config
+```
+
+It then creates a Tar Archive which contains *only* this changeset: The added and modified files in their entirety, and for each deleted item it creates an entry for an empty file at the same location but prefixes the basename of the file with `.wh.`. These `.wh.` prefixed files are known as whiteout files. The resulting Tar archive for `f60c56784b83` has the following entries:
+
+```
+/etc/my-app.d/default.cfg
+/bin/my-app-tools
+/etc/.wh.my-app-config
+```
+
+Any given Docker image is likely to be composed of several of these Image Filesystem Changeset tar archives.
+
+## Loading an Image Filesystem Changeset
+
+Loading an Image Filesystem Changeset is simply the inverse of the above operation: start with an empty directory for the rootfs of the container and extract each of the changesets of an image in order, treating a whiteout file as a sign to remove the file with the given name sans the `.wh.` prefix.
@metalivedev
metalivedev Dec 9, 2014 Contributor

Do we have a reference implementation of packing and unpacking layers? I thought there was some really basic chroot filesystem driver. If so, and if it is easy to understand, we should reference it from this spec as an implementation example.

@jamescarr
Contributor

👍 this is great to see!

@jlhawn
Contributor
jlhawn commented Dec 10, 2014

I've just pushed a major update to the draft spec. Please review again if you already have!

@tiborvass tiborvass and 2 others commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+## Terminology
+
+This section will describe some common terms used by this specification and other documentation.
+
+<dl>
+ <dt>
+ Image
+ </dt>
+ <dd>
+ A collection consisting of the JSON metadata and filesystem changes of an image and those of all of its parent images.
+ </dd>
+ <dt>
+ Layer
+ </dt>
+ <dd>
+ Refers to either one or both of the JSON metadata and filesystem changes for a single link in a chain of layers that make up a complete image. To refer to either specifically, one may use the terms `Image/Layer JSON` or `Image/Layer Metadata` to refer to its JSON metadata and `Image/Layer Filesystem Changeset` or `Image/Layer Diff` to refer to the set of filesystem changes.
@tiborvass
tiborvass Dec 10, 2014 Contributor

I find this pretty hard to understand.

@jlhawn
jlhawn Dec 10, 2014 Contributor

Do you think it'd be okay to just delete the second sentence of this paragraph? I realize I probably went a little crazy in the second sentence... we really should agree on some common terminology though. It's a bit confusing to have a single term used loosely to refer to multiple things :(

@tiborvass
tiborvass Dec 10, 2014 Contributor

Do you think we could force a definition and make sure we use that everywhere?

@jlhawn
jlhawn Dec 10, 2014 Contributor

I'm okay with the first sentence definition if everyone else is.

@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

I would phrase it something like this:

Images are composed of "layers". "Image layer" is a general term which may be used to refer to one or both of the following:

  1. The metadata for the layer, described in the JSON format
  2. The filesystem changes described by a layer

To refer to the former specifically, the terms "Layer JSON" or "Layer Metadata" are frequently used.

To refer to the latter, the terms "Image Filesystem Changeset" or "Image Diff" are frequently used.

WDYT?

@jlhawn
jlhawn Dec 10, 2014 Contributor

sounds good to me, @nathanleclaire I'll update it.

@mmdriley mmdriley and 2 others commented on an outdated diff Dec 10, 2014
image/spec/v1.md
@@ -0,0 +1,532 @@
+# Docker Image Specification v1.0.0
+
+A Docker Image is an ordered collection of root filesystem changes and their corresponding execution parameters. Filesystem change sets exists as Tar archives which are extracted and applied in order starting from an empty directory. Because every image is accompanied with execution parameters, any one image layer may be run as its own Docker container as long as all ancestor changesets are applied first.
@mmdriley
mmdriley Dec 10, 2014 Contributor

What is a "filesystem change"? Clearly it has "execution parameters", so a change is something executable? In the next sentence they're "change sets"?

What does it mean to "run" a Docker container? Are all containers "runnable"? You claim all ancestors of a Docker container are runnable, but some may not include the "CMD" or "ENTRYPOINT" commands added in later layers.

I'm worried that the goal of this effort -- adding a rigorous specification that enables independent implementations -- is at risk if we start off already assuming tons of context about how the official Docker client works in December 2014.

@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

I'd specify the purpose in the first sentence, as in:

A "Docker Image" is an ordered collection of root filesystem changes and their corresponding execution parameters, for use with the Docker container runtime. Images allow the basis for executing a process which is controlled in a fine-grained way in an isolated (chroot-like) environment.

Then move the other two sentences (as they're more specific and not as general) later in the spec.

@jlhawn
jlhawn Dec 10, 2014 Contributor

@mmdriley wrote:

What does it mean to "run" a Docker container? Are all containers "runnable"? You claim all ancestors of a Docker container are runnable, but some may not include the "CMD" or "ENTRYPOINT" commands added in later layers.

Any layer of an image is still runnable. It's ultimately up to the users to either set valid defaults for the entry point and/or command and they can always set a command to run upon creating the container with any image - and they must if one isn't specified. It's also dependent upon the user to execute a command that is valid in the first place, e.g., trying to run anything in an image with an empty filesystem would simply result in an error - "file not found".

I'm worried that the goal of this effort -- adding a rigorous specification that enables independent implementations -- is at risk if we start off already assuming tons of context about how the official Docker client works in December 2014.

A lot of things in Docker seem to have traditionally been implementation driven. I'm glad to see the project now moving towards a more specification/open-design driven way of doing things. While I think the project does a good job of documenting how to use Docker, unfortunately many details on how some components are currently designed and implemented have always been spread across various parts of the code or distributed in the knowledge of maintainers and experts of different subsystems. So, I'm not quite sure how to answer this part of your question other than by just pointing out that this isn't meant to be a rigorous new specification but just description of how it already works.

@nathanleclaire I'll switch to use your suggested intro for now. @mmdriley do you have a suggestion for an abstract description of a container image that we could use as an introduction?

@mmdriley mmdriley commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ Image JSON
+ </dt>
+ <dd>
+ A JSON structure which describes some basic information about the image such as date created, author, and the ID of its parent image as well as execution/runtime configuration like its entry point, default arguments, CPU/memory shares, networking, and volumes.
+ </dd>
+ <dt>
+ Image Filesystem Changeset
+ </dt>
+ <dd>
+ An archive of the new or changed files and directories which a layer of an image has. This archive also contains special "whiteout" files, which have names beginning with `.wh.`, which describe that that file or directory has been deleted from its parent image's filesystem. These archives can be made trivially by a layer-based/union filesystem such as AUFS or OverlayFS or by computing the diff of two directories (one corresponding to a snapshot of the parent image's filesystem and the other the current image's filesystem).
+ </dd>
+ <dt>
+ Image ID
+ </dt>
+ <dd>
+ The randomly generated ID given to an image or image layer upon its creation. It is represented as a hexidecimal encoding of 256 bits, e.g., `a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`.
@mmdriley
mmdriley Dec 10, 2014 Contributor

"image or image layer" -- this seems odd. Do images and image layers have IDs in different namespaces?

Need the image ID necessarily be random, or is the assertion simply that it need not have semantic meaning?

If random, must the ID be from a CSPRNG?

@mmdriley mmdriley and 1 other commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+
+It then creates a Tar Archive which contains *only* this changeset: The added and modified files in their entirety, and for each deleted item it creates an entry for an empty file at the same location but prefixes the basename of the file with `.wh.`. The filenames prefixed with .wh. are known as "whiteout" files. NOTE: For this reason, it is not possible to create an image filesystem which contains regular files whose name begins with `.wh.`. The resulting Tar archive for `f60c56784b83` has the following entries:
+
+```
+/etc/my-app.d/default.cfg
+/bin/my-app-tools
+/etc/.wh.my-app-config
+```
+
+Any given Docker image is likely to be composed of several of these Image Filesystem Changeset tar archives.
+
+## Combined Image JSON + Filesystem Changeset Format
+
+The commands `docker load` and `docker save` work with a single Tar archive which contains complete information about an image, including:
+
+ - repository names/tags
@mmdriley
mmdriley Dec 10, 2014 Contributor

These are presented without definition.

@jlhawn
jlhawn Dec 10, 2014 Contributor

Thanks! I've added term definitions for "Repository" and "Tag" in the latest commit.

@nathanleclaire nathanleclaire commented on an outdated diff Dec 10, 2014
image/spec/v1.md
@@ -0,0 +1,539 @@
+# Docker Image Specification v1.0.0
+
+A Docker Image is an ordered collection of root filesystem changes and their corresponding execution parameters. Filesystem change sets exists as Tar archives which are extracted and applied in order starting from an empty directory. Because every image is accompanied with execution parameters, any one image layer may be run as its own Docker container as long as all ancestor changesets are applied first.
+
+## Terminology
+
+This section will describe some common terms used by this specification and other documentation.
+
+<dl>
+ <dt>
+ Image
+ </dt>
+ <dd>
+ A collection consisting of the JSON metadata and filesystem changes of an image and those of all of its parent images.
@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

This definition is recursive.

@nathanleclaire
Contributor

cc @jamtur01 would be great to get your input on this

@mmdriley mmdriley and 1 other commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ <li>The filesystem changes described by a layer.</li>
+ </ol>
+
+ To refer to the former specifically, the terms "Layer JSON" or "Layer Metadata" are frequently used. To refer to the latter, the terms "Image Filesystem Changeset" or "Image Diff" are frequently used.
+ </dd>
+ <dt>
+ Image JSON
+ </dt>
+ <dd>
+ A JSON structure which describes some basic information about the image such as date created, author, and the ID of its parent image as well as execution/runtime configuration like its entry point, default arguments, CPU/memory shares, networking, and volumes.
+ </dd>
+ <dt>
+ Image Filesystem Changeset
+ </dt>
+ <dd>
+ An archive of the new or changed files and directories which a layer of an image has. This archive also contains special "whiteout" files, which have names beginning with `.wh.`, which describe that that file or directory has been deleted from its parent image's filesystem. These archives can be made trivially by a layer-based/union filesystem such as AUFS or OverlayFS or by computing the diff of two directories (one corresponding to a snapshot of the parent image's filesystem and the other the current image's filesystem).
@mmdriley
mmdriley Dec 10, 2014 Contributor

It seems like any description of whiteout files and their semantics is going to #include the implementation details of a specific version of aufs, with specific config/compilation flags, along with the flags Docker invokes it with. For example, this paragraph from the aufs documentation:

The whiteout is for hiding files on lower branches. Also it is applied to stop readdir going lower branches. The latter case is called ’opaque directory.’ Any whiteout is an empty file, it means whiteout is just an mark. In the case of hiding lower files, the name of whiteout is ’.wh..’ And in the case of stopping readdir, the name is ’.wh..wh..opq’ or ’.wh.__dir_opaque.’ The name depends upon your compile configuration CONFIG_AUFS_COMPAT. All whiteouts are hardlinked, including ’/.wh..wh.aufs.’

@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

I'd rm the bit about whiteout files (cover it later) and phrase like:

An archive of the files which have been added, changed, or deleted in an image layer. Using a layer-based or union filesystem such as AUFS, or by computing the diff from filesystem snapshots, the filesystem changeset can be used to present a series of image layers as if it were one cohesive filesystem.

@nathanleclaire nathanleclaire commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ Image ID
+ </dt>
+ <dd>
+ The randomly generated ID given to an image or image layer upon its creation. It is represented as a hexidecimal encoding of 256 bits, e.g., `a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`.
+ </dd>
+ <dt>
+ Image Parent
+ </dt>
+ <dd>
+ The Image from which another directly descends. A given image contains a separate JSON metadata file and set of changes relative to the filesystem of its parent image. `Image Ancestor` and `Image Descendant` are also common terms.
+ </dd>
+ <dt>
+ Image Checksum
+ </dt>
+ <dd>
+ A cryptographic hash of the contents of a single image layer's filesystem changeset. Though the set of changes exists as a simple Tar archive, two archives with identical filenames and content will have different SHA digests if only their last-access or last-modified times differ. For this reason, image checksums are generated using the TarSum algorithm which produces a cryptographic hash of file contents and selected headers only. The details of this are described in the separate TarSum specification.
@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

"details of this algorithm are described in a separate TarSum specification"

@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

:s/only//

@mmdriley mmdriley commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ "Cpuset":"",
+ "AttachStdin":false,
+ "AttachStdout":false,
+ "AttachStderr":false,
+ "PortSpecs":null,
+ "ExposedPorts":null,
+ "Tty":false,
+ "OpenStdin":false,
+ "StdinOnce":false,
+ "Env":[
+ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+ ],
+ "Cmd":[
+ "/bin/sh",
+ "-c",
+ "#(nop) CMD [/bin/bash]"
@mmdriley
mmdriley Dec 10, 2014 Contributor

This /bin/sh -c #(nop) ... is a great example of a Docker implementation detail that could be nailed down here. It's used as a hack in the builder so that intermediate build steps remember the last command that was run, even when a real CMD was previously specified.

@mmdriley mmdriley commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ id <code>string</code>
+ </dt>
+ <dd>
+ Randomly generated, 256-bit, hexadecimal encoded. Uniquely identifies the image.
+ </dd>
+ <dt>
+ parent <code>string</code>
+ </dt>
+ <dd>
+ ID of the parent image. If there is no parent image then its value is <code>""</code>.
+ </dd>
+ <dt>
+ comment <code>string</code>
+ </dt>
+ <dd>
+ A comment describing the image. (Deprecated)
@mmdriley
mmdriley Dec 10, 2014 Contributor

What does "deprecated" mean? Must the field still be present for the manifest to be valid? Are there values of deprecated fields that might have effects on older Docker versions?

@nathanleclaire nathanleclaire commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ checksum <code>string</code>
+ </dt>
+ <dd>
+ Image Checksum of the filesystem changeset associated with the image layer.
+ </dd>
+ <dt>
+ Size <code>integer</code>
+ </dt>
+ <dd>
+ The size in bytes of the filesystem changeset associated with the image layer.
+ </dd>
+</dl>
+
+## Creating an Image Filesystem Changeset
+
+Building an Image Filesystem Changeset is pretty straightforward. The way Docker does it is by first creating an empty directory named with the ID of the image being created.
@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

This tone too informal for a technical spec. No "we", "our" etc. in my opinion. "An example of creating an Image Filesystem Changeset" follows.

@icecrime icecrime commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ The execution parameters which should be used as a base when running a container using the image. This field can be `null` in which case any execution parameters should be specified at creation of the image.
+
+ <h4>Container RunConfig Field Descriptions</h4>
+
+ <dl>
+ <dt>
+ Hostname <code>string</code>
+ </dt>
+ <dd>
+ The name of the local host as seen in the container running the image. DEPRECATED - this field is ignored when creating and running a Docker container and, if desired, must instead be specified upon creation of the container. The default hostname of a container is the container ID truncated to 12 characters.
+ </dd>
+ <dt>
+ Domainname <code>string</code>
+ </dt>
+ <dd>
+ The domain name of the local host as seen in the container running the image. DEPRECATED - this field is ignored when created and running a Docker container and , if desired, must instead be specified upon creation of the container using the `hostname` option if using the CLI with the fully qualified domain name requested (hostname.domainname) OR by specifying the `Domainname` field in a container create API request.
@icecrime
icecrime Dec 10, 2014 Member

s/created/creating/
s/and , /and, /

@nathanleclaire nathanleclaire commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+{
+ "busybox":{
+ "latest":"5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e"
+ }
+}
+```
+
+Every key in this object is the name of a repository, and maps to a collection of tags. Each tag maps to the ID of the image represented by that tag.
+
+## Loading an Image Filesystem Changeset
+
+Loading an Image Filesystem Changeset is simply the inverse of the above operation: start with an empty directory for the rootfs of the container and extract each of the changesets of an image in order, treating a whiteout file as a sign to remove the file with the given name sans the `.wh.` prefix.
+
+## Implementations
+
+Docker itself an evolving implementation of this specification.
@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

"Docker is an implementation of this specification which is constantly evolving."

@mmdriley mmdriley commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ comment <code>string</code>
+ </dt>
+ <dd>
+ A comment describing the image. (Deprecated)
+ </dd>
+ <dt>
+ created <code>string</code>
+ </dt>
+ <dd>
+ ISO-8601 formatted combined date and time at which the image was created.
+ </dd>
+ <dt>
+ container <code>string</code>
+ </dt>
+ <dd>
+ The identifier of the container which was used to create the image.
@mmdriley
mmdriley Dec 10, 2014 Contributor

Containers have IDs. What do they look like? Are they in the same namespace as image IDs?

@nathanleclaire nathanleclaire commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+
+And the `repositories` file is another JSON file which describes names/tags:
+
+```
+{
+ "busybox":{
+ "latest":"5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e"
+ }
+}
+```
+
+Every key in this object is the name of a repository, and maps to a collection of tags. Each tag maps to the ID of the image represented by that tag.
+
+## Loading an Image Filesystem Changeset
+
+Loading an Image Filesystem Changeset is simply the inverse of the above operation: start with an empty directory for the rootfs of the container and extract each of the changesets of an image in order, treating a whiteout file as a sign to remove the file with the given name sans the `.wh.` prefix.
@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

:s/simply//

Additionally, I'd refactor these steps into a list.

@nathanleclaire
Contributor

Nice job Josh, thanks for putting this together. I've left a variety of feedback. Looks quite good to me with one exception: image tags are not brought up at all. How are the differences between foo, bar (which was created using docker tag foo bar), and foo:quux described on disk?

Oh yes, also I would describe all of the DEPRECATED parameters in a uniform way. I would just pull the DEPRECATED line on the same line where their name and type is in italics.

@icecrime icecrime commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ </dd>
+ <dt>
+ Volumes <code>struct</code>
+ </dt>
+ <dd>
+ A set of directories which should be created as data volumes in a container running this image. This JSON structure value is unusual because it is a direct JSON serialization of the Go type <code>map[string]struct{}</code> and is represented in JSON as an object mapping its keys to an empty object. Here is an example:
+<pre>{
+ "/var/my-app-data/": {},
+ "/etc/some-config.d/": {},
+}</pre>
+ </dd>
+ <dt>
+ WorkingDir <code>string</code>
+ </dt>
+ <dd>
+ Sets the current working directory of the entry point process in the container. This value acts as a default and is replaced by a working dir specified when creating a container.
@icecrime
icecrime Dec 10, 2014 Member

Should we add this can be set in a Dockerfile using the WORKDIR instruction (similar to "User" above)?

@icecrime icecrime and 2 others commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+<pre>{
+ "/var/my-app-data/": {},
+ "/etc/some-config.d/": {},
+}</pre>
+ </dd>
+ <dt>
+ WorkingDir <code>string</code>
+ </dt>
+ <dd>
+ Sets the current working directory of the entry point process in the container. This value acts as a default and is replaced by a working dir specified when creating a container.
+ </dd>
+ <dt>
+ Entrypoint <code>array of strings</code>
+ </dt>
+ <dd>
+ A list of arguments to use as the command to execute when the container starts. This value acts as a default and is replaced by an entrypoint specified when creating a container.
@icecrime
icecrime Dec 10, 2014 Member

Should we add this can be set in a Dockerfile using the ENTRYPOINT instruction (similar to "User" above)?

@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

References to Dockerfile don't seem right in this doc, imho.

@jlhawn
jlhawn Dec 10, 2014 Contributor

I agree, I've tried to remove any descriptions that refer to a Dockerfile

@kelseyhightower

@jlhawn This is pretty awesome; nice deep dive into the image format. I really like the details regarding how the layers work -- I think I can finally say I understand how they work.

@jlhawn
Contributor
jlhawn commented Dec 10, 2014

It's all in the commit message as well, but here's a run-down of the latest change:

  • Removed description of "Image" from the terminology section. The entire
    document is meant to serve this purpose.
  • Updated the definition of "Image Filesystem Changeset".
  • Clarified the level of randomness needed for generating image IDs.
  • Updated the description of "Image Checksum".
  • Added term descriptions for "Repository" and "Tag"
  • Removed extraneous/implementation-specific fields from the Image JSON
    example file and field descriptions:
    • removed "container_config" and "docker_version" fields.
    • Added missing "author" field example and description.
  • Removed extraneous/implementation-specific fields from the "config" struct
    example and description:
    • removed "Hostname", "Domainname", "Cpuset", "AttachStdin", "AttachStdout",
      "AttachStderr", "PortSpecs", "Tty", "OpenStdin", "StdinOnce", "Image",
      "NetworkDisabled", and "OnBuild".
  • Updated example Image JSON config with better example values for "Env",
    "Cmd", "Volumes", "WorkingDir", "Entrypoint", "CpuShares", "Memory",
    "MemorySwap", and "User".
  • Added notices that any fields not specified are to be considered as
    implementation specific and should be ignored my implementations which
    are unable to interpret them.
  • Updated example of creating layer filesystem changesets to use less formal
    language.
  • Listed more details in the section regarding extraction of a bundle of image
    layers into the root filesystem of a container.
  • Updated the closing mention of Docker as an evolving implementation.

edit: Oh! also various typo/formatting fixes throughout. Thanks everyone!

@jamtur01 jamtur01 and 4 others commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+Every key in this object is the name of a repository, and maps to a collection of tag suffixes. Each tag maps to the ID of the image represented by that tag.
+
+## Loading an Image Filesystem Changeset
+
+Unpacking a bundle of image layer JSON files and their corresponding filesystem changesets can be done using a series of steps:
+
+1. Follow the parent IDs of image layers to find the root ancestor (an image with no parent ID specified).
+2. For every image layer, in order from root ancestor and descending down, extract the contents of that layer's filesystem changeset archive into a directory which will be used as the root of a container filesystem.
+
+ - Extract all contents of each archive.
+ - Walk the directory tree once more, removing any files with the prefix `.wh.` and the corresponding file or directory named without this prefix.
+
+
+## Implementations
+
+Docker is an implementation of this specification which is constantly evolving.
@jamtur01
jamtur01 Dec 10, 2014 Contributor

Might want to make this sentence more clear.

@jlhawn
jlhawn Dec 10, 2014 Contributor

any suggestions for this? I've already changed it to something @nathanleclaire recommended so maybe you guys could come up with something together.

@SvenDowideit
SvenDowideit Dec 15, 2014 Collaborator

Docker is an implementation of this evolving specification.

@fredlf
fredlf Dec 16, 2014 Contributor

Well, what are you trying to communicate here? Or, more specifically, what's the important new info you are trying to convey to the reader? That the spec is constantly evolving? That Docker is an implementation of this spec? That Docker is constantly evolving? Some or all of those? None of those? Tell me, and I'll show you how to revise so that it gets across.

@mmdriley
mmdriley Dec 23, 2014 Contributor

This specification is an admittedly imperfect description of an imperfectly-understood problem. Docker is, in turn, an attempt to implement this specification. Our goal and our execution toward it will evolve over time, but our primary concern in this specification and in our implementation is compatibility and interoperability.

@jamtur01 jamtur01 and 1 other commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+
+And the `repositories` file is another JSON file which describes names/tags:
+
+```
+{
+ "busybox":{
+ "latest":"5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e"
+ }
+}
+```
+
+Every key in this object is the name of a repository, and maps to a collection of tag suffixes. Each tag maps to the ID of the image represented by that tag.
+
+## Loading an Image Filesystem Changeset
+
+Unpacking a bundle of image layer JSON files and their corresponding filesystem changesets can be done using a series of steps:
@jamtur01
jamtur01 Dec 10, 2014 Contributor

wrap lines.

@jlhawn
jlhawn Dec 10, 2014 Contributor

I'm not sure what you mean. Should I refer to the user documentation style guide for this? Is it an 80 character limit or something?

@jamtur01 jamtur01 commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+
+```
+1.0
+```
+
+And the `repositories` file is another JSON file which describes names/tags:
+
+```
+{
+ "busybox":{
+ "latest":"5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e"
+ }
+}
+```
+
+Every key in this object is the name of a repository, and maps to a collection of tag suffixes. Each tag maps to the ID of the image represented by that tag.
@jamtur01
jamtur01 Dec 10, 2014 Contributor

wrap lines.

@jamtur01
Contributor

Other than formatting to the style guide this is excellent LGTM.

@cpuguy83 cpuguy83 commented on an outdated diff Dec 10, 2014
image/spec/v1.md
@@ -0,0 +1,404 @@
+# Docker Image Specification v1.0.0
+
+A "Docker Image" is an ordered collection of root filesystem changes and their corresponding execution parameters, for use with the Docker container runtime.
@cpuguy83
cpuguy83 Dec 10, 2014 Contributor
A `Docker Image` is an ordered collection of root filesystem changes and the corresponding execution parameters for use within the Docker container runtime. Each entity in the collection is referred to as a `layer`.

Also, maybe each term should be linkable so when it's referenced (as layer is above) someone can just jump right to the definition.

@cpuguy83 cpuguy83 and 2 others commented on an outdated diff Dec 10, 2014
image/spec/v1.md
@@ -0,0 +1,404 @@
+# Docker Image Specification v1.0.0
+
+A "Docker Image" is an ordered collection of root filesystem changes and their corresponding execution parameters, for use with the Docker container runtime.
+
+## Terminology
+
+This section will describe some common terms used by this specification and other documentation.
+
+<dl>
+ <dt>
+ Layer
+ </dt>
+ <dd>
+ Images are composed of "layers". "Image layer" is a general term which may be used to refer to one or both of the following:
@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

I think this ought to be more definitive here. Also as I understand it, a layer is always comprised of both the layer json and the fs changes (which may be empty).

Images are a collection of `layers`. A `layer` is a general term which is comprised of the following:
<ol>
    <li>JSON metadata describing the execution parameters used to generate this layer</li>
    <li>The filesystem changes that occurred as a result of executing the described execution parameters</li>
</ol>
@jlhawn
jlhawn Dec 10, 2014 Contributor

@nathanleclaire I've changed this earlier to what you recommended, do you agree with @cpuguy83's edit?

@nathanleclaire
nathanleclaire Dec 10, 2014 Contributor

Seems reasonable to me!

@jlhawn
jlhawn Dec 10, 2014 Contributor

oh @cpuguy83 your reworded list items seem to imply that the JSON metadata describes the container which built that layer. This is not the case. Though Docker Images do have 2 runconfig fields: config and containerConfig, your list items better describe containerConfig which is a field that I have removed from the specification as it is a detail of how the docker build subsystem works and is not necessary for describing how to run a new container from the image, rather this is the purpose of the config section of the JSON.

@jlhawn
jlhawn Dec 10, 2014 Contributor

@nathanleclaire with that in mind, what do you think?

@cpuguy83 cpuguy83 and 1 other commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ <dt>
+ Image ID
+ </dt>
+ <dd>
+ The ID given to an image or image layer upon its creation. It is represented as a hexidecimal encoding of 256 bits, e.g., `a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`. Image IDs should be sufficiently random so as to be globally unique. 32 bytes read from `/dev/urandom` is considered to be sufficient for all practical purposes.
+ </dd>
+ <dt>
+ Image Parent
+ </dt>
+ <dd>
+ The Image from which another directly descends. A given image contains a separate JSON metadata file and set of changes relative to the filesystem of its parent image. `Image Ancestor` and `Image Descendant` are also common terms.
+ </dd>
+ <dt>
+ Image Checksum
+ </dt>
+ <dd>
@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

Link to tarsum spec

@jlhawn
jlhawn Dec 10, 2014 Contributor

Sure thing! The specification was just merged in this morning! What do you think is the best way to link to it? Link to the GitHub page with the file? what if it moves in the future? should I link to the file in that specific commit?

@jlhawn
jlhawn Dec 23, 2014 Contributor

I've decided to just link to the current file location in the master brach of this repository. If it becomes a broken link at a later time we can fix it. :)

@cpuguy83 cpuguy83 and 1 other commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ </dt>
+ <dd>
+ Sets the current working directory of the entry point process in the container. This value acts as a default and is replaced by a working directory specified when creating a container.
+ </dd>
+ <dt>
+ Entrypoint <code>array of strings</code>
+ </dt>
+ <dd>
+ A list of arguments to use as the command to execute when the container starts. This value acts as a default and is replaced by an entrypoint specified when creating a container.
+ </dd>
+ </dl>
+ Any extra fields in this config struct are considered implementation specific and should be ignored by any implementations which are unable to interpret them.
+ </dd>
+</dl>
+
+Any extra fields in the Image JSON struct are considered implementation specific and should be ignored by any implementations which are unable to interpret them.
@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

This is a dup of the above

@jlhawn
jlhawn Dec 10, 2014 Contributor

I wanted to differentiate the top-level fields in the Image JSON from the fields in the config object:

Any extra fields in this config struct ... and Any extra fields in the Image JSON struct ... If i were to have just one, where do recommend I place it in the document?

@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

I'd go with the 2nd one.

@cpuguy83 cpuguy83 and 1 other commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+Deleted: /etc/my-app-config
+```
+
+A Tar Archive is then created which contains *only* this changeset: The added and modified files in their entirety, and for each deleted item an entry for an empty file at the same location but with the basename of the file prefixed with `.wh.`. The filenames prefixed with .wh. are known as "whiteout" files. NOTE: For this reason, it is not possible to create an image root filesystem which contains a regular files with a name beginning with `.wh.`. The resulting Tar archive for `f60c56784b83` has the following entries:
+
+```
+/etc/my-app.d/default.cfg
+/bin/my-app-tools
+/etc/.wh.my-app-config
+```
+
+Any given image is likely to be composed of several of these Image Filesystem Changeset tar archives.
+
+## Combined Image JSON + Filesystem Changeset Format
+
+The commands `docker load` and `docker save` work with a single Tar archive which contains complete information about an image, including:
@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

Not sure what the point of referencing docker specific commands are.
Remember, Docker has an implementation of this spec, as such the spec shouldn't reference docker commands as it is a circular reference.

@jlhawn
jlhawn Dec 10, 2014 Contributor

I agree, I'll rework this sentence to remove references to load and save.

@cpuguy83 cpuguy83 commented on an outdated diff Dec 10, 2014
image/spec/v1.md
+ </dt>
+ <dd>
+ A list of arguments to use as the command to execute when the container starts. This value acts as a default and is replaced by an entrypoint specified when creating a container.
+ </dd>
+ </dl>
+ Any extra fields in this config struct are considered implementation specific and should be ignored by any implementations which are unable to interpret them.
+ </dd>
+</dl>
+
+Any extra fields in the Image JSON struct are considered implementation specific and should be ignored by any implementations which are unable to interpret them.
+
+## Creating an Image Filesystem Changeset
+
+An example of creating an Image Filesystem Changeset follows.
+
+An image root filesystem is first creating as an empty directory named with the ID of the image being created. Here is the initial empty directory structure for the changeset for an image with ID `c3167915dc9d` (real IDs are much longer, but this example use a truncated one here for brevity):
@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

An image root filesystem is first created as an empty directory

@cpuguy83
cpuguy83 Dec 10, 2014 Contributor

Link to the ID description. Also may be a good idea to just use a full ID everywhere anyway.

@cpuguy83
Contributor

I feel like this spec should not be referencing Docker, any of it's commands, Dockerfile's, etc... except the last line about Docker being an implementation of this spec.
Pretend Docker doesn't exist yet and we need to implement the spec in something new we are calling Docker

@jlhawn
Contributor
jlhawn commented Dec 10, 2014

I've just rebased this Pull Request on top of master and added another commit with changes after feedback from @jamtur01 and @cpuguy83 . There are still some unresolved comments though, so I'll probably be updating the draft again later.

@vbatts
Contributor
vbatts commented Dec 10, 2014

Good. Then I should like to review it. Looks like good progress.
On Dec 10, 2014 5:22 PM, "Josh Hawn" notifications@github.com wrote:

I've just rebased this Pull Request on top of master and added another
commit with changes after feed back from @jamtur01
https://github.com/jamtur01 and @cpuguy83 https://github.com/cpuguy83
. There are still some unresolved comments though, so I'll probably be
updating the draft again later.


Reply to this email directly or view it on GitHub
#9560 (comment).

@mmdriley mmdriley commented on the diff Dec 11, 2014
image/spec/v1.md
+ * `json` - The JSON metadata for an image layer
+ * `layer.tar` - The Tar archive of the filesystem changeset for an image
+ layer.
+
+The content of the `VERSION` files is simply the semantic version of the JSON
+metadata schema:
+
+```
+1.0
+```
+
+And the `repositories` file is another JSON file which describes names/tags:
+
+```
+{
+ "busybox":{
@mmdriley
mmdriley Dec 11, 2014 Contributor

It would be worth explaining why the name of the image you cite above (library/busybox) and the repository name here differ.

Perhaps it's worth using an example that doesn't leave the namespace (library/) or the host/port (index.provider.io:456) implicit?

@jlhawn
jlhawn Dec 11, 2014 Contributor

How about we use example.com/busybox:v1.0.0? I now realize that this specification doesn't even begin to describe the canonical format for image names. This needs to be added too.

@vbatts
vbatts Dec 11, 2014 Contributor

hurr. i agree this needs to be addressed, but ideally we can be clear about the transport/name, so that we leave ourselves the flexibility to continue separating transport from the name.

@mmdriley
mmdriley Dec 11, 2014 Contributor

Trying to keep transport and name separate is fine, but the Docker client today will interpret "localhost:123/hello" and "localhost:456/hello" to be different images, so the spec needs to treat them as different as well.

@jlhawn
jlhawn Dec 11, 2014 Contributor

There's a recent Pull Request from @dkjer which has an opening which I think is an excellent description of the canonical v1 image name: #8456 (comment)

@mmdriley
mmdriley Dec 11, 2014 Contributor

Note that PR defines CanonicalName to be LocalName, so it suggests library/ won't appear anywhere above. Do we therefore spec library to be a forbidden first namespace component?

Oh, also, shall we discuss namespace, repository, and tag names and constraints here?

@jlhawn
jlhawn Dec 23, 2014 Contributor

I began describing an Image Name term below Tag and Repository terms which are currently documented, but I realized that it's really difficult to begin to describe all of these things without slipping into describing what an image registry is.

I feel that the current description of repository and tag are sufficient for this spec and that domain names, ports, namespaces and their respective defaults and acceptable values are more of an expansion of Repository and Tag which should be details left for implementations to handle and document for their users.

If you disagree, please suggest a way to describe these that doesn't snowball into a full registry spec.

@mmdriley
mmdriley Dec 23, 2014 Contributor

Perhaps we could leave this format out? It's unclear how often it's used for transport or if it should be considered implementation-specific.

@jlhawn
jlhawn Dec 24, 2014 Contributor

I think it's definitely worth leaving in, otherwise there is no combined format with image JSON + layer archives (as pointed out above by @metalivedev several days ago). This format is the only way to move images around other than the push/pull mechanism which uses the registry API. I don't know exactly how many there are, but there's definitely a large number of users which deal exclusively in this format in lieu of docker push and docker pull.

@SvenDowideit
Collaborator

@fredlf we need to raise the priority of the task to migrate the doc's builds into the master Dockerfile, and move the scripts into the main make.sh tooling so that specs like this can be included in the http://docs.docker.com site. (I don't think we should move it under docs)

@SvenDowideit
Collaborator

LGTM though I would rather not use HTML, i would not worry about it right now.

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
@@ -0,0 +1,509 @@
+# Docker Image Specification v1.0.0
+
+An `Image` is an ordered collection of root filesystem changes and the
+corresponding execution parameters for use within a container runtime.
+
+## Terminology
+
+This section will describe some common terms used by this specification and
+other documentation.
@fredlf
fredlf Dec 16, 2014 Contributor

Let's reduce the number of verbs and simplify tense: "This specification uses the following terms:"

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+
+An `Image` is an ordered collection of root filesystem changes and the
+corresponding execution parameters for use within a container runtime.
+
+## Terminology
+
+This section will describe some common terms used by this specification and
+other documentation.
+
+<dl>
+ <dt>
+ Layer
+ </dt>
+ <dd>
+ Images are composed of `layers`. `Image layer` is a general term which
+ may be used to refer to one or both of the following:
@fredlf
fredlf Dec 16, 2014 Contributor

Is code style really what we want?

@fredlf fredlf and 1 other commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+<dl>
+ <dt>
+ Layer
+ </dt>
+ <dd>
+ Images are composed of `layers`. `Image layer` is a general term which
+ may be used to refer to one or both of the following:
+
+ <ol>
+ <li>The metadata for the layer, described in the JSON format.</li>
+ <li>The filesystem changes described by a layer.</li>
+ </ol>
+
+ To refer to the former specifically, the terms "Layer JSON" or "Layer
+ Metadata" are frequently used. To refer to the latter, the terms "Image
+ Filesystem Changeset" or "Image Diff" are frequently used.
@fredlf
fredlf Dec 16, 2014 Contributor

Need to get rid of the passive voice. E.g.,
To refer to the former, you can use the term "layer JSON" or "layer metadata".

@mmdriley
mmdriley Dec 16, 2014 Contributor

nit: Let's also avoid turning this spec into a conversation. For the moment the document avoids first- and second-person pronouns.

@fredlf
fredlf Dec 19, 2014 Contributor

Second person pronouns are perfectly fine. Encouraged, even, provided they are used correctly. Please refer to the style guide: http://docs.docker.com/contributing/docs_style-guide/#pronouns

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ <li>The metadata for the layer, described in the JSON format.</li>
+ <li>The filesystem changes described by a layer.</li>
+ </ol>
+
+ To refer to the former specifically, the terms "Layer JSON" or "Layer
+ Metadata" are frequently used. To refer to the latter, the terms "Image
+ Filesystem Changeset" or "Image Diff" are frequently used.
+ </dd>
+ <dt>
+ Image JSON
+ </dt>
+ <dd>
+ A JSON structure which describes some basic information about the image
+ such as date created, author, and the ID of its parent image as well as
+ execution/runtime configuration like its entry point, default
+ arguments, CPU/memory shares, networking, and volumes.
@fredlf
fredlf Dec 16, 2014 Contributor

Not a complete sentence.

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ </dd>
+ <dt>
+ Image JSON
+ </dt>
+ <dd>
+ A JSON structure which describes some basic information about the image
+ such as date created, author, and the ID of its parent image as well as
+ execution/runtime configuration like its entry point, default
+ arguments, CPU/memory shares, networking, and volumes.
+ </dd>
+ <dt>
+ Image Filesystem Changeset
+ </dt>
+ <dd>
+ An archive of the files which have been added, changed, or deleted in
+ an image layer. Using a layer-based or union filesystem such as AUFS,
@fredlf
fredlf Dec 16, 2014 Contributor

Not a complete sentence.

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ Image JSON
+ </dt>
+ <dd>
+ A JSON structure which describes some basic information about the image
+ such as date created, author, and the ID of its parent image as well as
+ execution/runtime configuration like its entry point, default
+ arguments, CPU/memory shares, networking, and volumes.
+ </dd>
+ <dt>
+ Image Filesystem Changeset
+ </dt>
+ <dd>
+ An archive of the files which have been added, changed, or deleted in
+ an image layer. Using a layer-based or union filesystem such as AUFS,
+ or by computing the diff from filesystem snapshots, the filesystem
+ changeset can be used to present a series of image layers as if it were
@fredlf
fredlf Dec 16, 2014 Contributor

w
Wrong pronoun: "...as if they were..."

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ </dd>
+ <dt>
+ Image Filesystem Changeset
+ </dt>
+ <dd>
+ An archive of the files which have been added, changed, or deleted in
+ an image layer. Using a layer-based or union filesystem such as AUFS,
+ or by computing the diff from filesystem snapshots, the filesystem
+ changeset can be used to present a series of image layers as if it were
+ one cohesive filesystem.
+ </dd>
+ <dt>
+ Image ID <a name="id_desc"></a>
+ </dt>
+ <dd>
+ The ID given to an image or image layer upon its creation. It is
@fredlf
fredlf Dec 16, 2014 Contributor

Not a complete sentence. I'm seeing a pattern here... :-)

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ <dd>
+ An archive of the files which have been added, changed, or deleted in
+ an image layer. Using a layer-based or union filesystem such as AUFS,
+ or by computing the diff from filesystem snapshots, the filesystem
+ changeset can be used to present a series of image layers as if it were
+ one cohesive filesystem.
+ </dd>
+ <dt>
+ Image ID <a name="id_desc"></a>
+ </dt>
+ <dd>
+ The ID given to an image or image layer upon its creation. It is
+ represented as a hexidecimal encoding of 256 bits, e.g.,
+ `a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`.
+ Image IDs should be sufficiently random so as to be globally unique.
+ 32 bytes read from `/dev/urandom` is considered to be sufficient for
@fredlf
fredlf Dec 16, 2014 Contributor

Simplify: "...is sufficient for..."

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ a separate JSON metadata file and set of changes relative to the
+ filesystem of its parent image. `Image Ancestor` and `Image Descendant`
+ are also common terms.
+ </dd>
+ <dt>
+ Image Checksum
+ </dt>
+ <dd>
+ A cryptographic hash of the contents of a single image layer's
+ filesystem changeset. Though the set of changes exists as a simple Tar
+ archive, two archives with identical filenames and content will have
+ different SHA digests if the last-access or last-modified times of any
+ entries differ. For this reason, image checksums are generated using
+ the TarSum algorithm which produces a cryptographic hash of file
+ contents and selected headers only. The details of algorithm this are
+ described in the separate TarSum specification.
@fredlf
fredlf Dec 16, 2014 Contributor

Yes, a link would be great. Also, there's a word flipped or missing here. Should it be "...details of this algorithm are..." ?

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ </dt>
+ <dd>
+ A cryptographic hash of the contents of a single image layer's
+ filesystem changeset. Though the set of changes exists as a simple Tar
+ archive, two archives with identical filenames and content will have
+ different SHA digests if the last-access or last-modified times of any
+ entries differ. For this reason, image checksums are generated using
+ the TarSum algorithm which produces a cryptographic hash of file
+ contents and selected headers only. The details of algorithm this are
+ described in the separate TarSum specification.
+ </dd>
+ <dt>
+ Tag
+ </dt>
+ <dd>
+ A tag serves to map a descriptive, user given name to any single image
@fredlf
fredlf Dec 16, 2014 Contributor

user-given

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ <dd>
+ ISO-8601 formatted combined date and time at which the image was
+ created.
+ </dd>
+ <dt>
+ author <code>string</code>
+ </dt>
+ <dd>
+ Gives the name and/or email address of the person or entity which
+ created and is responsible for maintaining the image.
+ </dd>
+ <dt>
+ architecture <code>string</code>
+ </dt>
+ <dd>
+ The cpu architecture which the binaries in this image are built to run
@fredlf
fredlf Dec 16, 2014 Contributor

CPU

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+ Image Checksum of the filesystem changeset associated with the image
+ layer.
+ </dd>
+ <dt>
+ Size <code>integer</code>
+ </dt>
+ <dd>
+ The size in bytes of the filesystem changeset associated with the image
+ layer.
+ </dd>
+ <dt>
+ config <code>struct</code>
+ </dt>
+ <dd>
+ The execution parameters which should be used as a base when running a
+ container using the image. This field can be `null` in which case any
@fredlf
fredlf Dec 16, 2014 Contributor

comma after null

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+```
+c3167915dc9d/
+```
+
+Files and directories are then created:
+
+```
+c3167915dc9d/
+ etc/
+ my-app-config
+ bin/
+ my-app-binary
+ my-app-tools
+```
+
+The `c3167915dc9d` directory is then committed as as a plain Tar archive with
@fredlf
fredlf Dec 16, 2014 Contributor

extra "as"

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+```
+
+The `c3167915dc9d` directory is then committed as as a plain Tar archive with
+entries for the following files:
+
+```
+etc/my-app-config
+bin/my-app-binary
+bin/my-app-tools
+```
+
+The TarSum checksum for the archive file is then computed and placed in the
+JSON metadata along with the execution parameters.
+
+To make changes to the filesystem of this container image, create a new
+directory named with a new ID, such as `f60c56784b83`, and initializes it with
@fredlf
fredlf Dec 16, 2014 Contributor

"initialize"

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+entries for the following files:
+
+```
+etc/my-app-config
+bin/my-app-binary
+bin/my-app-tools
+```
+
+The TarSum checksum for the archive file is then computed and placed in the
+JSON metadata along with the execution parameters.
+
+To make changes to the filesystem of this container image, create a new
+directory named with a new ID, such as `f60c56784b83`, and initializes it with
+a snapshot of the parent image's root filesystem, so that the directory is
+identical to that of `c3167915dc9d` (Note: a copy-on-write or union filesystem
+can make this very efficient):
@fredlf
fredlf Dec 16, 2014 Contributor

Don't need the parens.

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+which contains a default config file. There's also a change to the
+`my-app-tools` binary to handle the config layout change. The `f60c56784b83`
+directory then looks like this:
+
+```
+f60c56784b83/
+ etc/
+ my-app.d/
+ default.cfg
+ bin/
+ my-app-binary
+ my-app-tools
+```
+
+This reflects the removal of `/etc/my-app-config` and creation a file and
+directory at `/etc/my-app.d/default.cfg`. `/bin/my-app-tools` has also been
@fredlf
fredlf Dec 16, 2014 Contributor

Missing word? "...of a file..."?

@fredlf fredlf commented on an outdated diff Dec 16, 2014
image/spec/v1.md
+directory tree of the parent snapshot, `f60c56784b83`, looking for files and
+directories that have been added, modified, or removed. The following changeset
+is found:
+
+```
+Added: /etc/my-app.d/default.cfg
+Modified: /bin/my-app-tools
+Deleted: /etc/my-app-config
+```
+
+A Tar Archive is then created which contains *only* this changeset: The added
+and modified files in their entirety, and for each deleted item an entry for an
+empty file at the same location but with the basename of the file prefixed with
+`.wh.`. The filenames prefixed with .wh. are known as "whiteout" files. NOTE:
+For this reason, it is not possible to create an image root filesystem which
+contains a regular files with a name beginning with `.wh.`. The resulting Tar
@fredlf
fredlf Dec 16, 2014 Contributor

"file"

@fredlf fredlf commented on the diff Dec 16, 2014
image/spec/v1.md
@@ -0,0 +1,509 @@
+# Docker Image Specification v1.0.0
+
@fredlf
fredlf Dec 16, 2014 Contributor

This needs a proper introduction so the reader has some context to help them know what's coming. Can you summarize the purpose and content of the spec in 2-3 sentences and add them here?

@jlhawn
jlhawn Dec 23, 2014 Contributor

I've expanded the first paragraph. Let me know what you think.

@fredlf
fredlf Dec 31, 2014 Contributor

Much better! Thanks.

@fredlf
Contributor
fredlf commented Dec 16, 2014

Thanks for doing this, I think it was much needed. I made a few comments, but I think once the content is pretty well set, I'll need to go back and give it a thorough edit. That can happen after this is merged in a follow-on PR.

@SvenDowideit While I don't see an easy place for this in the current IA of the docs site, I do think we need to include things like this in our documentation. Lots of users find background like this useful as context for better understanding how and why things work the way they do. Since we're (still) a ways out from redoing the site IA, is there a place we can slot this in that makes at least some sense? Under User Guide maybe?

@crosbymichael
Member

@jlhawn is this ready to go? I think it's a needed merge documenting the current spec and reality of how images are created and consumed.

@jlhawn
Contributor
jlhawn commented Dec 17, 2014

@crosbymichael I'll take another pass to address recent comments from @SvenDowideit, @fredlf, and @mmdriley

@SvenDowideit
Collaborator

/me votes for merge and then follow on PR :)

@jlhawn
Contributor
jlhawn commented Dec 23, 2014

I've finally got a bit of time while I'm blocked on a couple of other things. Passing through now...

@jlhawn
Contributor
jlhawn commented Dec 23, 2014

I think I've addressed most concerns, but I'd like to get a 👍 from @mmdriley before we think about merging though since he's the non-Docker-Inc-employee who has been most involved in this draft.

@mmdriley mmdriley and 1 other commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ </dt>
+ <dd>
+ Each layer has an archive of the files which have been added, changed,
+ or deleted relative to its parent layer. Using a layer-based or union
+ filesystem such as AUFS, or by computing the diff from filesystem
+ snapshots, the filesystem changeset can be used to present a series of
+ image layers as if they were one cohesive filesystem.
+ </dd>
+ <dt>
+ Image ID <a name="id_desc"></a>
+ </dt>
+ <dd>
+ Each layer is given an ID upon its creation. It is
+ represented as a hexidecimal encoding of 256 bits, e.g.,
+ ß`a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`.
+ Image IDs should be sufficiently random so as to be globally unique.
@mmdriley
mmdriley Dec 23, 2014 Contributor

Would this prohibit an implementation that derived image IDs from image content?

@jlhawn
jlhawn Dec 23, 2014 Contributor

not if you use a hash function which produces output which is indistinguishable from random :D

@jlhawn
jlhawn Dec 24, 2014 Contributor

I'll add this to the spec to make it more clear :)

@jlhawn
Contributor
jlhawn commented Dec 23, 2014

Oh and I'm not sure if @shykes has taken a look at this yet but It'd be nice to get an LGTM from him too.

@mmdriley mmdriley commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ algorithm are described in the separate [TarSum specification](https://github.com/docker/docker/blob/master/pkg/tarsum/tarsum_spec.md).
+ </dd>
+ <dt>
+ Tag
+ </dt>
+ <dd>
+ A tag serves to map a descriptive, user-given name to any single image
+ ID. An image name suffix (the name component after `:`) is often
+ referred to as a tag as well, though it strictly refers to the full
+ name of an image.
+ </dd>
+ <dt>
+ Repository
+ </dt>
+ <dd>
+ A collection of tags grouped under a single namespace. For example, in
@mmdriley
mmdriley Dec 23, 2014 Contributor

I would avoid "namespace" here since it means other things to Docker.

A repository is a collection of tags with a common prefix (i.e. the same string before ':').

@mmdriley mmdriley and 1 other commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ "Memory": 2048,
+ "MemorySwap": 4096,
+ "CpuShares": 8,
+ "ExposedPorts": {
+ "8080/tcp": {}
+ },
+ "Env": [
+ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+ "FOO=docker_is_a_really",
+ "BAR=great_tool_you_know"
+ ],
+ "Entrypoint": [
+ "/bin/my-app-binary"
+ ],
+ "Cmd": [
+ "--foreground",
@mmdriley
mmdriley Dec 23, 2014 Contributor

misaligned

@jlhawn
jlhawn Dec 24, 2014 Contributor

oh no! I've mixed tabs with spaces! good catch!

@mmdriley mmdriley commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+### Image JSON Field Descriptions
+
+<dl>
+ <dt>
+ id <code>string</code>
+ </dt>
+ <dd>
+ Randomly generated, 256-bit, hexadecimal encoded. Uniquely identifies
+ the image.
+ </dd>
+ <dt>
+ parent <code>string</code>
+ </dt>
+ <dd>
+ ID of the parent image. If there is no parent image then its value is
+ <code>""</code>.
@mmdriley
mmdriley Dec 23, 2014 Contributor

Also, for completeness: no cycles. :)

@mmdriley mmdriley commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ <dd>
+ Gives the name and/or email address of the person or entity which
+ created and is responsible for maintaining the image.
+ </dd>
+ <dt>
+ architecture <code>string</code>
+ </dt>
+ <dd>
+ The CPU architecture which the binaries in this image are built to run
+ on.
+ </dd>
+ <dt>
+ os <code>string</code>
+ </dt>
+ <dd>
+ The name of the operating system which the image is built to run on.
@mmdriley
mmdriley Dec 23, 2014 Contributor

Is this drawn from an enumeration?

@mmdriley mmdriley commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ ISO-8601 formatted combined date and time at which the image was
+ created.
+ </dd>
+ <dt>
+ author <code>string</code>
+ </dt>
+ <dd>
+ Gives the name and/or email address of the person or entity which
+ created and is responsible for maintaining the image.
+ </dd>
+ <dt>
+ architecture <code>string</code>
+ </dt>
+ <dd>
+ The CPU architecture which the binaries in this image are built to run
+ on.
@mmdriley
mmdriley Dec 23, 2014 Contributor

Is this drawn from an enumeration?

@mmdriley mmdriley and 1 other commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ <dd>
+ The execution parameters which should be used as a base when running a
+ container using the image. This field can be <code>null</code>, in
+ which case any execution parameters should be specified at creation of
+ the image.
+
+ <h4>Container RunConfig Field Descriptions</h4>
+
+ <dl>
+ <dt>
+ User <code>string</code>
+ </dt>
+ <dd>
+ The user which the process in the container should run as. This
+ acts as a default value to use when the value is not specified
+ when creating a container.
@mmdriley
mmdriley Dec 23, 2014 Contributor

How should this field be interpreted? Is this a username and/or Linux UID?

@jlhawn
jlhawn Dec 24, 2014 Contributor

I'm pretty sure it's username, but I'll double check

@jlhawn
jlhawn Dec 24, 2014 Contributor

looks like it's username or UID

@mmdriley mmdriley and 1 other commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ </li>
+ <li>
+ <code>"port"</code>
+ </li>
+ </ul>
+ with the default protocol being <code>"tcp"</code> if not
+ specified.
+
+ These values act as defaults and are merged with any specified
+ when creating a container.
+ </dd>
+ <dt>
+ Env <code>array of strings</code>
+ </dt>
+ <dd>
+ Entries are in the format of <code>VARNAME="var value"</code>.
@mmdriley
mmdriley Dec 23, 2014 Contributor

Are these double-quotes normative?

@jlhawn
jlhawn Dec 24, 2014 Contributor

I probably shouldn't have included the quotes in this example. I believe the way this value should be interpreted is that the substring before the first = is the variable name and everything after is the value. In Docker, I think this is passed directly to the execution driver in this format. @crosbymichael could you clarify this for us please?

@mmdriley mmdriley commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ These values act as defaults and are merged with any specified
+ when creating a container.
+ </dd>
+ <dt>
+ Env <code>array of strings</code>
+ </dt>
+ <dd>
+ Entries are in the format of <code>VARNAME="var value"</code>.
+ These values act as defaults and are merged with any specified
+ when creating a container.
+ </dd>
+ <dt>
+ Cmd <code>array of strings</code>
+ </dt>
+ <dd>
+ Default arguments to the entry point of the container. These
@mmdriley
mmdriley Dec 23, 2014 Contributor

Not just arguments but the command as well.

@mmdriley mmdriley commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+ </dd>
+ <dt>
+ WorkingDir <code>string</code>
+ </dt>
+ <dd>
+ Sets the current working directory of the entry point process
+ in the container. This value acts as a default and is replaced
+ by a working directory specified when creating a container.
+ </dd>
+ <dt>
+ Entrypoint <code>array of strings</code>
+ </dt>
+ <dd>
+ A list of arguments to use as the command to execute when the
+ container starts. This value acts as a default and is replaced
+ by an entrypoint specified when creating a container.
@mmdriley
mmdriley Dec 23, 2014 Contributor

ENTRYPOINT and CMD do serve different purposes, but by this point in the spec it's not clear how they should be interpreted differently.

@mmdriley mmdriley commented on the diff Dec 23, 2014
image/spec/v1.md
+ by an entrypoint specified when creating a container.
+ </dd>
+ </dl>
+ </dd>
+</dl>
+
+Any extra fields in the Image JSON struct are considered implementation
+specific and should be ignored by any implementations which are unable to
+interpret them.
+
+## Creating an Image Filesystem Changeset
+
+An example of creating an Image Filesystem Changeset follows.
+
+An image root filesystem is first creating as an empty directory named with the
+ID of the image being created. Here is the initial empty directory structure
@mmdriley
mmdriley Dec 23, 2014 Contributor

The name of the directory doesn't matter, does it? At least, not for the most common image format.

@jlhawn
jlhawn Dec 24, 2014 Contributor

Nope. I'll add this to the end of the paragraph:

Implementations need not name the rootfs directory in this way but it may be
convenient for keeping record of a large number of image layers.

@mmdriley mmdriley and 1 other commented on an outdated diff Dec 23, 2014
image/spec/v1.md
+replaced with an updated version. Before committing this directory to a
+changeset, because it has a parent image, it is first compared with the
+directory tree of the parent snapshot, `f60c56784b83`, looking for files and
+directories that have been added, modified, or removed. The following changeset
+is found:
+
+```
+Added: /etc/my-app.d/default.cfg
+Modified: /bin/my-app-tools
+Deleted: /etc/my-app-config
+```
+
+A Tar Archive is then created which contains *only* this changeset: The added
+and modified files in their entirety, and for each deleted item an entry for an
+empty file at the same location but with the basename of the file prefixed with
+`.wh.`. The filenames prefixed with .wh. are known as "whiteout" files. NOTE:
@mmdriley
mmdriley Dec 23, 2014 Contributor

What if I delete a directory?

@jlhawn
jlhawn Dec 24, 2014 Contributor

it should be the same logic and is explained in the last paragraph of this section:

  • Extract all contents of each archive.
  • Walk the directory tree once more, removing any files with the prefix
    .wh. and the corresponding file or directory named without this prefix.
@tianon tianon and 1 other commented on an outdated diff Dec 24, 2014
image/spec/v1.md
+ <dd>
+ The execution parameters which should be used as a base when running a
+ container using the image. This field can be <code>null</code>, in
+ which case any execution parameters should be specified at creation of
+ the image.
+
+ <h4>Container RunConfig Field Descriptions</h4>
+
+ <dl>
+ <dt>
+ User <code>string</code>
+ </dt>
+ <dd>
+ The username or UID which the process in the container should
+ run as. This acts as a default value to use when the value is
+ not specified when creating a container.
@tianon
tianon Dec 24, 2014 Member

All the following are valid:

  • user
  • uid
  • user:group
  • uid:gid
  • uid:group
  • user:gid

If group/gid is not specified, the default group and supplementary groups of the given user/uid in /etc/passwd from the container are applied.

@jlhawn
jlhawn Dec 24, 2014 Contributor

thanks @tianon !

@mmdriley
Contributor
mmdriley commented Jan 1, 2015

lgtm. No doubt there are still nits to be picked, but this is a great step forward in unambiguously-described behavior. Thanks for your time and effort in compiling it.

@crosbymichael
Member

@jlhawn Any more edits remaining?

There is no reason for shykes to look at this if you are just documenting the reality of the current system.

@shykes
Contributor
shykes commented Jan 5, 2015

Correct, if we're documenting today's design don't feel obligated to wait for my +1

@jlhawn
Contributor
jlhawn commented Jan 5, 2015

@crosbymichael I think I just need to add in the User field description from @tianon and we're set!

@jessfraz jessfraz added the docs-only label Jan 6, 2015
@bfirsh
Contributor
bfirsh commented Jan 12, 2015

This is brilliant. Thanks @jlhawn. I'm really glad we're taking steps towards specifying how Docker works.

Perhaps we could this in for Docker 1.5 and shout about it a bit. ^_^

@jessfraz
Contributor

I don't know what we are waiting on @jlhawn

@jessfraz
Contributor

Maybe just a squash of commits?

@jlhawn jlhawn Adds Docker Image v1 Spec Documention
Many iterations have gone into documenting a v1 specification of Docker's Image
format.

v1 Image spec: clarify parent field

- metalivedev pointed out that the description was ambiguous, so I've removed
  mention that it was randomly generated. It IS the ID of the parent image.

Updated v1 image specificatino documentation

- More complete details and deprication notifications for each field
  in the JSON metadata of an image.
- Details on the format for packaging combined Image JSON + Filesystem
  Changeset archives for all layers of an image.

Clarify description of an image "Layer" in v1 spec

Updated intro of image v1 spec

Updated image v1 spec after more review

- Removed description of "Image" from the terminology section. The entire
  document is meant to serve this purpose.
- Updated the definition of "Image Filesystem Changeset".
- Clarified the level of randomness needed for generating image IDs.
- Updated the description of "Image Checksum".
- Added term descriptions for "Repository" and "Tag"
- Removed extraneous/implementation-specific fields from the Image JSON
  example file and field descriptions:
  - removed "container_config" and "docker_version" fields.
  - Added missing "author" field example and description.
- Removed extraneous/implementation-specific fields from the "config" struct
  example and description:
  - removed "Hostname", "Domainname", "Cpuset", "AttachStdin", "AttachStdout",
    "AttachStderr", "PortSpecs", "Tty", "OpenStdin", "StdinOnce", "Image",
    "NetworkDisabled", and "OnBuild".
- Updated example Image JSON config with better example values for "Env",
  "Cmd", "Volumes", "WorkingDir", "Entrypoint", "CpuShares", "Memory",
  "MemorySwap", and "User".
- Added notices that any fields not specified are to be considered as
  implementation specific and should be ignored my implementations which
  are unable to interpret them.
- Updated example of creating layer filesystem changesets to use less formal
  language.
- Listed more details in the section regarding extraction of a bundle of image
  layers into the root filesystem of a container.
- Updated the closing mention of Docker as an evolving implementation.

More updates to the v1 image spec

- Added line wrapping after 80 columns per line to adhere to documentation
  style guides, as pointed out by @jamtur01

- Removed references to any specific docker commands, updated a few descriptions
  or drop repeated statements, as pointed out by @cpuguy83

Cleanup image v1 spec draft after fredlf comments

Address comments by mmdriley on v1 image spec

Improve description of image v1 spec 'config.User`

- Improves description of image v1 specification for the 'User' runtime
  parameter after recomendations by tianon.

Docker-DCO-1.1-Signed-off-by: Josh Hawn <josh.hawn@docker.com> (github: jlhawn)
7991062
@jlhawn
Contributor
jlhawn commented Jan 12, 2015

@jfrazelle All squashed!

@jessfraz jessfraz merged commit 0192b6c into docker:master Jan 12, 2015

1 check was pending

default The build is pending on drone.io
Details
@jessfraz
Contributor

awesome!

@thaJeztah
Member

Thanks @jlhawn!

@ankushagarwal
Contributor

Shouldn't this be : specified at creation of the *container*

Contributor

you're right! good catch!

@ankushagarwal
Contributor

Pardon me but, shouldn't this be called Layer JSON? From the definition, it looks like it contains metadata about only one layer of an image. Image JSON feels like it describes the metadata of Image as a whole.

@ankushagarwal
Contributor

Is Image ID different from Layer ID or is Image ID just the ID of the topmost layer?

@odino
odino commented Jan 15, 2015

I was talking to @shykes about this at the dockercon in amsterdam...great job guys!

@jlhawn jlhawn deleted the jlhawn:image_spec branch Jul 31, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment