github.com/mika/distribution@v2.2.2-0.20160108133430-a75790e3d8e0+incompatible/docs/spec/manifest-v2-2.md (about)

     1  <!--[metadata]>
     2  +++
     3  draft = true
     4  +++
     5  <![end-metadata]-->
     6  
     7  # Image Manifest Version 2, Schema 2
     8  
     9  This document outlines the format of of the V2 image manifest, schema version 2.
    10  The original (and provisional) image manifest for V2 (schema 1), was introduced
    11  in the Docker daemon in the [v1.3.0
    12  release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453)
    13  and is specified in the [schema 1 manifest definition](./manifest-v2-1.md)
    14  
    15  This second schema version has two primary goals. The first is to allow
    16  multi-architecture images, through a "fat manifest" which references image
    17  manifests for platform-specific versions of an image. The second is to
    18  move the Docker engine towards content-addressable images, by supporting
    19  an image model where the image's configuration can be hashed to generate
    20  an ID for the image.
    21  
    22  # Media Types
    23  
    24  The following media types are used by the manifest formats described here, and
    25  the resources they reference:
    26  
    27  - `application/vnd.docker.distribution.manifest.v1+json`: schema1 (existing manifest format)
    28  - `application/vnd.docker.distribution.manifest.v2+json`: New image manifest format (schemaVersion = 2)
    29  - `application/vnd.docker.distribution.manifest.list.v2+json`: Manifest list, aka "fat manifest"
    30  - `application/vnd.docker.image.rootfs.diff.tar.gzip`: "Layer", as a gzipped tar
    31  - `application/vnd.docker.container.image.v1+json`: Container config JSON
    32  
    33  ## Manifest List
    34  
    35  The manifest list is the "fat manifest" which points to specific image manifests
    36  for one or more platforms. Its use is optional, and relatively few images will
    37  use one of these manifests. A client will distinguish a manifest list from an
    38  image manifest based on the Content-Type returned in the HTTP response.
    39  
    40  ## *Manifest List* Field Descriptions
    41  
    42  - **`schemaVersion`** *int*
    43  	
    44    This field specifies the image manifest schema version as an integer. This
    45    schema uses the version `2`.
    46  
    47  - **`mediaType`** *string*
    48  
    49      The MIME type of the manifest list. This should be set to
    50      `application/vnd.docker.distribution.manifest.list.v2+json`.
    51  
    52  - **`manifests`** *array*
    53  
    54      The manifests field contains a list of manifests for specific platforms.
    55  
    56      Fields of a object in the manifests list are:
    57      
    58      - **`mediaType`** *string*
    59      
    60          The MIME type of the referenced object. This will generally be
    61          `application/vnd.docker.image.manifest.v2+json`, but it could also
    62          be `application/vnd.docker.image.manifest.v1+json` if the manifest
    63          list references a legacy schema-1 manifest.
    64      
    65      - **`size`** *int*
    66      
    67          The size in bytes of the object. This field exists so that a client
    68          will have an expected size for the content before validating. If the
    69          length of the retrieved content does not match the specified length,
    70          the content should not be trusted.
    71      
    72      - **`digest`** *string*
    73  
    74          The digest of the content, as defined by the
    75          [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
    76  
    77      - **`platform`** *object*
    78  
    79          The platform object describes the platform which the image in the
    80          manifest runs on.
    81  
    82          - **`architecture`** *string*
    83  
    84              The architecture field specifies the CPU architecture, for example
    85              `amd64` or `ppc64`.
    86  
    87          - **`os`** *string*
    88  
    89              The os field specifies the operating system, for example
    90              `linux` or `windows`.
    91  
    92          - **`variant`** *string*
    93  
    94              The optional variant field specifies a variant of the CPU, for
    95              example `ppc64le` to specify a little-endian version of a PowerPC
    96              CPU.
    97  
    98          - **`features`** *array*
    99  
   100              The optional features field specifies an array of strings, each
   101              listing a required CPU feature (for example `sse4` or `aes`).
   102  
   103  ## Example Manifest List
   104  
   105  *Example showing a simple manifest list pointing to image manifests for two platforms:*
   106  ```json
   107  {
   108    "schemaVersion": 2,
   109    "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   110    "manifests": [
   111      {
   112        "mediaType": "application/vnd.docker.image.manifest.v2+json",
   113        "size": 7143,
   114        "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
   115        "platform": {
   116          "architecture": "ppc64",
   117          "os": "linux",
   118          "variant": "ppc64le",
   119        }
   120      },
   121      {
   122        "mediaType": "application/vnd.docker.image.manifest.v2+json",
   123        "size": 7682,
   124        "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
   125        "platform": {
   126          "architecture": "x86-64",
   127          "os": "linux",
   128          "features": [
   129            "sse4"
   130          ]
   131        }
   132      }
   133    ]
   134  }
   135  ```
   136  
   137  # Image Manifest
   138  
   139  The image manifest provides a configuration and a set of layers for a container
   140  image. It's the direct replacement for the schema-1 manifest.
   141  
   142  ## *Image Manifest* Field Descriptions
   143  
   144  - **`schemaVersion`** *int*
   145  	
   146    This field specifies the image manifest schema version as an integer. This
   147    schema uses version `2`.
   148  
   149  - **`mediaType`** *string*
   150  
   151      The MIME type of the manifest. This should be set to
   152      `application/vnd.docker.distribution.manifest.v2+json`.
   153  
   154  - **`config`** *object*
   155  
   156      The config field references a configuration object for a container, by
   157      digest. This configuration item is a JSON blob that the runtime uses
   158      to set up the container. This new schema uses a tweaked version
   159      of this configuration to allow image content-addressability on the
   160      daemon side.
   161  
   162      Fields of a config object are:
   163      
   164      - **`mediaType`** *string*
   165      
   166          The MIME type of the referenced object. This should generally be
   167          `application/vnd.docker.container.image.v1+json`.
   168      
   169      - **`size`** *int*
   170      
   171          The size in bytes of the object. This field exists so that a client
   172          will have an expected size for the content before validating. If the
   173          length of the retrieved content does not match the specified length,
   174          the content should not be trusted.
   175      
   176      - **`digest`** *string*
   177  
   178          The digest of the content, as defined by the
   179          [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
   180  
   181  - **`layers`** *array*
   182  
   183      The layer list is ordered starting from the base image (opposite order of schema1).
   184  
   185      Fields of an item in the layers list are:
   186      
   187      - **`mediaType`** *string*
   188      
   189          The MIME type of the referenced object. This should
   190          generally be `application/vnd.docker.image.rootfs.diff.tar.gzip`.
   191      
   192      - **`size`** *int*
   193      
   194          The size in bytes of the object. This field exists so that a client
   195          will have an expected size for the content before validating. If the
   196          length of the retrieved content does not match the specified length,
   197          the content should not be trusted.
   198      
   199      - **`digest`** *string*
   200  
   201          The digest of the content, as defined by the
   202          [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
   203  
   204  ## Example Image Manifest
   205  
   206  *Example showing an image manifest:*
   207  ```json
   208  {
   209      "schemaVersion": 2,
   210      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
   211      "config": {
   212          "mediaType": "application/vnd.docker.container.image.v1+json",
   213          "size": 7023,
   214          "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
   215      },
   216      "layers": [
   217          {
   218              "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
   219              "size": 32654,
   220              "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f"
   221          },
   222          {
   223              "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
   224              "size": 16724,
   225              "digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b"
   226          },
   227          {
   228              "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
   229              "size": 73109,
   230              "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736"
   231          }
   232      ],
   233  }
   234  ```
   235  
   236  # Backward compatibility
   237  
   238  The registry will continue to accept uploads of manifests in both the old and
   239  new formats.
   240  
   241  When pushing images, clients which support the new manifest format should first
   242  construct a manifest in the new format. If uploading this manifest fails,
   243  presumably because the registry only supports the old format, the client may
   244  fall back to uploading a manifest in the old format.
   245  
   246  When pulling images, clients indicate support for this new version of the
   247  manifest format by sending the
   248  `application/vnd.docker.distribution.manifest.v2+json` and
   249  `application/vnd.docker.distribution.manifest.list.v2+json` media types in an
   250  `Accept` header when making a request to the `manifests` endpoint. Updated
   251  clients should check the `Content-Type` header to see whether the manifest
   252  returned from the endpoint is in the old format, or is an image manifest or
   253  manifest list in the new format.
   254  
   255  If the manifest being requested uses the new format, and the appropriate media
   256  type is not present in an `Accept` header, the registry will assume that the
   257  client cannot handle the manifest as-is, and rewrite it on the fly into the old
   258  format. If the object that would otherwise be returned is a manifest list, the
   259  registry will look up the appropriate manifest for the x86-64 platform and
   260  linux OS, rewrite that manifest into the old format if necessary, and return
   261  the result to the client. If no suitable manifest is found in the manifest
   262  list, the registry will return a 404 error.
   263  
   264  One of the challenges in rewriting manifests to the old format is that the old
   265  format involves an image configuration for each layer in the manifest, but the
   266  new format only provides one image configuration. To work around this, the
   267  registry will create synthetic image configurations for all layers except the
   268  top layer. These image configurations will not result in runnable images on
   269  their own, but only serve to fill in the parent chain in a compatible way.
   270  The IDs in these synthetic configurations will be derived from hashes of their
   271  respective blobs. The registry will create these configurations and their IDs
   272  using the same scheme as Docker 1.10 when it creates a legacy manifest to push
   273  to a registry which doesn't support the new format.