beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

migrate image spec to github.com/moby/docker-image-spec

Browse source 
The specification was migrated to a separate module:
https://github.com/moby/docker-image-spec

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2024-02-08 22:47:28 +01:00
parent 97478c99f8
commit 03a17a2887
No known key found for this signature in database
GPG key ID: 76698F39D527CE8C
19 changed files with 268 additions and 841 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
api/types/container/config.go
View file

@ -5,8 +5,8 @@ import (
"time"
"github.com/docker/docker/api/types/strslice"
dockerspec "github.com/docker/docker/image/spec/specs-go/v1"
"github.com/docker/go-connections/nat"
dockerspec "github.com/moby/docker-image-spec/specs-go/v1"
)
// MinimumDuration puts a minimum on user configured duration.

2
daemon/containerd/image.go
View file

@ -19,7 +19,7 @@ import (
"github.com/docker/docker/daemon/images"
"github.com/docker/docker/errdefs"
"github.com/docker/docker/image"
imagespec "github.com/docker/docker/image/spec/specs-go/v1"
imagespec "github.com/moby/docker-image-spec/specs-go/v1"
"github.com/opencontainers/go-digest"
ocispec "github.com/opencontainers/image-spec/specs-go/v1"
"github.com/pkg/errors"

2
daemon/containerd/image_builder.go
View file

@ -27,7 +27,6 @@ import (
"github.com/docker/docker/builder"
"github.com/docker/docker/errdefs"
dimage "github.com/docker/docker/image"
imagespec "github.com/docker/docker/image/spec/specs-go/v1"
"github.com/docker/docker/internal/compatcontext"
"github.com/docker/docker/layer"
"github.com/docker/docker/pkg/archive"
@ -35,6 +34,7 @@ import (
"github.com/docker/docker/pkg/streamformatter"
"github.com/docker/docker/pkg/stringid"
registrypkg "github.com/docker/docker/registry"
imagespec "github.com/moby/docker-image-spec/specs-go/v1"
"github.com/opencontainers/go-digest"
"github.com/opencontainers/image-spec/identity"
"github.com/opencontainers/image-spec/specs-go"

2
daemon/containerd/image_commit.go
View file

@ -20,9 +20,9 @@ import (
"github.com/containerd/log"
"github.com/docker/docker/api/types/backend"
"github.com/docker/docker/image"
imagespec "github.com/docker/docker/image/spec/specs-go/v1"
"github.com/docker/docker/internal/compatcontext"
"github.com/docker/docker/pkg/archive"
imagespec "github.com/moby/docker-image-spec/specs-go/v1"
"github.com/opencontainers/go-digest"
"github.com/opencontainers/image-spec/identity"
ocispec "github.com/opencontainers/image-spec/specs-go/v1"

2
daemon/containerd/image_import.go
View file

@ -20,11 +20,11 @@ import (
"github.com/docker/docker/builder/dockerfile"
"github.com/docker/docker/errdefs"
"github.com/docker/docker/image"
imagespec "github.com/docker/docker/image/spec/specs-go/v1"
"github.com/docker/docker/internal/compatcontext"
"github.com/docker/docker/pkg/archive"
"github.com/docker/docker/pkg/pools"
"github.com/google/uuid"
imagespec "github.com/moby/docker-image-spec/specs-go/v1"
"github.com/opencontainers/go-digest"
"github.com/opencontainers/image-spec/specs-go"
ocispec "github.com/opencontainers/image-spec/specs-go/v1"

2
daemon/containerd/imagespec.go
View file

@ -4,9 +4,9 @@ import (
"github.com/docker/docker/api/types/container"
"github.com/docker/docker/dockerversion"
"github.com/docker/docker/image"
imagespec "github.com/docker/docker/image/spec/specs-go/v1"
"github.com/docker/docker/layer"
"github.com/docker/go-connections/nat"
imagespec "github.com/moby/docker-image-spec/specs-go/v1"
"github.com/opencontainers/go-digest"
ocispec "github.com/opencontainers/image-spec/specs-go/v1"
)

64
image/spec/README.md
View file

@ -1,64 +1,4 @@
# Docker Image Specification v1.
This directory contains documents about Docker Image Specification v1.X.
The Docker Image Specification is the image specification as used by the
Docker Engine, and was used as foundation of the OCI image specification.
The Docker Image Specification provides a superset of the OCI Image specification;
it is OCI-compatible, but some extensions that are specific to the Docker
Engine implementation.
Refer to [spec.md](spec.md) for the current version of the Docker Image
Specification, and the [OCI Image specification](https://github.com/opencontainers/image-spec/)
for an in-depth specification of the OCI Image specs.
The v1 file layout and manifests are no longer used in Moby and Docker, except in `docker save` and `docker load`.
However, v1 Image JSON (`application/vnd.docker.container.image.v1+json`) has been still widely
used and officially adopted in [V2 manifest](https://github.com/distribution/distribution/blob/main/docs/content/spec/manifest-v2-2.md)
and in [OCI Image Format Specification](https://github.com/opencontainers/image-spec).
## v1.X rough Changelog
All 1.X versions are compatible with older ones.
### [v1.3](spec.md)
* Implemented in Docker v25.0
Changes:
* `StartInterval` was added to the `Healthcheck` struct in the Image JSON
### [v1.2](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.2.md)
* Implemented in Docker v1.12 (July, 2016)
* The official spec document was written in August 2016 ([#25750](https://github.com/moby/moby/pull/25750))
Changes:
* `Healthcheck` struct was added to Image JSON
### [v1.1](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.1.md)
* Implemented in Docker v1.10 (February, 2016)
* The official spec document was written in April 2016 ([#22264](https://github.com/moby/moby/pull/22264))
Changes:
* IDs were made into SHA256 digest values rather than random values
* Layer directory names were made into deterministic values rather than random ID values
* `manifest.json` was added
### [v1](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.md)
* The initial revision
* The official spec document was written in late 2014 ([#9560](https://github.com/moby/moby/pull/9560)), but actual implementations had existed even earlier
## Related specifications
* [Open Containers Initiative (OCI) Image Format Specification v1.0.0](https://github.com/opencontainers/image-spec/tree/v1.0.0)
* [Docker Image Manifest Version 2, Schema 2](https://github.com/distribution/distribution/blob/main/docs/content/spec/manifest-v2-2.md)
* [Docker Image Manifest Version 2, Schema 1](https://github.com/distribution/distribution/blob/main/docs/content/spec/deprecated-schema-v1.md) (*DEPRECATED*)
This specification moved to a separate repository:
https://github.com/moby/docker-image-spec

717
image/spec/spec.md
View file

@ -1,717 +1,4 @@
# Docker Image Specification v1.3.0
An *Image* is an ordered collection of root filesystem changes and the
corresponding execution parameters for use within a container runtime. This
specification outlines the format of these filesystem changes and corresponding
parameters and describes how to create and use them for use with a container
runtime and execution tool.
This version of the image specification was adopted starting in Docker 1.12.
## Terminology
This specification uses the following terms:
<dl>
<dt>
Layer
</dt>
<dd>
Images are composed of <i>layers</i>. Each layer is a set of filesystem
changes. Layers do not have configuration metadata such as environment
variables or default arguments - these are properties of the image as a
whole rather than any particular layer.
</dd>
<dt>
Image JSON
</dt>
<dd>
Each image has an associated 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. The JSON structure also references a cryptographic hash of
each layer used by the image, and provides history information for
those layers. This JSON is considered to be immutable, because changing
it would change the computed ImageID. Changing it means creating a new
derived image, instead of changing the existing image.
</dd>
<dt>
Image Filesystem Changeset
</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>
Layer DiffID
</dt>
<dd>
Layers are referenced by cryptographic hashes of their serialized
representation. This is a SHA256 digest over the tar archive used to
transport the layer, represented as a hexadecimal encoding of 256 bits, e.g.,
<code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
Layers must be packed and unpacked reproducibly to avoid changing the
layer ID, for example by using tar-split to save the tar headers. Note
that the digest used as the layer ID is taken over an uncompressed
version of the tar.
</dd>
<dt>
Layer ChainID
</dt>
<dd>
For convenience, it is sometimes useful to refer to a stack of layers
with a single identifier. This is called a <code>ChainID</code>. For a
single layer (or the layer at the bottom of a stack), the
<code>ChainID</code> is equal to the layer's <code>DiffID</code>.
Otherwise the <code>ChainID</code> is given by the formula:
<code>ChainID(layerN) = SHA256hex(ChainID(layerN-1) + " " + DiffID(layerN))</code>.
</dd>
<dt>
ImageID <a name="id_desc"></a>
</dt>
<dd>
Each image's ID is given by the SHA256 hash of its configuration JSON. It is
represented as a hexadecimal encoding of 256 bits, e.g.,
<code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
Since the configuration JSON that gets hashed references hashes of each
layer in the image, this formulation of the ImageID makes images
content-addressable.
</dd>
<dt>
Tag
</dt>
<dd>
A tag serves to map a descriptive, user-given name to any single image
ID. Tag values are limited to the set of characters
<code>[a-zA-Z0-9_.-]</code>, except they may not start with a <code>.</code>
or <code>-</code> character. Tags are limited to 128 characters.
</dd>
<dt>
Repository
</dt>
<dd>
A collection of tags grouped under a common prefix (the name component
before <code>:</code>). For example, in an image tagged with the name
<code>my-app:3.1.4</code>, <code>my-app</code> is the <i>Repository</i>
component of the name. A repository name is made up of slash-separated
name components, optionally prefixed by a DNS hostname. The hostname
must comply with standard DNS rules, but may not contain
<code>_</code> characters. If a hostname is present, it may optionally
be followed by a port number in the format <code>:8080</code>.
Name components may contain lowercase characters, digits, and
separators. A separator is defined as a period, one or two underscores,
or one or more dashes. A name component may not start or end with
a separator.
</dd>
</dl>
## Image JSON Description
Here is an example image JSON file:
```
{
"created": "2015-10-31T22:22:56.015925234Z",
"author": "Alyssa P. Hacker &ltalyspdev@example.com&gt",
"architecture": "amd64",
"os": "linux",
"config": {
"User": "alice",
"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",
"--config",
"/etc/my-app.d/default.cfg"
],
"Volumes": {
"/var/job-result-data": {},
"/var/log/my-app-logs": {}
},
"WorkingDir": "/home/alice"
},
"rootfs": {
"diff_ids": [
"sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
],
"type": "layers"
},
"history": [
{
"created": "2015-10-31T22:22:54.690851953Z",
"created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
},
{
"created": "2015-10-31T22:22:55.613815829Z",
"created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
"empty_layer": true
}
]
}
```
Note that image JSON files produced by Docker don't contain formatting
whitespace. It has been added to this example for clarity.
### Image JSON Field Descriptions
<dl>
<dt>
created <code>string</code>
</dt>
<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
on. Possible values include:
<ul>
<li>386</li>
<li>amd64</li>
<li>arm</li>
</ul>
More values may be supported in the future and any of these may or may
not be supported by a given container runtime implementation.
</dd>
<dt>
os <code>string</code>
</dt>
<dd>
The name of the operating system which the image is built to run on.
Possible values include:
<ul>
<li>darwin</li>
<li>freebsd</li>
<li>linux</li>
</ul>
More values may be supported in the future and any of these may or may
not be supported by a given container runtime implementation.
</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 <code>null</code>, in
which case any execution parameters should be specified at creation of
the container.
<h4>Container RunConfig Field Descriptions</h4>
<dl>
<dt>
User <code>string</code>
</dt>
<dd>
<p>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.</p>
<p>All of the following are valid:</p>
<ul>
<li><code>user</code></li>
<li><code>uid</code></li>
<li><code>user:group</code></li>
<li><code>uid:gid</code></li>
<li><code>uid:group</code></li>
<li><code>user:gid</code></li>
</ul>
<p>If <code>group</code>/<code>gid</code> is not specified, the
default group and supplementary groups of the given
<code>user</code>/<code>uid</code> in <code>/etc/passwd</code>
from the container are applied.</p>
</dd>
<dt>
Memory <code>integer</code>
</dt>
<dd>
Memory limit (in bytes). This acts as a default value to use
when the value is not specified when creating a container.
</dd>
<dt>
MemorySwap <code>integer</code>
</dt>
<dd>
Total memory usage (memory + swap); set to <code>-1</code> to
disable swap. This acts as a default value to use when the
value is not specified when creating a container.
</dd>
<dt>
CpuShares <code>integer</code>
</dt>
<dd>
CPU shares (relative weight vs. other containers). This acts as
a default value to use when the value is not specified when
creating a container.
</dd>
<dt>
ExposedPorts <code>struct</code>
</dt>
<dd>
A set of ports to expose from 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>{
"8080": {},
"53/udp": {},
"2356/tcp": {}
}</pre>
Its keys can be in the format of:
<ul>
<li>
<code>"port/tcp"</code>
</li>
<li>
<code>"port/udp"</code>
</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>.
These values act as defaults and are merged with any 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>
<dt>
Cmd <code>array of strings</code>
</dt>
<dd>
Default arguments to the entry point of the container. These
values act as defaults and are replaced with any specified when
creating a container. If an <code>Entrypoint</code> value is
not specified, then the first entry of the <code>Cmd</code>
array should be interpreted as the executable to run.
</dd>
<dt>
ArgsEscaped <code>boolean</code>
</dt>
<dd>
Used for Windows images to indicate that the <code>Entrypoint</code>
or <code>Cmd</code> or both, contain only a single element array
that is a pre-escaped, and combined into a single string, **CommandLine**.
If "true", the value in <code>Entrypoint</code> or <code>Cmd</code>Cmd
should be used as-is to avoid double escaping.
Note, the exact behavior of <code>ArgsEscaped</code> is complex
and subject to implementation details.
</dd>
<dt>
Healthcheck <code>struct</code>
</dt>
<dd>
A test to perform to determine whether the container is healthy.
Here is an example:
<pre>{
"Test": [
"CMD-SHELL",
"/usr/bin/check-health localhost"
],
"Interval": 30000000000,
"Timeout": 10000000000,
"Retries": 3,
"StartInterval": 3000000000
}</pre>
The object has the following fields.
<dl>
<dt>
Test <code>array of strings</code>
</dt>
<dd>
The test to perform to check that the container is healthy.
The options are:
<ul>
<li><code>[]</code> : inherit healthcheck from base image</li>
<li><code>["NONE"]</code> : disable healthcheck</li>
<li><code>["CMD", arg1, arg2, ...]</code> : exec arguments directly</li>
<li><code>["CMD-SHELL", command]</code> : run command with system's default shell</li>
</ul>
The test command should exit with a status of 0 if the container is healthy,
or with 1 if it is unhealthy.
</dd>
<dt>
Interval <code>integer</code>
</dt>
<dd>
Number of nanoseconds to wait between probe attempts.
</dd>
<dt>
Timeout <code>integer</code>
</dt>
<dd>
Number of nanoseconds to wait before considering the check to have hung.
</dd>
<dt>
Retries <code>integer</code>
<dt>
<dd>
The number of consecutive failures needed to consider a container as unhealthy.
</dd>
<dt>
StartInterval <code>integer</code>
<dt>
<dd>
Number of nanoseconds to wait between probe attempts during the start period.
</dd>
</dl>
In each case, the field can be omitted to indicate that the
value should be inherited from the base layer. These values act
as defaults and are merged with any specified when creating a
container.
</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 directory specified when creating a container.
</dd>
<dt>
OnBuild <code>array of strings</code>
</dt>
<dd>
This metadata defines "trigger" instructions to be executed at
a later time, when the image is used as the base for another
build. Each trigger will be executed in the context of the
downstream build, as if it had been inserted immediately after
the *FROM* instruction in the downstream Dockerfile.
</dd>
<dt>
Shell <code>array of strings</code>
</dt>
<dd>
Override the default shell used for the *shell* form of
commands during "build". The default shell on Linux is
<code>["/bin/sh", "-c"]</code>, and <code>["cmd", "/S", "/C"]</code>
on Windows. This field is set by the <code>SHELL</code>
instruction in a Dockerfile, and *must* be written in JSON
form.
</dd>
</dl>
</dd>
<dt>
rootfs <code>struct</code>
</dt>
<dd>
The rootfs key references the layer content addresses used by the
image. This makes the image config hash depend on the filesystem hash.
rootfs has two subkeys:
<ul>
<li>
<code>type</code> is usually set to <code>layers</code>.
</li>
<li>
<code>diff_ids</code> is an array of layer content hashes (<code>DiffIDs</code>), in order from bottom-most to top-most.
</li>
</ul>
Here is an example rootfs section:
<pre>"rootfs": {
"diff_ids": [
"sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
"sha256:13f53e08df5a220ab6d13c58b2bf83a59cbdc2e04d0a3f041ddf4b0ba4112d49"
],
"type": "layers"
}</pre>
</dd>
<dt>
history <code>struct</code>
</dt>
<dd>
<code>history</code> is an array of objects describing the history of
each layer. The array is ordered from bottom-most layer to top-most
layer. The object has the following fields.
<ul>
<li>
<code>created</code>: Creation time, expressed as a ISO-8601 formatted
combined date and time
</li>
<li>
<code>author</code>: The author of the build point
</li>
<li>
<code>created_by</code>: The command which created the layer
</li>
<li>
<code>comment</code>: A custom message set when creating the layer
</li>
<li>
<code>empty_layer</code>: This field is used to mark if the history
item created a filesystem diff. It is set to true if this history
item doesn't correspond to an actual layer in the rootfs section
(for example, a command like ENV which results in no change to the
filesystem).
</li>
</ul>
Here is an example history section:
<pre>"history": [
{
"created": "2015-10-31T22:22:54.690851953Z",
"created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
},
{
"created": "2015-10-31T22:22:55.613815829Z",
"created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
"empty_layer": true
}
]</pre>
</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 created as an empty directory. Here is the
initial empty directory structure for the a changeset using the
randomly-generated directory name `c3167915dc9d` ([actual layer DiffIDs are
generated based on the content](#id_desc)).
```
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 a plain Tar archive with
entries for the following files:
```
etc/my-app-config
bin/my-app-binary
bin/my-app-tools
```
To make changes to the filesystem of this container image, create a new
directory, such as `f60c56784b83`, and initialize 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:
```
f60c56784b83/
etc/
my-app-config
bin/
my-app-binary
my-app-tools
```
This example change adds a configuration directory at `/etc/my-app.d`
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 of a file and
directory at `/etc/my-app.d/default.cfg`. `/bin/my-app-tools` has also been
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 and directories in their entirety, and for each deleted item
an entry for an empty file at the same location but with the basename of the
deleted file or directory 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 file or directory 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
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):
```
.
├── 47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json
├── 5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a
│ ├── VERSION
│ ├── json
│ └── layer.tar
├── a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198
│ ├── VERSION
│ ├── json
│ └── layer.tar
├── manifest.json
└── repositories
```
There is a directory for each layer in the image. Each directory is named with
a 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 compatibility.
* `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 a 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`.
This specification moved to a separate repository:
https://github.com/moby/docker-image-spec

31
image/spec/specs-go/v1/image_deprecated.go Normal file
View file

@ -0,0 +1,31 @@
// Package v1 is deprecated and moved to github.com/moby/docker-image-spec/specs-go/v1
//
// Deprecated: use github.com/moby/docker-image-spec/specs-go instead.
package v1
import v1 "github.com/moby/docker-image-spec/specs-go/v1"
// DockerOCIImageMediaType is the media-type used for Docker Image spec images.
//
// Deprecated: use [v1.DockerOCIImageMediaType].
const DockerOCIImageMediaType = v1.DockerOCIImageMediaType
// DockerOCIImage is a ocispec.Image extended with Docker specific Config.
//
// Deprecated: use [v1.DockerOCIImage].
type DockerOCIImage = v1.DockerOCIImage
// DockerOCIImageConfig is a ocispec.ImageConfig extended with Docker specific fields.
//
// Deprecated: use [v1.DockerOCIImageConfig]
type DockerOCIImageConfig = v1.DockerOCIImageConfig
// DockerOCIImageConfigExt contains Docker-specific fields in DockerImageConfig.
//
// Deprecated: use [v1.DockerOCIImageConfigExt].
type DockerOCIImageConfigExt = v1.DockerOCIImageConfigExt
// HealthcheckConfig holds configuration settings for the HEALTHCHECK feature.
//
// Deprecated: use [v1.HealthcheckConfig].
type HealthcheckConfig = v1.HealthcheckConfig

12
image/spec/specs-go/version_deprecated.go Normal file
View file

@ -0,0 +1,12 @@
// Package v1 is deprecated and moved to github.com/moby/docker-image-spec/specs-go
//
// Deprecated: use github.com/moby/docker-image-spec/specs-go instead.
package v1
import "github.com/moby/docker-image-spec/specs-go"
const (
Version = specs.Version // Deprecated: use [specs.Version].
VersionMajor = specs.VersionMajor // Deprecated: use [specs.VersionMajor].
VersionMinor = specs.VersionMinor // Deprecated: use [specs.VersionMinor].
)

21
image/spec/v1.1.md
View file

@ -1,21 +1,4 @@
# Docker Image Specification v1.1.0
This Document described the Docker Image Specification used by Docker Engine
v1.10.0 and up. It has been superseded by Docker Image Specification v1.2.0.
The Docker Image Specification is the image specification as used by the
Docker Engine, and was used as foundation of the OCI image specification.
The Docker Image Specification provides a superset of the OCI Image specification;
it is OCI-compatible, but some extensions that are specific to the Docker
Engine implementation.
Refer to [spec.md](spec.md) for the current version of the Docker Image
Specification, and the [OCI Image specification](https://github.com/opencontainers/image-spec/)
for an in-depth specification of the OCI Image specs.
For older versions of the specification, refer to the specs in git history;
- [Docker Image Specification v1.0.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.md)
- [Docker Image Specification v1.1.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.1.md)
- [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.2.md)
This specification moved to a separate repository:
https://github.com/moby/docker-image-spec

21
image/spec/v1.2.md
View file

@ -1,21 +1,4 @@
# Docker Image Specification v1.2.0
This Document described the Docker Image Specification used by Docker Engine
v1.12.0 and up. It has been superseded by Docker Image Specification v1.3.0.
The Docker Image Specification is the image specification as used by the
Docker Engine, and was used as foundation of the OCI image specification.
The Docker Image Specification provides a superset of the OCI Image specification;
it is OCI-compatible, but some extensions that are specific to the Docker
Engine implementation.
Refer to [spec.md](spec.md) for the current version of the Docker Image
Specification, and the [OCI Image specification](https://github.com/opencontainers/image-spec/)
for an in-depth specification of the OCI Image specs.
For older versions of the specification, refer to the specs in git history;
- [Docker Image Specification v1.0.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.md)
- [Docker Image Specification v1.1.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.1.md)
- [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.2.md)
This specification moved to a separate repository:
https://github.com/moby/docker-image-spec

21
image/spec/v1.md
View file

@ -1,21 +1,4 @@
# Docker Image Specification v1.0.0
This Document described the Docker Image Specification used by Docker Engine
before v1.10.0. It has been superseded by Docker Image Specification v1.1.0.
The Docker Image Specification is the image specification as used by the
Docker Engine, and was used as foundation of the OCI image specification.
The Docker Image Specification provides a superset of the OCI Image specification;
it is OCI-compatible, but some extensions that are specific to the Docker
Engine implementation.
Refer to [spec.md](spec.md) for the current version of the Docker Image
Specification, and the [OCI Image specification](https://github.com/opencontainers/image-spec/)
for an in-depth specification of the OCI Image specs.
For older versions of the specification, refer to the specs in git history;
- [Docker Image Specification v1.0.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.md)
- [Docker Image Specification v1.1.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.1.md)
- [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/daa4618da826fb1de4fc2478d88196edbba49b2f/image/spec/v1.2.md)
This specification moved to a separate repository:
https://github.com/moby/docker-image-spec

1
vendor.mod
View file

@ -61,6 +61,7 @@ require (
github.com/mistifyio/go-zfs/v3 v3.0.1
github.com/mitchellh/copystructure v1.2.0
github.com/moby/buildkit v0.12.5
github.com/moby/docker-image-spec v1.3.1
github.com/moby/ipvs v1.1.0
github.com/moby/locker v1.0.1
github.com/moby/patternmatcher v0.6.0

2
vendor.sum
View file

@ -904,6 +904,8 @@ github.com/mndrix/tap-go v0.0.0-20171203230836-629fa407e90b/go.mod h1:pzzDgJWZ34
github.com/moby/buildkit v0.8.1/go.mod h1:/kyU1hKy/aYCuP39GZA9MaKioovHku57N6cqlKZIaiQ=
github.com/moby/buildkit v0.12.5 h1:RNHH1l3HDhYyZafr5EgstEu8aGNCwyfvMtrQDtjH9T0=
github.com/moby/buildkit v0.12.5/go.mod h1:YGwjA2loqyiYfZeEo8FtI7z4x5XponAaIWsWcSjWwso=
github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
github.com/moby/ipvs v1.1.0 h1:ONN4pGaZQgAx+1Scz5RvWV4Q7Gb+mvfRh3NsPS+1XQQ=
github.com/moby/ipvs v1.1.0/go.mod h1:4VJMWuf098bsUMmZEiD4Tjk/O7mOn3l1PTD3s4OoYAs=
github.com/moby/locker v1.0.1 h1:fOXqR41zeveg4fFODix+1Ch4mj/gT0NE1XJbp/epuBg=

201
vendor/github.com/moby/docker-image-spec/LICENSE generated vendored Normal file
View file

@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

0
image/spec/specs-go/v1/image.go → vendor/github.com/moby/docker-image-spec/specs-go/v1/image.go generated vendored
View file

2
image/spec/specs-go/version.go → vendor/github.com/moby/docker-image-spec/specs-go/version.go generated vendored
View file

@ -1,4 +1,4 @@
package v1
package specs
const (
Version = "v1.3"

4
vendor/modules.txt vendored
View file

@ -833,6 +833,10 @@ github.com/moby/buildkit/worker
github.com/moby/buildkit/worker/base
github.com/moby/buildkit/worker/containerd
github.com/moby/buildkit/worker/label
# github.com/moby/docker-image-spec v1.3.1
## explicit; go 1.18
github.com/moby/docker-image-spec/specs-go
github.com/moby/docker-image-spec/specs-go/v1
# github.com/moby/ipvs v1.1.0
## explicit; go 1.17
github.com/moby/ipvs