Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

serialization: remove combined spec #95

Merged
merged 1 commit into from
May 31, 2016
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 0 additions & 99 deletions serialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -473,102 +473,3 @@ The resulting Tar archive for `f60c56784b83` has the following entries:
```

Any given image is likely to be composed of several of these Image Filesystem Changeset tar archives.

## Combined Image JSON + Filesystem Changeset Format

There is also a format for a single archive which contains complete information about an image, including:

- repository names/tags
- image configuration JSON file
- all tar archives of each layer filesystem changesets

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

```
.
|-- 88ecdbb5a908bd1bdbb921110a6134d6916f962680da0c4628102ff0691b38b3.json
|-- 5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e
| |-- VERSION
| |-- json
| |-- layer.tar
|-- a7b8b41220991bfc754d7ad445ad27b7f272ab8b4a2c175b9512b97471d02a8a
| |-- VERSION
| |-- json
| |-- layer.tar
|-- a936027c5ca8bf8f517923169a233e391cbb38469a75de8383b5228dc2d26ceb
| |-- VERSION
| |-- json
| |-- layer.tar
|-- f60c56784b832dd990022afc120b8136ab3da9528094752ae13fe63a2d28dc8c
| |-- VERSION
| |-- json
| |-- layer.tar
|-- manifest.json
|-- repositories
```

There is a directory for each layer in the image.
Each directory is named with 64 character hex name that is deterministically generated from the layer information.
These names are not necessarily layer DiffIDs or ChainIDs.
Each of these directories contains 3 files:

* `VERSION` - The schema version of the `json` file
* `json` - The legacy JSON metadata for an image layer.
In this version of the image specification, layers don't have JSON metadata, but in [version 1](v1.md), they did.
A file is created for each layer in the v1 format for backward compatiblity.
* `layer.tar` - The Tar archive of the filesystem changeset for an image layer.

Note that this directory layout is only important for backward compatibility.
Current implementations use the paths specified in `manifest.json`.

The content of the `VERSION` files is simply the semantic version of the JSON metadata schema:

```
1.0
```

The `repositories` file is another JSON file which describes names/tags:

```
{
"busybox":{
"latest":"5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a"
}
}
```

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.
This file is only used for backwards compatibility.
Current implementations use the `manifest.json` file instead.

The `manifest.json` file provides the image JSON for the top-level image, and optionally for parent images that this image was derived from.
It consists of an array of metadata entries:

```
[
{
"Config": "47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json",
"RepoTags": ["busybox:latest"],
"Layers": [
"a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198/layer.tar",
"5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a/layer.tar"
]
}
]
```

There is an entry in the array for each image.

The `Config` field references another file in the tar which includes the image JSON for this image.

The `RepoTags` field lists references pointing to this image.

The `Layers` field points to the filesystem changeset tars.

An optional `Parent` field references the imageID of the parent image.
This parent must be part of the same `manifest.json` file.

This file shouldn't be confused with the distribution manifest, used to push and pull images.

Generally, implementations that support this version of the spec will use the `manifest.json` file if available, and older implementations will use the legacy `*/json` files and `repositories`.