From 03a17a2887ce9a07768e6982a8ccae9b35bc86c6 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 8 Feb 2024 22:47:28 +0100 Subject: [PATCH] migrate image spec to github.com/moby/docker-image-spec The specification was migrated to a separate module: https://github.com/moby/docker-image-spec Signed-off-by: Sebastiaan van Stijn --- api/types/container/config.go | 2 +- daemon/containerd/image.go | 2 +- daemon/containerd/image_builder.go | 2 +- daemon/containerd/image_commit.go | 2 +- daemon/containerd/image_import.go | 2 +- daemon/containerd/imagespec.go | 2 +- image/spec/README.md | 64 +- image/spec/spec.md | 717 +----------------- image/spec/specs-go/v1/image_deprecated.go | 31 + image/spec/specs-go/version_deprecated.go | 12 + image/spec/v1.1.md | 21 +- image/spec/v1.2.md | 21 +- image/spec/v1.md | 21 +- vendor.mod | 1 + vendor.sum | 2 + .../github.com/moby/docker-image-spec/LICENSE | 201 +++++ .../docker-image-spec}/specs-go/v1/image.go | 0 .../docker-image-spec}/specs-go/version.go | 2 +- vendor/modules.txt | 4 + 19 files changed, 268 insertions(+), 841 deletions(-) create mode 100644 image/spec/specs-go/v1/image_deprecated.go create mode 100644 image/spec/specs-go/version_deprecated.go create mode 100644 vendor/github.com/moby/docker-image-spec/LICENSE rename {image/spec => vendor/github.com/moby/docker-image-spec}/specs-go/v1/image.go (100%) rename {image/spec => vendor/github.com/moby/docker-image-spec}/specs-go/version.go (83%) diff --git a/api/types/container/config.go b/api/types/container/config.go index be41d6315e5d7..86f46b74afc49 100644 --- a/api/types/container/config.go +++ b/api/types/container/config.go @@ -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. diff --git a/daemon/containerd/image.go b/daemon/containerd/image.go index 9822d88cb1516..8d0067360a2cf 100644 --- a/daemon/containerd/image.go +++ b/daemon/containerd/image.go @@ -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" diff --git a/daemon/containerd/image_builder.go b/daemon/containerd/image_builder.go index 148ed2b463017..5f3a40e4783c5 100644 --- a/daemon/containerd/image_builder.go +++ b/daemon/containerd/image_builder.go @@ -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" diff --git a/daemon/containerd/image_commit.go b/daemon/containerd/image_commit.go index d78c038659ef5..568bf8dfa83b1 100644 --- a/daemon/containerd/image_commit.go +++ b/daemon/containerd/image_commit.go @@ -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" diff --git a/daemon/containerd/image_import.go b/daemon/containerd/image_import.go index 8b33053d46c8d..e6af188e21586 100644 --- a/daemon/containerd/image_import.go +++ b/daemon/containerd/image_import.go @@ -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" diff --git a/daemon/containerd/imagespec.go b/daemon/containerd/imagespec.go index 932119999b75c..f3fba60849e45 100644 --- a/daemon/containerd/imagespec.go +++ b/daemon/containerd/imagespec.go @@ -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" ) diff --git a/image/spec/README.md b/image/spec/README.md index 75855c7509796..4466692719604 100644 --- a/image/spec/README.md +++ b/image/spec/README.md @@ -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 diff --git a/image/spec/spec.md b/image/spec/spec.md index 6dcbc2e1f8865..1415e10efe76e 100644 --- a/image/spec/spec.md +++ b/image/spec/spec.md @@ -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: - -
-
- Layer -
-
- Images are composed of layers. 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. -
-
- Image JSON -
-
- 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. -
-
- Image Filesystem Changeset -
-
- 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. -
-
- Layer DiffID -
-
- 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., - sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9. - 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. -
-
- Layer ChainID -
-
- For convenience, it is sometimes useful to refer to a stack of layers - with a single identifier. This is called a ChainID. For a - single layer (or the layer at the bottom of a stack), the - ChainID is equal to the layer's DiffID. - Otherwise the ChainID is given by the formula: - ChainID(layerN) = SHA256hex(ChainID(layerN-1) + " " + DiffID(layerN)). -
-
- ImageID -
-
- 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., - sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9. - Since the configuration JSON that gets hashed references hashes of each - layer in the image, this formulation of the ImageID makes images - content-addressable. -
-
- Tag -
-
- A tag serves to map a descriptive, user-given name to any single image - ID. Tag values are limited to the set of characters - [a-zA-Z0-9_.-], except they may not start with a . - or - character. Tags are limited to 128 characters. -
-
- Repository -
-
- A collection of tags grouped under a common prefix (the name component - before :). For example, in an image tagged with the name - my-app:3.1.4, my-app is the Repository - 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 - _ characters. If a hostname is present, it may optionally - be followed by a port number in the format :8080. - 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. -
-
- -## Image JSON Description - -Here is an example image JSON file: - -``` -{ - "created": "2015-10-31T22:22:56.015925234Z", - "author": "Alyssa P. Hacker <alyspdev@example.com>", - "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 - -
-
- created string -
-
- ISO-8601 formatted combined date and time at which the image was - created. -
-
- author string -
-
- Gives the name and/or email address of the person or entity which - created and is responsible for maintaining the image. -
-
- architecture string -
-
- The CPU architecture which the binaries in this image are built to run - on. Possible values include: -
    -
  • 386
    • -
  • amd64
    • -
  • arm
    • -
- More values may be supported in the future and any of these may or may - not be supported by a given container runtime implementation. -
-
- os string -
-
- The name of the operating system which the image is built to run on. - Possible values include: -
    -
  • darwin
    • -
  • freebsd
    • -
  • linux
    • -
- More values may be supported in the future and any of these may or may - not be supported by a given container runtime implementation. -
-
- config struct -
-
- 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 container. -

Container RunConfig Field Descriptions

-
-
- User string -
-
-

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.

-

All of 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.

-
-
- Memory integer -
-
- Memory limit (in bytes). This acts as a default value to use - when the value is not specified when creating a container. -
-
- MemorySwap integer -
-
- Total memory usage (memory + swap); set to -1 to - disable swap. This acts as a default value to use when the - value is not specified when creating a container. -
-
- CpuShares integer -
-
- 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. -
-
- ExposedPorts struct -
-
- 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 - map[string]struct{} and is represented in JSON as - an object mapping its keys to an empty object. Here is an - example: -
{
-    "8080": {},
-    "53/udp": {},
-    "2356/tcp": {}
-}
- Its keys can be in the format of: -
    -
  • - "port/tcp" -
    • -
  • - "port/udp" -
    • -
  • - "port" -
    • -
- with the default protocol being "tcp" if not - specified. These values act as defaults and are merged with - any specified when creating a container. -
-
- Env array of strings -
-
- Entries are in the format of VARNAME="var value". - These values act as defaults and are merged with any specified - when creating a container. -
-
- Entrypoint array of strings -
-
- 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. -
-
- Cmd array of strings -
-
- 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 Entrypoint value is - not specified, then the first entry of the Cmd - array should be interpreted as the executable to run. -
-
- ArgsEscaped boolean -
-
- Used for Windows images to indicate that the Entrypoint - or Cmd 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 Entrypoint or CmdCmd - should be used as-is to avoid double escaping. - Note, the exact behavior of ArgsEscaped is complex - and subject to implementation details. -
-
- Healthcheck struct -
-
- A test to perform to determine whether the container is healthy. - Here is an example: -
{
-  "Test": [
-      "CMD-SHELL",
-      "/usr/bin/check-health localhost"
-  ],
-  "Interval": 30000000000,
-  "Timeout": 10000000000,
-  "Retries": 3,
-  "StartInterval": 3000000000
-}
- The object has the following fields. -
-
- Test array of strings -
-
- The test to perform to check that the container is healthy. - The options are: -
    -
  • [] : inherit healthcheck from base image
    • -
  • ["NONE"] : disable healthcheck
    • -
  • ["CMD", arg1, arg2, ...] : exec arguments directly
    • -
  • ["CMD-SHELL", command] : run command with system's default shell
    • -
- The test command should exit with a status of 0 if the container is healthy, - or with 1 if it is unhealthy. -
-
- Interval integer -
-
- Number of nanoseconds to wait between probe attempts. -
-
- Timeout integer -
-
- Number of nanoseconds to wait before considering the check to have hung. -
-
- Retries integer -
-
- The number of consecutive failures needed to consider a container as unhealthy. -
-
- StartInterval integer -
-
- Number of nanoseconds to wait between probe attempts during the start period. -
-
- 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. -
-
- Volumes struct -
-
- 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 map[string]struct{} and is represented in - JSON as an object mapping its keys to an empty object. Here is - an example: -
{
-    "/var/my-app-data/": {},
-    "/etc/some-config.d/": {},
-}
-
-
- WorkingDir string -
-
- 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. -
-
- OnBuild array of strings -
-
- 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. -
-
- Shell array of strings -
-
- Override the default shell used for the *shell* form of - commands during "build". The default shell on Linux is - ["/bin/sh", "-c"], and ["cmd", "/S", "/C"] - on Windows. This field is set by the SHELL - instruction in a Dockerfile, and *must* be written in JSON - form. -
-
-
-
- rootfs struct -
-
- 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: -
    -
  • - type is usually set to layers. -
    • -
  • - diff_ids is an array of layer content hashes (DiffIDs), in order from bottom-most to top-most. -
    • -
- Here is an example rootfs section: -
"rootfs": {
-  "diff_ids": [
-    "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
-    "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
-    "sha256:13f53e08df5a220ab6d13c58b2bf83a59cbdc2e04d0a3f041ddf4b0ba4112d49"
-  ],
-  "type": "layers"
-}
-
-
- history struct -
-
- history 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. -
    -
  • - created: Creation time, expressed as a ISO-8601 formatted - combined date and time -
    • -
  • - author: The author of the build point -
    • -
  • - created_by: The command which created the layer -
    • -
  • - comment: A custom message set when creating the layer -
    • -
  • - empty_layer: 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). -
    • -
- Here is an example history section: -
"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
-  }
-]
-
-
- -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 diff --git a/image/spec/specs-go/v1/image_deprecated.go b/image/spec/specs-go/v1/image_deprecated.go new file mode 100644 index 0000000000000..57e5795267629 --- /dev/null +++ b/image/spec/specs-go/v1/image_deprecated.go @@ -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 diff --git a/image/spec/specs-go/version_deprecated.go b/image/spec/specs-go/version_deprecated.go new file mode 100644 index 0000000000000..fca6fb3180799 --- /dev/null +++ b/image/spec/specs-go/version_deprecated.go @@ -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]. +) diff --git a/image/spec/v1.1.md b/image/spec/v1.1.md index 9b2f6b8dc2429..a31b035186cdb 100644 --- a/image/spec/v1.1.md +++ b/image/spec/v1.1.md @@ -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 diff --git a/image/spec/v1.2.md b/image/spec/v1.2.md index 5046f8e4fbe20..85d3a5f51369d 100644 --- a/image/spec/v1.2.md +++ b/image/spec/v1.2.md @@ -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 diff --git a/image/spec/v1.md b/image/spec/v1.md index ef641b11f7943..734c61a348dd0 100644 --- a/image/spec/v1.md +++ b/image/spec/v1.md @@ -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 diff --git a/vendor.mod b/vendor.mod index f262ca1c6e8b7..9e3f3b6075c3d 100644 --- a/vendor.mod +++ b/vendor.mod @@ -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 diff --git a/vendor.sum b/vendor.sum index 5832f697296dc..462923d3bba22 100644 --- a/vendor.sum +++ b/vendor.sum @@ -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= diff --git a/vendor/github.com/moby/docker-image-spec/LICENSE b/vendor/github.com/moby/docker-image-spec/LICENSE new file mode 100644 index 0000000000000..261eeb9e9f8b2 --- /dev/null +++ b/vendor/github.com/moby/docker-image-spec/LICENSE @@ -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. diff --git a/image/spec/specs-go/v1/image.go b/vendor/github.com/moby/docker-image-spec/specs-go/v1/image.go similarity index 100% rename from image/spec/specs-go/v1/image.go rename to vendor/github.com/moby/docker-image-spec/specs-go/v1/image.go diff --git a/image/spec/specs-go/version.go b/vendor/github.com/moby/docker-image-spec/specs-go/version.go similarity index 83% rename from image/spec/specs-go/version.go rename to vendor/github.com/moby/docker-image-spec/specs-go/version.go index 560e7d0f8cb4c..5e6058aa60e76 100644 --- a/image/spec/specs-go/version.go +++ b/vendor/github.com/moby/docker-image-spec/specs-go/version.go @@ -1,4 +1,4 @@ -package v1 +package specs const ( Version = "v1.3" diff --git a/vendor/modules.txt b/vendor/modules.txt index 8f0015defadbf..9531bc386e0d0 100644 --- a/vendor/modules.txt +++ b/vendor/modules.txt @@ -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