It interacts with instances of the docker registry, which is a service to manage information about docker images and enable their distribution. 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 is a set of changes to the docker the image format, covered in. 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. 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. Differentiating use cases are covered below. An untrusted registry returns a manifest. After each layer is downloaded, the engine verifies the digest of the layer, ensuring that the content matches that specified by the manifest. 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. 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. 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. Each set of changes is given a letter corresponding to a set of modifications that were applied to the baseline specification. Classically, repository names have always been two path components where each path component is less than 30 characters. A component of a repository name must be at least one lowercase, alpha-numeric characters, optionally separated by periods, dashes or underscores. All endpoints should support aggressive http caching, compression and range headers, where appropriate. For detail on individual endpoints, please see the section. Errors Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses, in a json response body. 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. 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 section. Optionally, the response may contain information about the supported paths in the response body. The client should be prepared to ignore this data. Depending on access control setup, the client may still have to authenticate against different resources, even if this check succeeds. The core of this design is the concept of a content addressable identifier. It uniquely identifies content by taking a collision-resistant 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. 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. D gets the algorithm concatenated with the hex encoding of B. 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. Note that the commonly used canonicalization for digest calculation may be dependent docker java api 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 docker java api 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. To maintain security, the client must always verify the content against the digest used to fetch the content. The process of pulling an image centers around retrieving these two components. The first step in pulling an docker
