Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Replace vendor-specific examples and links #50

Merged
merged 2 commits into from
Mar 13, 2019
+85 −70
Merged

Replace vendor-specific examples and links #50

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
55292ea
*:Replace vendor-specific examples.
bsatlas Jan 31, 2019
d93cfa5
*: Add OCI links to spec.
bsatlas Feb 13, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 85 additions & 70 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ For detail on individual endpoints, please see the [_Detail_](#detail) section.

Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses, in a json response body.
One or more errors will be returned in the following format:

```JSON
{
"errors:" [{
"code": <error identifier>,
Expand All @@ -183,6 +183,7 @@ One or more errors will be returned in the following format:
...
]
}
```

The `code` field will be a unique identifier, all caps with underscores by convention.
The `message` field will be a human readable string.
Expand Down Expand Up @@ -285,16 +286,7 @@ An "image" is a combination of a JSON manifest and individual layer files.
The process of pulling an image centers around retrieving these two components.

The first step in pulling an image is to retrieve the manifest.
For reference, the relevant manifest fields for the registry are the following:

| field | description |
|-----------|------------------------------------------------|
| name | The name of the image. |
| tag | The tag for this version of the image. |
| fsLayers | A list of layer descriptors (including digest) |
| signature | A JWS used to verify the manifest content |

For more information about the manifest format, please see [moby/moby#8093](https://github.com/moby/moby/issues/8093).
For details on manifest formats and their content types, refer to the OCI Image Specification's [manifest property description](https://github.com/opencontainers/image-spec/blob/master/manifest.md#image-manifest-property-descriptions).

When the manifest is in hand, the client MUST verify the signature to ensure the names and layers are valid.
Once confirmed, the client will then use the digests to download the individual layers.
Expand All @@ -312,26 +304,31 @@ The `name` and `reference` parameter identify the image and are REQUIRED.
The reference MAY include a tag or digest.

The client SHOULD include an Accept header indicating which manifest content types it supports.
For more details on the manifest formats and their content types, see [manifest-v2-1.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-1.md) and [manifest-v2-2.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md).
In a successful response, the Content-Type header will indicate which manifest type is being returned.

A `404 Not Found` response will be returned if the image is unknown to the registry.
If the image exists and the response is successful, the image manifest will be returned, with the following format (see [moby/moby#8093](https://github.com/moby/moby/issues/8093) for details):
If the image exists and the response is successful, the image manifest will be returned:

```json
{
"name": <name>,
"tag": <tag>,
"fsLayers": [
{
"blobSum": <digest>
},
...
]
],
"history": <v1 images>,
"signature": <JWS>
}
{
bsatlas marked this conversation as resolved.
Show resolved Hide resolved
"annotations": {
"com.example.key1": "value1",
"com.example.key2": "value2"
},
"config": {
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.config.v1+json",
"size": 452
},
"layers": [
{
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
"size": 78343
}
],
"schemaVersion": 2
}
```

The client SHOULD verify the returned manifest signature for authenticity before fetching layers.
Expand Down Expand Up @@ -657,23 +654,28 @@ Once all of the layers for an image are uploaded, the client can upload the imag
An image can be pushed using the following request format:

```HTTP
PUT /v2/<name>/manifests/<reference>
Content-Type: <manifest media type>
PUT /v2/<name>/manifests/<reference>
Content-Type: <manifest media type>

{
"name": <name>,
"tag": <tag>,
"fsLayers": [
{
"blobSum": <digest>
},
...
]
],
"history": <v1 images>,
"signature": <JWS>,
...
}
{
"annotations": {
"com.example.key1": "value1",
"com.example.key2": "value2"
},
"config": {
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.config.v1+json",
"size": 452
},
"layers": [
{
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
"size": 78343
}
],
"schemaVersion": 2
}
```

The `name` and `reference` fields of the response body MUST match those specified in the URL.
Expand All @@ -687,7 +689,7 @@ If one or more layers are unknown to the registry, `BLOB_UNKNOWN` errors are ret
The `detail` field of the error response will have a `digest` field identifying the missing blob.
An error is returned for each unknown blob.
The response format is as follows:

```JSON
{
"errors:" [{
"code": "BLOB_UNKNOWN",
Expand All @@ -699,6 +701,7 @@ The response format is as follows:
...
]
}
```

### Listing Repositories

Expand Down Expand Up @@ -820,16 +823,16 @@ The tags for an image repository can be retrieved with the following request:
The response will be in the following format:

```HTTP
200 OK
Content-Type: application/json
200 OK
Content-Type: application/json

{
"name": <name>,
"tags": [
<tag>,
...
]
}
{
"name": <name>,
"tags": [
<tag>,
...
]
}
```

For repositories with a large number of tags, this response MAY be quite large.
Expand Down Expand Up @@ -1450,17 +1453,23 @@ Docker-Content-Digest: <digest>
Content-Type: <media type of manifest>

{
"name": <name>,
"tag": <tag>,
"fsLayers": [
"annotations": {
bsatlas marked this conversation as resolved.
Show resolved Hide resolved
"com.example.key1": "value1",
"com.example.key2": "value2"
},
"config": {
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.config.v1+json",
"size": 452
},
"layers": [
{
"blobSum": "<digest>"
},
...
]
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
"size": 78343
}
],
"history": <v1 images>,
"signature": <JWS>
"schemaVersion": 2
}
```

Expand Down Expand Up @@ -1645,17 +1654,23 @@ Authorization: <scheme> <token>
Content-Type: <media type of manifest>

{
"name": <name>,
"tag": <tag>,
"fsLayers": [
"annotations": {
"com.example.key1": "value1",
"com.example.key2": "value2"
},
"config": {
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.config.v1+json",
"size": 452
},
"layers": [
{
"blobSum": "<digest>"
},
...
]
"digest": "sha256:6f4e69a5ff18d92e7315e3ee31c62165ebf25bfa05cad05c0d09d8f412dae401",
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
"size": 78343
}
],
"history": <v1 images>,
"signature": <JWS>
"schemaVersion": 2
}
```

Expand Down