Skip to content

Commit

Permalink
serialization: remove combined spec
Browse files Browse the repository at this point in the history
The combined spec isn't really part of the image format and introduces
new objects that we don't have a schema for. Largely I think that it
should be replaced by something like the image layout.

opencontainers/image-spec#94
Signed-off-by: Brandon Philips <[email protected]>
  • Loading branch information
laventuraw committed Feb 8, 2022
1 parent 7e3621e commit 0932b3a
Showing 1 changed file with 0 additions and 99 deletions.
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`.

0 comments on commit 0932b3a

Please sign in to comment.