910 lines
33 KiB
Cheetah
910 lines
33 KiB
Cheetah
<!--[metadata]>
|
|
+++
|
|
title = "Docker Registry HTTP API V2"
|
|
description = "This is a specification for the API."
|
|
keywords = ["registry, service, driver, images, storage, api"]
|
|
[menu.main]
|
|
parent="smn_registry_ref"
|
|
+++
|
|
<![end-metadata]-->
|
|
|
|
# Docker Registry HTTP API V2
|
|
|
|
## Introduction
|
|
|
|
The _Docker Registry HTTP API_ is the protocol to facilitate distribution of
|
|
images to the docker engine. It interacts with instances of the docker
|
|
registry, which is a service to manage information about docker images and
|
|
enable their distribution. The specification covers the operation of version 2
|
|
of this API, known as _Docker Registry HTTP API V2_.
|
|
|
|
While the V1 registry protocol is usable, there are several problems with the
|
|
architecture that have led to this new version. The main driver of this
|
|
specification these changes to the docker the image format, covered in
|
|
docker/docker#8093. The new, self-contained image manifest simplifies image
|
|
definition and improves security. This specification will build on that work,
|
|
leveraging new properties of the manifest format to improve performance,
|
|
reduce bandwidth usage and decrease the likelihood of backend corruption.
|
|
|
|
For relevant details and history leading up to this specification, please see
|
|
the following issues:
|
|
|
|
- [docker/docker#8093](https://github.com/docker/docker/issues/8093)
|
|
- [docker/docker#9015](https://github.com/docker/docker/issues/9015)
|
|
- [docker/docker-registry#612](https://github.com/docker/docker-registry/issues/612)
|
|
|
|
### Scope
|
|
|
|
This specification covers the URL layout and protocols of the interaction
|
|
between docker registry and docker core. This will affect the docker core
|
|
registry API and the rewrite of docker-registry. Docker registry
|
|
implementations may implement other API endpoints, but they are not covered by
|
|
this specification.
|
|
|
|
This includes the following features:
|
|
|
|
- Namespace-oriented URI Layout
|
|
- PUSH/PULL registry server for V2 image manifest format
|
|
- Resumable layer PUSH support
|
|
- V2 Client library implementation
|
|
|
|
While authentication and authorization support will influence this
|
|
specification, details of the protocol will be left to a future specification.
|
|
Relevant header definitions and error codes are present to provide an
|
|
indication of what a client may encounter.
|
|
|
|
#### Future
|
|
|
|
There are features that have been discussed during the process of cutting this
|
|
specification. The following is an incomplete list:
|
|
|
|
- Immutable image references
|
|
- Multiple architecture support
|
|
- Migration from v2compatibility representation
|
|
|
|
These may represent features that are either out of the scope of this
|
|
specification, the purview of another specification or have been deferred to a
|
|
future version.
|
|
|
|
### Use Cases
|
|
|
|
For the most part, the use cases of the former registry API apply to the new
|
|
version. Differentiating use cases are covered below.
|
|
|
|
#### Image Verification
|
|
|
|
A docker engine instance would like to run verified image named
|
|
"library/ubuntu", with the tag "latest". The engine contacts the registry,
|
|
requesting the manifest for "library/ubuntu:latest". An untrusted registry
|
|
returns a manifest. Before proceeding to download the individual layers, the
|
|
engine verifies the manifest's signature, ensuring that the content was
|
|
produced from a trusted source and no tampering has occured. After each layer
|
|
is downloaded, the engine verifies the digest of the layer, ensuring that the
|
|
content matches that specified by the manifest.
|
|
|
|
#### Resumable Push
|
|
|
|
Company X's build servers lose connectivity to docker registry before
|
|
completing an image layer transfer. After connectivity returns, the build
|
|
server attempts to re-upload the image. The registry notifies the build server
|
|
that the upload has already been partially attempted. The build server
|
|
responds by only sending the remaining data to complete the image file.
|
|
|
|
#### Resumable Pull
|
|
|
|
Company X is having more connectivity problems but this time in their
|
|
deployment datacenter. When downloading an image, the connection is
|
|
interrupted before completion. The client keeps the partial data and uses http
|
|
`Range` requests to avoid downloading repeated data.
|
|
|
|
#### Layer Upload De-duplication
|
|
|
|
Company Y's build system creates two identical docker layers from build
|
|
processes A and B. Build process A completes uploading the layer before B.
|
|
When process B attempts to upload the layer, the registry indicates that its
|
|
not necessary because the layer is already known.
|
|
|
|
If process A and B upload the same layer at the same time, both operations
|
|
will proceed and the first to complete will be stored in the registry (Note:
|
|
we may modify this to prevent dogpile with some locking mechanism).
|
|
|
|
### Changes
|
|
|
|
The V2 specification has been written to work as a living document, specifying
|
|
only what is certain and leaving what is not specified open or to future
|
|
changes. Only non-conflicting additions should be made to the API and accepted
|
|
changes should avoid preventing future changes from happening.
|
|
|
|
This section should be updated when changes are made to the specification,
|
|
indicating what is different. Optionally, we may start marking parts of the
|
|
specification to correspond with the versions enumerated here.
|
|
|
|
<dl>
|
|
<dt>2.0.3</dt>
|
|
<dd>
|
|
<li>Allow repository name components to be one character.</li>
|
|
<li>Clarified that single component names are allowed.</li>
|
|
</dd>
|
|
|
|
<dt>2.0.2</dt>
|
|
<dd>
|
|
<li>Added section covering digest format.</li>
|
|
<li>Added more clarification that manifest cannot be deleted by tag.</li>
|
|
</dd>
|
|
|
|
<dt>2.0.1</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>Added capability of doing streaming upload to PATCH blob upload.</li>
|
|
<li>Updated PUT blob upload to no longer take final chunk, now requires entire data or no data.</li>
|
|
<li>Removed `416 Requested Range Not Satisfiable` response status from PUT blob upload.</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>2.0.0</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>Added support for immutable manifest references in manifest endpoints.</li>
|
|
<li>Deleting a manifest by tag has been deprecated.</li>
|
|
<li>Specified `Docker-Content-Digest` header for appropriate entities.</li>
|
|
<li>Added error code for unsupported operations.</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>2.0</dt>
|
|
<dd>
|
|
This is the baseline specification.
|
|
</dd>
|
|
</dl>
|
|
|
|
## Overview
|
|
|
|
This section covers client flows and details of the API endpoints. The URI
|
|
layout of the new API is structured to support a rich authentication and
|
|
authorization model by leveraging namespaces. All endpoints will be prefixed
|
|
by the API version and the repository name:
|
|
|
|
/v2/<name>/
|
|
|
|
For example, an API endpoint that will work with the `library/ubuntu`
|
|
repository, the URI prefix will be:
|
|
|
|
/v2/library/ubuntu/
|
|
|
|
This scheme provides rich access control over various operations and methods
|
|
using the URI prefix and http methods that can be controlled in variety of
|
|
ways.
|
|
|
|
Classically, repository names have always been two path components where each
|
|
path component is less than 30 characters. The V2 registry API does not
|
|
enforce this. The rules for a repository name are as follows:
|
|
|
|
1. A repository name is broken up into _path components_. A component of a
|
|
repository name must be at least one lowercase, alpha-numeric characters,
|
|
optionally separated by periods, dashes or underscores. More strictly, it
|
|
must match the regular expression `[a-z0-9]+(?:[._-][a-z0-9]+)*`.
|
|
2. If a repository name has two or more path components, they must be
|
|
separated by a forward slash ("/").
|
|
3. The total length of a repository name, including slashes, must be less the
|
|
256 characters.
|
|
|
|
These name requirements _only_ apply to the registry API and should accept a
|
|
superset of what is supported by other docker ecosystem components.
|
|
|
|
All endpoints should support aggressive http caching, compression and range
|
|
headers, where appropriate. The new API attempts to leverage HTTP semantics
|
|
where possible but may break from standards to implement targeted features.
|
|
|
|
For detail on individual endpoints, please see the [_Detail_](#detail)
|
|
section.
|
|
|
|
### Errors
|
|
|
|
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:
|
|
|
|
{
|
|
"errors:" [{
|
|
"code": <error identifier>,
|
|
"message": <message describing condition>,
|
|
"detail": <unstructured>
|
|
},
|
|
...
|
|
]
|
|
}
|
|
|
|
The `code` field will be a unique identifier, all caps with underscores by
|
|
convention. The `message` field will be a human readable string. The optional
|
|
`detail` field may contain arbitrary json data providing information the
|
|
client can use to resolve the issue.
|
|
|
|
While the client can take action on certain error codes, the registry may add
|
|
new error codes over time. All client implementations should treat unknown
|
|
error codes as `UNKNOWN`, allowing future error codes to be added without
|
|
breaking API compatibility. For the purposes of the specification error codes
|
|
will only be added and never removed.
|
|
|
|
For a complete account of all error codes, please see the _Detail_ section.
|
|
|
|
### API Version Check
|
|
|
|
A minimal endpoint, mounted at `/v2/` will provide version support information
|
|
based on its response statuses. The request format is as follows:
|
|
|
|
GET /v2/
|
|
|
|
If a `200 OK` response is returned, the registry implements the V2(.1)
|
|
registry API and the client may proceed safely with other V2 operations.
|
|
Optionally, the response may contain information about the supported paths in
|
|
the response body. The client should be prepared to ignore this data.
|
|
|
|
If a `401 Unauthorized` response is returned, the client should take action
|
|
based on the contents of the "WWW-Authenticate" header and try the endpoint
|
|
again. Depending on access control setup, the client may still have to
|
|
authenticate against different resources, even if this check succeeds.
|
|
|
|
If `404 Not Found` response status, or other unexpected status, is returned,
|
|
the client should proceed with the assumption that the registry does not
|
|
implement V2 of the API.
|
|
|
|
When a `200 OK` or `401 Unauthorized` response is returned, the
|
|
"Docker-Distribution-API-Version" header should be set to "registry/2.0".
|
|
Clients may require this header value to determine if the endpoint serves this
|
|
API. When this header is omitted, clients may fallback to an older API version.
|
|
|
|
### Content Digests
|
|
|
|
This API design is driven heavily by [content addressability](http://en.wikipedia.org/wiki/Content-addressable_storage).
|
|
The core of this design is the concept of a content addressable identifier. It
|
|
uniquely identifies content by taking a collision-resistent hash of the bytes.
|
|
Such an identifier can be independently calculated and verified by selection
|
|
of a common _algorithm_. If such an identifier can be communicated in a secure
|
|
manner, one can retrieve the content from an insecure source, calculate it
|
|
independently and be certain that the correct content was obtained. Put simply,
|
|
the identifier is a property of the content.
|
|
|
|
To disambiguate from other concepts, we call this identifier a _digest_. A
|
|
_digest_ is a serialized hash result, consisting of a _algorithm_ and _hex_
|
|
portion. The _algorithm_ identifies the methodology used to calculate the
|
|
digest. The _hex_ portion is the hex-encoded result of the hash.
|
|
|
|
We define a _digest_ string to match the following grammar:
|
|
|
|
digest := algorithm ":" hex
|
|
algorithm := /[A-Fa-f0-9_+.-]+/
|
|
hex := /[A-Fa-f0-9]+/
|
|
|
|
Some examples of _digests_ include the following:
|
|
|
|
digest | description |
|
|
----------------------------------------------------------------------------------|------------------------------------------------
|
|
sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b | Common sha256 based digest |
|
|
tarsum.v1+sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b | Tarsum digest, used for legacy layer digests. |
|
|
|
|
> __NOTE:__ While we show an example of using a `tarsum` digest, the security
|
|
> of tarsum has not been verified. It is recommended that most implementations
|
|
> use sha256 for interoperability.
|
|
|
|
While the _algorithm_ does allow one to implement a wide variety of
|
|
algorithms, compliant implementations should use sha256. Heavy processing of
|
|
input before calculating a hash is discouraged to avoid degrading the
|
|
uniqueness of the _digest_ but some canonicalization may be performed to
|
|
ensure consistent identifiers.
|
|
|
|
Let's use a simple example in pseudo-code to demonstrate a digest calculation:
|
|
|
|
```
|
|
let C = 'a small string'
|
|
let B = sha256(C)
|
|
let D = 'sha256:' + EncodeHex(B)
|
|
let ID(C) = D
|
|
```
|
|
|
|
Above, we have bytestring _C_ passed into a function, _SHA256_, that returns a
|
|
bytestring B, which is the hash of _C_. _D_ gets the algorithm concatenated
|
|
with the hex encoding of _B_. We then define the identifier of _C_ to _ID(C)_
|
|
as equal to _D_. A digest can be verified by independently calculating _D_ and
|
|
comparing it with identifier _ID(C)_
|
|
|
|
#### Digest Header
|
|
|
|
To provide verification of http content, any response may include a `Docker-
|
|
Content-Digest` header. This will include the digest of the target entity
|
|
returned in the response. For blobs, this is the entire blob content. For
|
|
manifests, this is the manifest body without the signature content, also known
|
|
as the JWS payload. Note that the commonly used canonicalization for digest
|
|
calculation may be dependent on the mediatype of the content, such as with
|
|
manifests.
|
|
|
|
The client may choose to ignore the header or may verify it to ensure content
|
|
integrity and transport security. This is most important when fetching by a
|
|
digest. To ensure security, the content should be verified against the digest
|
|
used to fetch the content. At times, the returned digest may differ from that
|
|
used to initiate a request. Such digests are considered to be from different
|
|
_domains_, meaning they have different values for _algorithm_. In such a case,
|
|
the client may choose to verify the digests in both domains or ignore the
|
|
server's digest. To maintain security, the client _must_ always verify the
|
|
content against the _digest_ used to fetch the content.
|
|
|
|
> __IMPORTANT:__ If a _digest_ is used to fetch content, the client should use
|
|
> the same digest used to fetch the content to verify it. The header `Docker-
|
|
> Content-Digest` should not be trusted over the "local" digest.
|
|
|
|
### Pulling An Image
|
|
|
|
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 tarsum) |
|
|
signature | A JWS used to verify the manifest content |
|
|
|
|
For more information about the manifest format, please see
|
|
[docker/docker#8093](https://github.com/docker/docker/issues/8093).
|
|
|
|
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
|
|
tarsums to download the individual layers. Layers are stored in as blobs in
|
|
the V2 registry API, keyed by their tarsum digest.
|
|
|
|
#### Pulling an Image Manifest
|
|
|
|
The image manifest can be fetched with the following url:
|
|
|
|
```
|
|
GET /v2/<name>/manifests/<reference>
|
|
```
|
|
|
|
The `name` and `reference` parameter identify the image and are required. The
|
|
reference may include a tag or digest.
|
|
|
|
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 docker/docker#8093
|
|
for details):
|
|
|
|
{
|
|
"name": <name>,
|
|
"tag": <tag>,
|
|
"fsLayers": [
|
|
{
|
|
"blobSum": <tarsum>
|
|
},
|
|
...
|
|
]
|
|
],
|
|
"history": <v1 images>,
|
|
"signature": <JWS>
|
|
}
|
|
|
|
The client should verify the returned manifest signature for authenticity
|
|
before fetching layers.
|
|
|
|
#### Pulling a Layer
|
|
|
|
Layers are stored in the blob portion of the registry, keyed by tarsum digest.
|
|
Pulling a layer is carried out by a standard http request. The URL is as
|
|
follows:
|
|
|
|
GET /v2/<name>/blobs/<tarsum>
|
|
|
|
Access to a layer will be gated by the `name` of the repository but is
|
|
identified uniquely in the registry by `tarsum`. The `tarsum` parameter is an
|
|
opaque field, to be interpreted by the tarsum library.
|
|
|
|
This endpoint may issue a 307 (302 for <HTTP 1.1) redirect to another service
|
|
for downloading the layer and clients should be prepared to handle redirects.
|
|
|
|
This endpoint should support aggressive HTTP caching for image layers. Support
|
|
for Etags, modification dates and other cache control headers should be
|
|
included. To allow for incremental downloads, `Range` requests should be
|
|
supported, as well.
|
|
|
|
### Pushing An Image
|
|
|
|
Pushing an image works in the opposite order as a pull. After assembling the
|
|
image manifest, the client must first push the individual layers. When the
|
|
layers are fully pushed into the registry, the client should upload the signed
|
|
manifest.
|
|
|
|
The details of each step of the process are covered in the following sections.
|
|
|
|
#### Pushing a Layer
|
|
|
|
All layer uploads use two steps to manage the upload process. The first step
|
|
starts the upload in the registry service, returning a url to carry out the
|
|
second step. The second step uses the upload url to transfer the actual data.
|
|
Uploads are started with a POST request which returns a url that can be used
|
|
to push data and check upload status.
|
|
|
|
The `Location` header will be used to communicate the upload location after
|
|
each request. While it won't change in the this specification, clients should
|
|
use the most recent value returned by the API.
|
|
|
|
##### Starting An Upload
|
|
|
|
To begin the process, a POST request should be issued in the following format:
|
|
|
|
```
|
|
POST /v2/<name>/blobs/uploads/
|
|
```
|
|
|
|
The parameters of this request are the image namespace under which the layer
|
|
will be linked. Responses to this request are covered below.
|
|
|
|
##### Existing Layers
|
|
|
|
The existence of a layer can be checked via a `HEAD` request to the blob store
|
|
API. The request should be formatted as follows:
|
|
|
|
```
|
|
HEAD /v2/<name>/blobs/<digest>
|
|
```
|
|
|
|
If the layer with the tarsum specified in `digest` is available, a 200 OK
|
|
response will be received, with no actual body content (this is according to
|
|
http specification). The response will look as follows:
|
|
|
|
```
|
|
200 OK
|
|
Content-Length: <length of blob>
|
|
Docker-Content-Digest: <digest>
|
|
```
|
|
|
|
When this response is received, the client can assume that the layer is
|
|
already available in the registry under the given name and should take no
|
|
further action to upload the layer. Note that the binary digests may differ
|
|
for the existing registry layer, but the tarsums will be guaranteed to match.
|
|
|
|
##### Uploading the Layer
|
|
|
|
If the POST request is successful, a `202 Accepted` response will be returned
|
|
with the upload URL in the `Location` header:
|
|
|
|
```
|
|
202 Accepted
|
|
Location: /v2/<name>/blobs/uploads/<uuid>
|
|
Range: bytes=0-<offset>
|
|
Content-Length: 0
|
|
Docker-Upload-UUID: <uuid>
|
|
```
|
|
|
|
The rest of the upload process can be carried out with the returned url,
|
|
called the "Upload URL" from the `Location` header. All responses to the
|
|
upload url, whether sending data or getting status, will be in this format.
|
|
Though the URI format (`/v2/<name>/blobs/uploads/<uuid>`) for the `Location`
|
|
header is specified, clients should treat it as an opaque url and should never
|
|
try to assemble the it. While the `uuid` parameter may be an actual UUID, this
|
|
proposal imposes no constraints on the format and clients should never impose
|
|
any.
|
|
|
|
If clients need to correlate local upload state with remote upload state, the
|
|
contents of the `Docker-Upload-UUID` header should be used. Such an id can be
|
|
used to key the last used location header when implementing resumable uploads.
|
|
|
|
##### Upload Progress
|
|
|
|
The progress and chunk coordination of the upload process will be coordinated
|
|
through the `Range` header. While this is a non-standard use of the `Range`
|
|
header, there are examples of [similar approaches](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) in APIs with heavy use.
|
|
For an upload that just started, for an example with a 1000 byte layer file,
|
|
the `Range` header would be as follows:
|
|
|
|
```
|
|
Range: bytes=0-0
|
|
```
|
|
|
|
To get the status of an upload, issue a GET request to the upload URL:
|
|
|
|
```
|
|
GET /v2/<name>/blobs/uploads/<uuid>
|
|
Host: <registry host>
|
|
```
|
|
|
|
The response will be similar to the above, except will return 204 status:
|
|
|
|
```
|
|
204 No Content
|
|
Location: /v2/<name>/blobs/uploads/<uuid>
|
|
Range: bytes=0-<offset>
|
|
Docker-Upload-UUID: <uuid>
|
|
```
|
|
|
|
Note that the HTTP `Range` header byte ranges are inclusive and that will be
|
|
honored, even in non-standard use cases.
|
|
|
|
##### Monolithic Upload
|
|
|
|
A monolithic upload is simply a chunked upload with a single chunk and may be
|
|
favored by clients that would like to avoided the complexity of chunking. To
|
|
carry out a "monolithic" upload, one can simply put the entire content blob to
|
|
the provided URL:
|
|
|
|
```
|
|
PUT /v2/<name>/blobs/uploads/<uuid>?digest=<tarsum>[&digest=sha256:<hex digest>]
|
|
Content-Length: <size of layer>
|
|
Content-Type: application/octet-stream
|
|
|
|
<Layer Binary Data>
|
|
```
|
|
|
|
The "digest" parameter must be included with the PUT request. Please see the
|
|
_Completed Upload_ section for details on the parameters and expected
|
|
responses.
|
|
|
|
Additionally, the upload can be completed with a single `POST` request to
|
|
the uploads endpoint, including the "size" and "digest" parameters:
|
|
|
|
```
|
|
POST /v2/<name>/blobs/uploads/?digest=<tarsum>[&digest=sha256:<hex digest>]
|
|
Content-Length: <size of layer>
|
|
Content-Type: application/octet-stream
|
|
|
|
<Layer Binary Data>
|
|
```
|
|
|
|
On the registry service, this should allocate a download, accept and verify
|
|
the data and return the same response as the final chunk of an upload. If the
|
|
POST request fails collecting the data in any way, the registry should attempt
|
|
to return an error response to the client with the `Location` header providing
|
|
a place to continue the download.
|
|
|
|
The single `POST` method is provided for convenience and most clients should
|
|
implement `POST` + `PUT` to support reliable resume of uploads.
|
|
|
|
##### Chunked Upload
|
|
|
|
To carry out an upload of a chunk, the client can specify a range header and
|
|
only include that part of the layer file:
|
|
|
|
```
|
|
PATCH /v2/<name>/blobs/uploads/<uuid>
|
|
Content-Length: <size of chunk>
|
|
Content-Range: <start of range>-<end of range>
|
|
Content-Type: application/octet-stream
|
|
|
|
<Layer Chunk Binary Data>
|
|
```
|
|
|
|
There is no enforcement on layer chunk splits other than that the server must
|
|
receive them in order. The server may enforce a minimum chunk size. If the
|
|
server cannot accept the chunk, a `416 Requested Range Not Satisfiable`
|
|
response will be returned and will include a `Range` header indicating the
|
|
current status:
|
|
|
|
```
|
|
416 Requested Range Not Satisfiable
|
|
Location: /v2/<name>/blobs/uploads/<uuid>
|
|
Range: 0-<last valid range>
|
|
Content-Length: 0
|
|
Docker-Upload-UUID: <uuid>
|
|
```
|
|
|
|
If this response is received, the client should resume from the "last valid
|
|
range" and upload the subsequent chunk. A 416 will be returned under the
|
|
following conditions:
|
|
|
|
- Invalid Content-Range header format
|
|
- Out of order chunk: the range of the next chunk must start immediately after
|
|
the "last valid range" from the previous response.
|
|
|
|
When a chunk is accepted as part of the upload, a `202 Accepted` response will
|
|
be returned, including a `Range` header with the current upload status:
|
|
|
|
```
|
|
202 Accepted
|
|
Location: /v2/<name>/blobs/uploads/<uuid>
|
|
Range: bytes=0-<offset>
|
|
Content-Length: 0
|
|
Docker-Upload-UUID: <uuid>
|
|
```
|
|
|
|
##### Completed Upload
|
|
|
|
For an upload to be considered complete, the client must submit a `PUT`
|
|
request on the upload endpoint with a digest parameter. If it is not provided,
|
|
the upload will not be considered complete. The format for the final chunk
|
|
will be as follows:
|
|
|
|
```
|
|
PUT /v2/<name>/blob/uploads/<uuid>?digest=<tarsum>[&digest=sha256:<hex digest>]
|
|
Content-Length: <size of chunk>
|
|
Content-Range: <start of range>-<end of range>
|
|
Content-Type: application/octet-stream
|
|
|
|
<Last Layer Chunk Binary Data>
|
|
```
|
|
|
|
Optionally, if all chunks have already been uploaded, a `PUT` request with a
|
|
`digest` parameter and zero-length body may be sent to complete and validated
|
|
the upload. Multiple "digest" parameters may be provided with different
|
|
digests. The server may verify none or all of them but _must_ notify the
|
|
client if the content is rejected.
|
|
|
|
When the last chunk is received and the layer has been validated, the client
|
|
will receive a `201 Created` response:
|
|
|
|
```
|
|
201 Created
|
|
Location: /v2/<name>/blobs/<tarsum>
|
|
Content-Length: 0
|
|
Docker-Content-Digest: <digest>
|
|
```
|
|
|
|
The `Location` header will contain the registry URL to access the accepted
|
|
layer file. The `Docker-Content-Digest` header returns the canonical digest of
|
|
the uploaded blob which may differ from the provided digest. Most clients may
|
|
ignore the value but if it is used, the client should verify the value against
|
|
the uploaded blob data.
|
|
|
|
###### Digest Parameter
|
|
|
|
The "digest" parameter is designed as an opaque parameter to support
|
|
verification of a successful transfer. The initial version of the registry API
|
|
will support a tarsum digest, in the standard tarsum format. For example, a
|
|
HTTP URI parameter might be as follows:
|
|
|
|
```
|
|
tarsum.v1+sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b
|
|
```
|
|
|
|
Given this parameter, the registry will verify that the provided content does
|
|
result in this tarsum. Optionally, the registry can support other other digest
|
|
parameters for non-tarfile content stored as a layer. A regular hash digest
|
|
might be specified as follows:
|
|
|
|
```
|
|
sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b
|
|
```
|
|
|
|
Such a parameter would be used to verify that the binary content (as opposed
|
|
to the tar content) would be verified at the end of the upload process.
|
|
|
|
For the initial version, registry servers are only required to support the
|
|
tarsum format.
|
|
|
|
##### Canceling an Upload
|
|
|
|
An upload can be cancelled by issuing a DELETE request to the upload endpoint.
|
|
The format will be as follows:
|
|
|
|
```
|
|
DELETE /v2/<name>/blobs/uploads/<uuid>
|
|
```
|
|
|
|
After this request is issued, the upload uuid will no longer be valid and the
|
|
registry server will dump all intermediate data. While uploads will time out
|
|
if not completed, clients should issue this request if they encounter a fatal
|
|
error but still have the ability to issue an http request.
|
|
|
|
##### Errors
|
|
|
|
If an 502, 503 or 504 error is received, the client should assume that the
|
|
download can proceed due to a temporary condition, honoring the appropriate
|
|
retry mechanism. Other 5xx errors should be treated as terminal.
|
|
|
|
If there is a problem with the upload, a 4xx error will be returned indicating
|
|
the problem. After receiving a 4xx response (except 416, as called out above),
|
|
the upload will be considered failed and the client should take appropriate
|
|
action.
|
|
|
|
Note that the upload url will not be available forever. If the upload uuid is
|
|
unknown to the registry, a `404 Not Found` response will be returned and the
|
|
client must restart the upload process.
|
|
|
|
#### Pushing an Image Manifest
|
|
|
|
Once all of the layers for an image are uploaded, the client can upload the
|
|
image manifest. An image can be pushed using the following request format:
|
|
|
|
PUT /v2/<name>/manifests/<reference>
|
|
|
|
{
|
|
"name": <name>,
|
|
"tag": <tag>,
|
|
"fsLayers": [
|
|
{
|
|
"blobSum": <tarsum>
|
|
},
|
|
...
|
|
]
|
|
],
|
|
"history": <v1 images>,
|
|
"signature": <JWS>,
|
|
...
|
|
}
|
|
|
|
The `name` and `reference` fields of the response body must match those specified in
|
|
the URL. The `reference` field may be a "tag" or a "digest".
|
|
|
|
If there is a problem with pushing the manifest, a relevant 4xx response will
|
|
be returned with a JSON error message. Please see the _PUT Manifest section
|
|
for details on possible error codes that may be returned.
|
|
|
|
If one or more layers are unknown to the registry, `BLOB_UNKNOWN` errors are
|
|
returned. The `detail` field of the error response will have a `digest` field
|
|
identifying the missing blob, which will be a tarsum. An error is returned for
|
|
each unknown blob. The response format is as follows:
|
|
|
|
{
|
|
"errors:" [{
|
|
"code": "BLOB_UNKNOWN",
|
|
"message": "blob unknown to registry",
|
|
"detail": {
|
|
"digest": <tarsum>
|
|
}
|
|
},
|
|
...
|
|
]
|
|
}
|
|
|
|
#### Listing Image Tags
|
|
|
|
It may be necessary to list all of the tags under a given repository. The tags
|
|
for an image repository can be retrieved with the following request:
|
|
|
|
GET /v2/<name>/tags/list
|
|
|
|
The response will be in the following format:
|
|
|
|
200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": <name>,
|
|
"tags": [
|
|
<tag>,
|
|
...
|
|
]
|
|
}
|
|
|
|
For repositories with a large number of tags, this response may be quite
|
|
large, so care should be taken by the client when parsing the response to
|
|
reduce copying.
|
|
|
|
### Deleting an Image
|
|
|
|
An image may be deleted from the registry via its `name` and `reference`. A
|
|
delete may be issued with the following request format:
|
|
|
|
DELETE /v2/<name>/manifests/<reference>
|
|
|
|
For deletes, `reference` *must* be a digest or the delete will fail. If the
|
|
image exists and has been successfully deleted, the following response will be
|
|
issued:
|
|
|
|
202 Accepted
|
|
Content-Length: None
|
|
|
|
If the image had already been deleted or did not exist, a `404 Not Found`
|
|
response will be issued instead.
|
|
|
|
## Detail
|
|
|
|
> **Note**: This section is still under construction. For the purposes of
|
|
> implementation, if any details below differ from the described request flows
|
|
> above, the section below should be corrected. When they match, this note
|
|
> should be removed.
|
|
|
|
The behavior of the endpoints are covered in detail in this section, organized
|
|
by route and entity. All aspects of the request and responses are covered,
|
|
including headers, parameters and body formats. Examples of requests and their
|
|
corresponding responses, with success and failure, are enumerated.
|
|
|
|
> **Note**: The sections on endpoint detail are arranged with an example
|
|
> request, a description of the request, followed by information about that
|
|
> request.
|
|
|
|
A list of methods and URIs are covered in the table below:
|
|
|
|
|Method|Path|Entity|Description|
|
|
|------|----|------|-----------|
|
|
{{range $route := .RouteDescriptors}}{{range $method := .Methods}}| {{$method.Method}} | `{{$route.Path|prettygorilla}}` | {{$route.Entity}} | {{$method.Description}} |
|
|
{{end}}{{end}}
|
|
|
|
The detail for each endpoint is covered in the following sections.
|
|
|
|
### Errors
|
|
|
|
The error codes encountered via the API are enumerated in the following table:
|
|
|
|
|Code|Message|Description|
|
|
|----|-------|-----------|
|
|
{{range $err := .ErrorDescriptors}} `{{$err.Value}}` | {{$err.Message}} | {{$err.Description|removenewlines}}
|
|
{{end}}
|
|
|
|
{{range $route := .RouteDescriptors}}
|
|
### {{.Entity}}
|
|
|
|
{{.Description}}
|
|
|
|
{{range $method := $route.Methods}}
|
|
|
|
#### {{.Method}} {{$route.Entity}}
|
|
|
|
{{.Description}}
|
|
|
|
{{if .Requests}}{{range .Requests}}{{if .Name}}
|
|
##### {{.Name}}{{end}}
|
|
|
|
```
|
|
{{$method.Method}} {{$route.Path|prettygorilla}}{{if .QueryParameters}}?{{range .QueryParameters}}{{.Name}}={{.Format}}{{end}}{{end}}{{range .Headers}}
|
|
{{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}}
|
|
Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}}
|
|
|
|
{{.Body.Format}}{{end}}
|
|
```
|
|
|
|
{{.Description}}
|
|
|
|
{{if or .Headers .PathParameters .QueryParameters}}
|
|
The following parameters should be specified on the request:
|
|
|
|
|Name|Kind|Description|
|
|
|----|----|-----------|
|
|
{{range .Headers}}|`{{.Name}}`|header|{{.Description}}|
|
|
{{end}}{{range .PathParameters}}|`{{.Name}}`|path|{{.Description}}|
|
|
{{end}}{{range .QueryParameters}}|`{{.Name}}`|query|{{.Description}}|
|
|
{{end}}{{end}}
|
|
|
|
{{if .Successes}}
|
|
{{range .Successes}}
|
|
###### On Success: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}}
|
|
|
|
```
|
|
{{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}}
|
|
{{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}}
|
|
Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}}
|
|
|
|
{{.Body.Format}}{{end}}
|
|
```
|
|
|
|
{{.Description}}
|
|
|
|
{{if .Headers}}The following headers will be returned with the response:
|
|
|
|
|Name|Description|
|
|
|----|-----------|
|
|
{{range .Headers}}|`{{.Name}}`|{{.Description}}|
|
|
{{end}}{{end}}{{end}}{{end}}
|
|
|
|
{{if .Failures}}
|
|
{{range .Failures}}
|
|
###### On Failure: {{if .Name}}{{.Name}}{{else}}{{.StatusCode | statustext}}{{end}}
|
|
|
|
```
|
|
{{.StatusCode}} {{.StatusCode | statustext}}{{range .Headers}}
|
|
{{.Name}}: {{.Format}}{{end}}{{if .Body.ContentType}}
|
|
Content-Type: {{.Body.ContentType}}{{end}}{{if .Body.Format}}
|
|
|
|
{{.Body.Format}}{{end}}
|
|
```
|
|
|
|
{{.Description}}
|
|
{{if .Headers}}
|
|
The following headers will be returned on the response:
|
|
|
|
|Name|Description|
|
|
|----|-----------|
|
|
{{range .Headers}}|`{{.Name}}`|{{.Description}}|
|
|
{{end}}{{end}}
|
|
|
|
{{if .ErrorCodes}}
|
|
The error codes that may be included in the response body are enumerated below:
|
|
|
|
|Code|Message|Description|
|
|
|----|-------|-----------|
|
|
{{range $err := .ErrorCodes}}| `{{$err}}` | {{$err.Descriptor.Message}} | {{$err.Descriptor.Description|removenewlines}} |
|
|
{{end}}
|
|
|
|
{{end}}{{end}}{{end}}{{end}}{{end}}{{end}}
|
|
|
|
{{end}}
|