github.com/demonoid81/moby@v0.0.0-20200517203328-62dd8e17c460/image/spec/v1.1.md (about)

     1  # Docker Image Specification v1.1.0
     2  
     3  An *Image* is an ordered collection of root filesystem changes and the
     4  corresponding execution parameters for use within a container runtime. This
     5  specification outlines the format of these filesystem changes and corresponding
     6  parameters and describes how to create and use them for use with a container
     7  runtime and execution tool.
     8  
     9  This version of the image specification was adopted starting in Docker 1.10.
    10  
    11  ## Terminology
    12  
    13  This specification uses the following terms:
    14  
    15  <dl>
    16      <dt>
    17          Layer
    18      </dt>
    19      <dd>
    20          Images are composed of <i>layers</i>. Each layer is a set of filesystem
    21          changes. Layers do not have configuration metadata such as environment
    22          variables or default arguments - these are properties of the image as a
    23          whole rather than any particular layer.
    24      </dd>
    25      <dt>
    26          Image JSON
    27      </dt>
    28      <dd>
    29          Each image has an associated JSON structure which describes some
    30          basic information about the image such as date created, author, and the
    31          ID of its parent image as well as execution/runtime configuration like
    32          its entry point, default arguments, CPU/memory shares, networking, and
    33          volumes. The JSON structure also references a cryptographic hash of
    34          each layer used by the image, and provides history information for
    35          those layers. This JSON is considered to be immutable, because changing
    36          it would change the computed ImageID. Changing it means creating a new
    37          derived image, instead of changing the existing image.
    38      </dd>
    39      <dt>
    40          Image Filesystem Changeset
    41      </dt>
    42      <dd>
    43          Each layer has an archive of the files which have been added, changed,
    44          or deleted relative to its parent layer. Using a layer-based or union
    45          filesystem such as AUFS, or by computing the diff from filesystem
    46          snapshots, the filesystem changeset can be used to present a series of
    47          image layers as if they were one cohesive filesystem.
    48      </dd>
    49      <dt>
    50          Layer DiffID
    51      </dt>
    52      <dd>
    53          Layers are referenced by cryptographic hashes of their serialized
    54          representation. This is a SHA256 digest over the tar archive used to
    55          transport the layer, represented as a hexadecimal encoding of 256 bits, e.g.,
    56          <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
    57          Layers must be packed and unpacked reproducibly to avoid changing the
    58          layer ID, for example by using tar-split to save the tar headers. Note
    59          that the digest used as the layer ID is taken over an uncompressed
    60          version of the tar.
    61      </dd>
    62      <dt>
    63          Layer ChainID
    64      </dt>
    65      <dd>
    66          For convenience, it is sometimes useful to refer to a stack of layers
    67          with a single identifier. This is called a <code>ChainID</code>. For a
    68          single layer (or the layer at the bottom of a stack), the
    69          <code>ChainID</code> is equal to the layer's <code>DiffID</code>.
    70          Otherwise the <code>ChainID</code> is given by the formula:
    71          <code>ChainID(layerN) = SHA256hex(ChainID(layerN-1) + " " + DiffID(layerN))</code>.
    72      </dd>
    73      <dt>
    74          ImageID <a name="id_desc"></a>
    75      </dt>
    76      <dd>
    77          Each image's ID is given by the SHA256 hash of its configuration JSON. It is 
    78          represented as a hexadecimal encoding of 256 bits, e.g.,
    79          <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
    80          Since the configuration JSON that gets hashed references hashes of each
    81          layer in the image, this formulation of the ImageID makes images
    82          content-addressable.
    83      </dd>
    84      <dt>
    85          Tag
    86      </dt>
    87      <dd>
    88          A tag serves to map a descriptive, user-given name to any single image
    89          ID. Tag values are limited to the set of characters
    90          <code>[a-zA-Z0-9_.-]</code>, except they may not start with a <code>.</code>
    91          or <code>-</code> character. Tags are limited to 128 characters.
    92      </dd>
    93      <dt>
    94          Repository
    95      </dt>
    96      <dd>
    97          A collection of tags grouped under a common prefix (the name component
    98          before <code>:</code>). For example, in an image tagged with the name
    99          <code>my-app:3.1.4</code>, <code>my-app</code> is the <i>Repository</i>
   100          component of the name. A repository name is made up of slash-separated
   101          name components, optionally prefixed by a DNS hostname. The hostname
   102          must comply with standard DNS rules, but may not contain
   103          <code>_</code> characters. If a hostname is present, it may optionally
   104          be followed by a port number in the format <code>:8080</code>.
   105          Name components may contain lowercase characters, digits, and
   106          separators. A separator is defined as a period, one or two underscores,
   107          or one or more dashes. A name component may not start or end with
   108          a separator.
   109      </dd>
   110  </dl>
   111  
   112  ## Image JSON Description
   113  
   114  Here is an example image JSON file:
   115  
   116  ```
   117  {  
   118      "created": "2015-10-31T22:22:56.015925234Z",
   119      "author": "Alyssa P. Hacker &ltalyspdev@example.com&gt",
   120      "architecture": "amd64",
   121      "os": "linux",
   122      "config": {
   123          "User": "alice",
   124          "Memory": 2048,
   125          "MemorySwap": 4096,
   126          "CpuShares": 8,
   127          "ExposedPorts": {  
   128              "8080/tcp": {}
   129          },
   130          "Env": [  
   131              "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
   132              "FOO=docker_is_a_really",
   133              "BAR=great_tool_you_know"
   134          ],
   135          "Entrypoint": [
   136              "/bin/my-app-binary"
   137          ],
   138          "Cmd": [
   139              "--foreground",
   140              "--config",
   141              "/etc/my-app.d/default.cfg"
   142          ],
   143          "Volumes": {
   144              "/var/job-result-data": {},
   145              "/var/log/my-app-logs": {},
   146          },
   147          "WorkingDir": "/home/alice",
   148      },
   149      "rootfs": {
   150        "diff_ids": [
   151          "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
   152          "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
   153        ],
   154        "type": "layers"
   155      },
   156      "history": [
   157        {
   158          "created": "2015-10-31T22:22:54.690851953Z",
   159          "created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
   160        },
   161        {
   162          "created": "2015-10-31T22:22:55.613815829Z",
   163          "created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
   164          "empty_layer": true
   165        }
   166      ]
   167  }
   168  ```
   169  
   170  Note that image JSON files produced by Docker don't contain formatting
   171  whitespace. It has been added to this example for clarity.
   172  
   173  ### Image JSON Field Descriptions
   174  
   175  <dl>
   176      <dt>
   177          created <code>string</code>
   178      </dt>
   179      <dd>
   180          ISO-8601 formatted combined date and time at which the image was
   181          created.
   182      </dd>
   183      <dt>
   184          author <code>string</code>
   185      </dt>
   186      <dd>
   187          Gives the name and/or email address of the person or entity which
   188          created and is responsible for maintaining the image.
   189      </dd>
   190      <dt>
   191          architecture <code>string</code>
   192      </dt>
   193      <dd>
   194          The CPU architecture which the binaries in this image are built to run
   195          on. Possible values include:
   196          <ul>
   197              <li>386</li>
   198              <li>amd64</li>
   199              <li>arm</li>
   200          </ul>
   201          More values may be supported in the future and any of these may or may
   202          not be supported by a given container runtime implementation.
   203      </dd>
   204      <dt>
   205          os <code>string</code>
   206      </dt>
   207      <dd>
   208          The name of the operating system which the image is built to run on.
   209          Possible values include:
   210          <ul>
   211              <li>darwin</li>
   212              <li>freebsd</li>
   213              <li>linux</li>
   214          </ul>
   215          More values may be supported in the future and any of these may or may
   216          not be supported by a given container runtime implementation.
   217      </dd>
   218      <dt>
   219          config <code>struct</code>
   220      </dt>
   221      <dd>
   222          The execution parameters which should be used as a base when running a
   223          container using the image. This field can be <code>null</code>, in
   224          which case any execution parameters should be specified at creation of
   225          the container.
   226          <h4>Container RunConfig Field Descriptions</h4>
   227          <dl>
   228              <dt>
   229                  User <code>string</code>
   230              </dt>
   231              <dd>
   232                  <p>The username or UID which the process in the container should
   233                  run as. This acts as a default value to use when the value is
   234                  not specified when creating a container.</p>
   235                  <p>All of the following are valid:</p>
   236                  <ul>
   237                      <li><code>user</code></li>
   238                      <li><code>uid</code></li>
   239                      <li><code>user:group</code></li>
   240                      <li><code>uid:gid</code></li>
   241                      <li><code>uid:group</code></li>
   242                      <li><code>user:gid</code></li>
   243                  </ul>
   244                  <p>If <code>group</code>/<code>gid</code> is not specified, the
   245                  default group and supplementary groups of the given
   246                  <code>user</code>/<code>uid</code> in <code>/etc/passwd</code>
   247                  from the container are applied.</p>
   248              </dd>
   249              <dt>
   250                  Memory <code>integer</code>
   251              </dt>
   252              <dd>
   253                  Memory limit (in bytes). This acts as a default value to use
   254                  when the value is not specified when creating a container.
   255              </dd>
   256              <dt>
   257                  MemorySwap <code>integer</code>
   258              </dt>
   259              <dd>
   260                  Total memory usage (memory + swap); set to <code>-1</code> to
   261                  disable swap. This acts as a default value to use when the
   262                  value is not specified when creating a container.
   263              </dd>
   264              <dt>
   265                  CpuShares <code>integer</code>
   266              </dt>
   267              <dd>
   268                  CPU shares (relative weight vs. other containers). This acts as
   269                  a default value to use when the value is not specified when
   270                  creating a container.
   271              </dd>
   272              <dt>
   273                  ExposedPorts <code>struct</code>
   274              </dt>
   275              <dd>
   276                  A set of ports to expose from a container running this image.
   277                  This JSON structure value is unusual because it is a direct
   278                  JSON serialization of the Go type
   279                  <code>map[string]struct{}</code> and is represented in JSON as
   280                  an object mapping its keys to an empty object. Here is an
   281                  example:
   282  <pre>{
   283      "8080": {},
   284      "53/udp": {},
   285      "2356/tcp": {}
   286  }</pre>
   287                  Its keys can be in the format of:
   288                  <ul>
   289                      <li>
   290                          <code>"port/tcp"</code>
   291                      </li>
   292                      <li>
   293                          <code>"port/udp"</code>
   294                      </li>
   295                      <li>
   296                          <code>"port"</code>
   297                      </li>
   298                  </ul>
   299                  with the default protocol being <code>"tcp"</code> if not
   300                  specified. These values act as defaults and are merged with any
   301                  specified when creating a container.
   302              </dd>
   303              <dt>
   304                  Env <code>array of strings</code>
   305              </dt>
   306              <dd>
   307                  Entries are in the format of <code>VARNAME="var value"</code>.
   308                  These values act as defaults and are merged with any specified
   309                  when creating a container.
   310              </dd>
   311              <dt>
   312                  Entrypoint <code>array of strings</code>
   313              </dt>
   314              <dd>
   315                  A list of arguments to use as the command to execute when the
   316                  container starts. This value acts as a  default and is replaced
   317                  by an entrypoint specified when creating a container.
   318              </dd>
   319              <dt>
   320                  Cmd <code>array of strings</code>
   321              </dt>
   322              <dd>
   323                  Default arguments to the entry point of the container. These
   324                  values act as defaults and are replaced with any specified when
   325                  creating a container. If an <code>Entrypoint</code> value is
   326                  not specified, then the first entry of the <code>Cmd</code>
   327                  array should be interpreted as the executable to run.
   328              </dd>
   329              <dt>
   330                  Volumes <code>struct</code>
   331              </dt>
   332              <dd>
   333                  A set of directories which should be created as data volumes in
   334                  a container running this image. This JSON structure value is
   335                  unusual because it is a direct JSON serialization of the Go
   336                  type <code>map[string]struct{}</code> and is represented in
   337                  JSON as an object mapping its keys to an empty object. Here is
   338                  an example:
   339  <pre>{
   340      "/var/my-app-data/": {},
   341      "/etc/some-config.d/": {},
   342  }</pre>
   343              </dd>
   344              <dt>
   345                  WorkingDir <code>string</code>
   346              </dt>
   347              <dd>
   348                  Sets the current working directory of the entry point process
   349                  in the container. This value acts as a default and is replaced
   350                  by a working directory specified when creating a container.
   351              </dd>
   352          </dl>
   353      </dd>
   354      <dt>
   355          rootfs <code>struct</code>
   356      </dt>
   357      <dd>
   358          The rootfs key references the layer content addresses used by the
   359          image. This makes the image config hash depend on the filesystem hash.
   360          rootfs has two subkeys:
   361          <ul>
   362            <li>
   363              <code>type</code> is usually set to <code>layers</code>.
   364            </li>
   365            <li>
   366              <code>diff_ids</code> is an array of layer content hashes (<code>DiffIDs</code>), in order from bottom-most to top-most.
   367            </li>
   368          </ul>
   369          Here is an example rootfs section:
   370  <pre>"rootfs": {
   371    "diff_ids": [
   372      "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
   373      "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
   374      "sha256:13f53e08df5a220ab6d13c58b2bf83a59cbdc2e04d0a3f041ddf4b0ba4112d49"
   375    ],
   376    "type": "layers"
   377  }</pre>
   378      </dd>
   379      <dt>
   380          history <code>struct</code>
   381      </dt>
   382      <dd>
   383          <code>history</code> is an array of objects describing the history of
   384          each layer. The array is ordered from bottom-most layer to top-most
   385          layer. The object has the following fields.
   386          <ul>
   387            <li>
   388              <code>created</code>: Creation time, expressed as a ISO-8601 formatted
   389              combined date and time
   390            </li>
   391            <li>
   392              <code>author</code>: The author of the build point
   393            </li>
   394            <li>
   395              <code>created_by</code>: The command which created the layer
   396            </li>
   397            <li>
   398              <code>comment</code>: A custom message set when creating the layer
   399            </li>
   400            <li>
   401              <code>empty_layer</code>: This field is used to mark if the history
   402              item created a filesystem diff. It is set to true if this history
   403              item doesn't correspond to an actual layer in the rootfs section
   404              (for example, a command like ENV which results in no change to the
   405              filesystem).
   406            </li>
   407          </ul>
   408  Here is an example history section:
   409  <pre>"history": [
   410    {
   411      "created": "2015-10-31T22:22:54.690851953Z",
   412      "created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
   413    },
   414    {
   415      "created": "2015-10-31T22:22:55.613815829Z",
   416      "created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
   417      "empty_layer": true
   418    }
   419  ]</pre>
   420      </dd>
   421  </dl>
   422  
   423  Any extra fields in the Image JSON struct are considered implementation
   424  specific and should be ignored by any implementations which are unable to
   425  interpret them.
   426  
   427  ## Creating an Image Filesystem Changeset
   428  
   429  An example of creating an Image Filesystem Changeset follows.
   430  
   431  An image root filesystem is first created as an empty directory. Here is the
   432  initial empty directory structure for the a changeset using the
   433  randomly-generated directory name `c3167915dc9d` ([actual layer DiffIDs are
   434  generated based on the content](#id_desc)).
   435  
   436  ```
   437  c3167915dc9d/
   438  ```
   439  
   440  Files and directories are then created:
   441  
   442  ```
   443  c3167915dc9d/
   444      etc/
   445          my-app-config
   446      bin/
   447          my-app-binary
   448          my-app-tools
   449  ```
   450  
   451  The `c3167915dc9d` directory is then committed as a plain Tar archive with
   452  entries for the following files:
   453  
   454  ```
   455  etc/my-app-config
   456  bin/my-app-binary
   457  bin/my-app-tools
   458  ```
   459  
   460  To make changes to the filesystem of this container image, create a new
   461  directory, such as `f60c56784b83`, and initialize it with a snapshot of the
   462  parent image's root filesystem, so that the directory is identical to that
   463  of `c3167915dc9d`. NOTE: a copy-on-write or union filesystem can make this very
   464  efficient:
   465  
   466  ```
   467  f60c56784b83/
   468      etc/
   469          my-app-config
   470      bin/
   471          my-app-binary
   472          my-app-tools
   473  ```
   474  
   475  This example change is going add a configuration directory at `/etc/my-app.d`
   476  which contains a default config file. There's also a change to the
   477  `my-app-tools` binary to handle the config layout change. The `f60c56784b83`
   478  directory then looks like this:
   479  
   480  ```
   481  f60c56784b83/
   482      etc/
   483          my-app.d/
   484              default.cfg
   485      bin/
   486          my-app-binary
   487          my-app-tools
   488  ```
   489  
   490  This reflects the removal of `/etc/my-app-config` and creation of a file and
   491  directory at `/etc/my-app.d/default.cfg`. `/bin/my-app-tools` has also been
   492  replaced with an updated version. Before committing this directory to a
   493  changeset, because it has a parent image, it is first compared with the
   494  directory tree of the parent snapshot, `f60c56784b83`, looking for files and
   495  directories that have been added, modified, or removed. The following changeset
   496  is found:
   497  
   498  ```
   499  Added:      /etc/my-app.d/default.cfg
   500  Modified:   /bin/my-app-tools
   501  Deleted:    /etc/my-app-config
   502  ```
   503  
   504  A Tar Archive is then created which contains *only* this changeset: The added
   505  and modified files and directories in their entirety, and for each deleted item
   506  an entry for an empty file at the same location but with the basename of the
   507  deleted file or directory prefixed with `.wh.`. The filenames prefixed with
   508  `.wh.` are known as "whiteout" files. NOTE: For this reason, it is not possible
   509  to create an image root filesystem which contains a file or directory with a
   510  name beginning with `.wh.`. The resulting Tar archive for `f60c56784b83` has
   511  the following entries:
   512  
   513  ```
   514  /etc/my-app.d/default.cfg
   515  /bin/my-app-tools
   516  /etc/.wh.my-app-config
   517  ```
   518  
   519  Any given image is likely to be composed of several of these Image Filesystem
   520  Changeset tar archives.
   521  
   522  ## Combined Image JSON + Filesystem Changeset Format
   523  
   524  There is also a format for a single archive which contains complete information
   525  about an image, including:
   526  
   527   - repository names/tags
   528   - image configuration JSON file
   529   - all tar archives of each layer filesystem changesets
   530  
   531  For example, here's what the full archive of `library/busybox` is (displayed in
   532  `tree` format):
   533  
   534  ```
   535  .
   536  ├── 47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json
   537  ├── 5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a
   538  │   ├── VERSION
   539  │   ├── json
   540  │   └── layer.tar
   541  ├── a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198
   542  │   ├── VERSION
   543  │   ├── json
   544  │   └── layer.tar
   545  ├── manifest.json
   546  └── repositories
   547  ```
   548  
   549  There is a directory for each layer in the image. Each directory is named with
   550  a 64 character hex name that is deterministically generated from the layer
   551  information. These names are not necessarily layer DiffIDs or ChainIDs. Each of
   552  these directories contains 3 files:
   553  
   554   * `VERSION` - The schema version of the `json` file
   555   * `json` - The legacy JSON metadata for an image layer. In this version of
   556      the image specification, layers don't have JSON metadata, but in
   557      [version 1](v1.md), they did. A file is created for each layer in the
   558      v1 format for backward compatibility.
   559   * `layer.tar` - The Tar archive of the filesystem changeset for an image
   560     layer.
   561  
   562  Note that this directory layout is only important for backward compatibility.
   563  Current implementations use the paths specified in `manifest.json`.
   564  
   565  The content of the `VERSION` files is simply the semantic version of the JSON
   566  metadata schema:
   567  
   568  ```
   569  1.0
   570  ```
   571  
   572  The `repositories` file is another JSON file which describes names/tags:
   573  
   574  ```
   575  {  
   576      "busybox":{  
   577          "latest":"5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a"
   578      }
   579  }
   580  ```
   581  
   582  Every key in this object is the name of a repository, and maps to a collection
   583  of tag suffixes. Each tag maps to the ID of the image represented by that tag.
   584  This file is only used for backwards compatibility. Current implementations use
   585  the `manifest.json` file instead.
   586  
   587  The `manifest.json` file provides the image JSON for the top-level image, and
   588  optionally for parent images that this image was derived from. It consists of
   589  an array of metadata entries:
   590  
   591  ```
   592  [
   593    {
   594      "Config": "47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json",
   595      "RepoTags": ["busybox:latest"],
   596      "Layers": [
   597        "a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198/layer.tar",
   598        "5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a/layer.tar"
   599      ]
   600    }
   601  ]
   602  ```
   603  
   604  There is an entry in the array for each image.
   605  
   606  The `Config` field references another file in the tar which includes the image
   607  JSON for this image.
   608  
   609  The `RepoTags` field lists references pointing to this image.
   610  
   611  The `Layers` field points to the filesystem changeset tars.
   612  
   613  An optional `Parent` field references the imageID of the parent image. This
   614  parent must be part of the same `manifest.json` file.
   615  
   616  This file shouldn't be confused with the distribution manifest, used to push
   617  and pull images.
   618  
   619  Generally, implementations that support this version of the spec will use
   620  the `manifest.json` file if available, and older implementations will use the
   621  legacy `*/json` files and `repositories`.