Skip to content

Commit 2273702

Browse files
vbattsvbatts
committed
Merge pull request #12 from vbatts/begin_import_adjustments
Begin adjustments on the imported specs
2 parents a6eff3e + f7ffdbd commit 2273702

File tree

2 files changed

+205
-340
lines changed

2 files changed

+205
-340
lines changed

‎manifest.md‎

Lines changed: 108 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -4,124 +4,101 @@ draft = true
44
+++
55
<![end-metadata]-->
66

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)
7+
# Image Manifest
148

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.
9+
There are three main goals of the Image Manifest Specification.
10+
The first goal is content-addressable images, by supporting an image model where the image's configuration can be hashed to generate a unique ID for the image and its components.
11+
The second goal is to allow multi-architecture images, through a "fat manifest" which references image manifests for platform-specific versions of an image.
12+
The third goal is to be translatable to the [OpenContainers/runtime-spec](https://github.com/opencontainers/runtime-spec)
2113

2214
# Media Types
2315

24-
The following media types are used by the manifest formats described here, and
25-
the resources they reference:
16+
The following media types are used by the manifest formats described here, and the resources they reference:
2617

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
18+
- `application/vnd.oci.image.manifest.list.v1+json`: Manifest list, aka "fat manifest"
19+
- `application/vnd.oci.image.manifest.v1+json`: Image manifest format
20+
- `application/vnd.oci.image.rootfs.tar.gzip`: "Layer", as a gzipped tar archive
21+
- `application/vnd.oci.image.serialization.v1+json`: Container config JSON
3222

3323
## Manifest List
3424

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.
25+
The manifest list is the "fat manifest" which points to specific image manifests for one or more platforms.
26+
While the use of a manifest list is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.
27+
A client will distinguish a manifest list from an image manifest based on the Content-Type returned in the HTTP response.
3928

4029
## *Manifest List* Field Descriptions
4130

4231
- **`schemaVersion`** *int*
43-
44-
This field specifies the image manifest schema version as an integer. This
45-
schema uses the version `2`.
32+
33+
This REQUIRED property specifies the image manifest schema version.
34+
This schema uses the version `2`.
4635

4736
- **`mediaType`** *string*
4837

49-
The MIME type of the manifest list. This should be set to
50-
`application/vnd.docker.distribution.manifest.list.v2+json`.
38+
This REQUIRED property contains the MIME type of the manifest list.
39+
For this version of the specification, this MUST be set to `application/vnd.oci.image.manifest.list.v1+json`.
5140

5241
- **`manifests`** *array*
5342

54-
The manifests field contains a list of manifests for specific platforms.
43+
This REQUIRED property contains a list of manifests for specific platforms.
44+
While the property MUST be present, the size of the array MAY be zero.
5545

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*
46+
Fields of each object in the manifests list are:
47+
48+
- **`mediaType`** *string*
7349

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).
50+
This REQUIRED property contains the MIME type of the referenced object.
51+
(i.e. `application/vnd.oci.image.manifest.v1+json`)
7652

77-
- **`platform`** *object*
53+
- **`size`** *int*
7854

79-
The platform object describes the platform which the image in the
80-
manifest runs on. A full list of valid operating system and architecture
81-
values are listed in the [Go language documentation for `$GOOS` and
82-
`$GOARCH`](https://golang.org/doc/install/source#environment)
55+
This REQUIRED property specifies the size in bytes of the object.
56+
This field exists so that a client will have an expected size for the content before validating.
57+
If the length of the retrieved content does not match the specified length, the content should not be trusted.
8358

84-
- **`architecture`** *string*
59+
- **`digest`** *string*
8560

86-
The architecture field specifies the CPU architecture, for example
87-
`amd64` or `ppc64le`.
61+
The digest of the content, as defined by the [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
8862

89-
- **`os`** *string*
63+
- **`platform`** *object*
9064

91-
The os field specifies the operating system, for example
92-
`linux` or `windows`.
65+
This REQUIRED property describes the platform which the image in the manifest runs on.
66+
A full list of valid operating system and architecture values are listed in the [Go language documentation for `$GOOS` and `$GOARCH`](https://golang.org/doc/install/source#environment)
9367

94-
- **`os.version`** *string*
68+
- **`architecture`** *string*
9569

96-
The optional os.version field specifies the operating system version,
97-
for example `10.0.10586`.
70+
This REQUIRED property specified the CPU architecture, for example `amd64` or `ppc64le`.
9871

99-
- **`os.features`** *array*
72+
- **`os`** *string*
10073

101-
The optional os.features field specifies an array of strings,
102-
each listing a required OS feature (for example on Windows
103-
`win32k`).
74+
This REQUIRED property specifies the operating system, for example `linux` or `windows`.
10475

105-
- **`variant`** *string*
76+
- **`os.version`** *string*
10677

107-
The optional variant field specifies a variant of the CPU, for
108-
example `armv6l` to specify a particular CPU variant of the ARM CPU.
78+
This optional property specifies the operating system version, for example `10.0.10586`.
10979

110-
- **`features`** *array*
80+
- **`os.features`** *array*
11181

112-
The optional features field specifies an array of strings, each
113-
listing a required CPU feature (for example `sse4` or `aes`).
82+
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature (for example on Windows `win32k`).
83+
84+
- **`variant`** *string*
85+
86+
This OPTIONAL property specifies the variant of the CPU, for example `armv6l` to specify a particular CPU variant of the ARM CPU.
87+
88+
- **`features`** *array*
89+
90+
This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature (for example `sse4` or `aes`).
11491

11592
## Example Manifest List
11693

11794
*Example showing a simple manifest list pointing to image manifests for two platforms:*
11895
```json
11996
{
12097
"schemaVersion": 2,
121-
"mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
98+
"mediaType": "application/vnd.oci.image.manifest.list.v1+json",
12299
"manifests": [
123100
{
124-
"mediaType": "application/vnd.docker.image.manifest.v2+json",
101+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
125102
"size": 7143,
126103
"digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
127104
"platform": {
@@ -130,7 +107,7 @@ image manifest based on the Content-Type returned in the HTTP response.
130107
}
131108
},
132109
{
133-
"mediaType": "application/vnd.docker.image.manifest.v2+json",
110+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
134111
"size": 7682,
135112
"digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
136113
"platform": {
@@ -147,96 +124,89 @@ image manifest based on the Content-Type returned in the HTTP response.
147124

148125
# Image Manifest
149126

150-
The image manifest provides a configuration and a set of layers for a container
151-
image. It's the direct replacement for the schema-1 manifest.
127+
The image manifest provides a configuration and a set of layers for a container image.
152128

153129
## *Image Manifest* Field Descriptions
154130

155131
- **`schemaVersion`** *int*
156-
157-
This field specifies the image manifest schema version as an integer. This
158-
schema uses version `2`.
132+
133+
This REQUIRED property specifies the image manifest schema version.
134+
This schema uses version `2`.
159135

160136
- **`mediaType`** *string*
161137

162-
The MIME type of the manifest. This should be set to
163-
`application/vnd.docker.distribution.manifest.v2+json`.
138+
This REQUIRED property contains the MIME type of the image manifest.
139+
For this version of the specification, this MUST be set to `application/vnd.oci.image.manifest.v1+json`.
164140

165141
- **`config`** *object*
166142

167-
The config field references a configuration object for a container, by
168-
digest. This configuration item is a JSON blob that the runtime uses
169-
to set up the container. This new schema uses a tweaked version
170-
of this configuration to allow image content-addressability on the
171-
daemon side.
143+
The config field references a configuration object for a container, by digest.
144+
This configuration item is a JSON blob that the runtime uses to set up the container.
145+
This new schema uses a tweaked version of this configuration to allow image content-addressability on the daemon side.
172146

173147
Fields of a config object are:
174-
148+
175149
- **`mediaType`** *string*
176-
177-
The MIME type of the referenced object. This should generally be
178-
`application/vnd.docker.container.image.v1+json`.
179-
150+
151+
This REQUIRED property contains the MIME type of the referenced object.
152+
(i.e. `application/vnd.oci.image.serialization.v1+json`)
153+
180154
- **`size`** *int*
181-
182-
The size in bytes of the object. This field exists so that a client
183-
will have an expected size for the content before validating. If the
184-
length of the retrieved content does not match the specified length,
185-
the content should not be trusted.
186-
155+
156+
This REQUIRED property specifies the size in bytes of the object.
157+
This field exists so that a client will have an expected size for the content before validating.
158+
If the length of the retrieved content does not match the specified length, the content should not be trusted.
159+
187160
- **`digest`** *string*
188161

189-
The digest of the content, as defined by the
190-
[Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
162+
The digest of the content, as defined by the [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
191163

192164
- **`layers`** *array*
193165

194166
The layer list is ordered starting from the base image (opposite order of schema1).
195167

196168
Fields of an item in the layers list are:
197-
169+
198170
- **`mediaType`** *string*
199-
200-
The MIME type of the referenced object. This should
201-
generally be `application/vnd.docker.image.rootfs.diff.tar.gzip`.
202-
171+
172+
This REQUIRED property contains the MIME type of the referenced object.
173+
(i.e. `application/vnd.oci.image.rootfs.tar.gzip`)
174+
203175
- **`size`** *int*
204-
205-
The size in bytes of the object. This field exists so that a client
206-
will have an expected size for the content before validating. If the
207-
length of the retrieved content does not match the specified length,
208-
the content should not be trusted.
209-
176+
177+
This REQUIRED property specifies the size in bytes of the object.
178+
This field exists so that a client will have an expected size for the content before validating.
179+
If the length of the retrieved content does not match the specified length, the content should not be trusted.
180+
210181
- **`digest`** *string*
211182

212-
The digest of the content, as defined by the
213-
[Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
183+
The digest of the content, as defined by the [Registry V2 HTTP API Specificiation](https://docs.docker.com/registry/spec/api/#digest-parameter).
214184

215185
## Example Image Manifest
216186

217187
*Example showing an image manifest:*
218188
```json
219189
{
220190
"schemaVersion": 2,
221-
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
191+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
222192
"config": {
223-
"mediaType": "application/vnd.docker.container.image.v1+json",
193+
"mediaType": "application/vnd.oci.image.serialization.v1+json",
224194
"size": 7023,
225195
"digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
226196
},
227197
"layers": [
228198
{
229-
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
199+
"mediaType": "application/vnd.oci.image.rootfs.tar.gzip",
230200
"size": 32654,
231201
"digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f"
232202
},
233203
{
234-
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
204+
"mediaType": "application/vnd.oci.image.rootfs.tar.gzip",
235205
"size": 16724,
236206
"digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b"
237207
},
238208
{
239-
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
209+
"mediaType": "application/vnd.oci.image.rootfs.tar.gzip",
240210
"size": 73109,
241211
"digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736"
242212
}
@@ -246,39 +216,22 @@ image. It's the direct replacement for the schema-1 manifest.
246216

247217
# Backward compatibility
248218

249-
The registry will continue to accept uploads of manifests in both the old and
250-
new formats.
251-
252-
When pushing images, clients which support the new manifest format should first
253-
construct a manifest in the new format. If uploading this manifest fails,
254-
presumably because the registry only supports the old format, the client may
255-
fall back to uploading a manifest in the old format.
256-
257-
When pulling images, clients indicate support for this new version of the
258-
manifest format by sending the
259-
`application/vnd.docker.distribution.manifest.v2+json` and
260-
`application/vnd.docker.distribution.manifest.list.v2+json` media types in an
261-
`Accept` header when making a request to the `manifests` endpoint. Updated
262-
clients should check the `Content-Type` header to see whether the manifest
263-
returned from the endpoint is in the old format, or is an image manifest or
264-
manifest list in the new format.
265-
266-
If the manifest being requested uses the new format, and the appropriate media
267-
type is not present in an `Accept` header, the registry will assume that the
268-
client cannot handle the manifest as-is, and rewrite it on the fly into the old
269-
format. If the object that would otherwise be returned is a manifest list, the
270-
registry will look up the appropriate manifest for the amd64 platform and
271-
linux OS, rewrite that manifest into the old format if necessary, and return
272-
the result to the client. If no suitable manifest is found in the manifest
273-
list, the registry will return a 404 error.
274-
275-
One of the challenges in rewriting manifests to the old format is that the old
276-
format involves an image configuration for each layer in the manifest, but the
277-
new format only provides one image configuration. To work around this, the
278-
registry will create synthetic image configurations for all layers except the
279-
top layer. These image configurations will not result in runnable images on
280-
their own, but only serve to fill in the parent chain in a compatible way.
281-
The IDs in these synthetic configurations will be derived from hashes of their
282-
respective blobs. The registry will create these configurations and their IDs
283-
using the same scheme as Docker 1.10 when it creates a legacy manifest to push
284-
to a registry which doesn't support the new format.
219+
The registry will continue to accept uploads of manifests in both the old and new formats.
220+
221+
When pushing images, clients which support the new manifest format should first construct a manifest in the new format.
222+
If uploading this manifest fails, presumably because the registry only supports the old format, the client may fall back to uploading a manifest in the old format.
223+
224+
When pulling images, clients indicate support for this new version of the manifest format by sending the
225+
`application/vnd.oci.image.manifest.v1+json` and
226+
`application/vnd.oci.image.manifest.list.v1+json` media types in an `Accept` header when making a request to the `manifests` endpoint.
227+
Updated clients should check the `Content-Type` header to see whether the manifest returned from the endpoint is in the old format, or is an image manifest or manifest list in the new format.
228+
229+
If the manifest being requested uses the new format, and the appropriate media type is not present in an `Accept` header, the registry will assume that the client cannot handle the manifest as-is, and rewrite it on the fly into the old format.
230+
If the object that would otherwise be returned is a manifest list, the registry will look up the appropriate manifest for the amd64 platform and linux OS, rewrite that manifest into the old format if necessary, and return the result to the client.
231+
If no suitable manifest is found in the manifest list, the registry will return a 404 error.
232+
233+
One of the challenges in rewriting manifests to the old format is that the old format involves an image configuration for each layer in the manifest, but the new format only provides one image configuration.
234+
To work around this, the registry will create synthetic image configurations for all layers except the top layer.
235+
These image configurations will not result in runnable images on their own, but only serve to fill in the parent chain in a compatible way.
236+
The IDs in these synthetic configurations will be derived from hashes of their respective blobs.
237+
The registry will create these configurations and their IDs using the same scheme as Docker 1.10 when it creates a legacy manifest to push to a registry which doesn't support the new format.

0 commit comments

Comments
 (0)