dockerdocker-registrydocker-pulldocker-pushdocker-tag

Is docker push/pull atomic?


The question is simple as it seems.

What happens if the push is interrupted (^C ?) during the process but the remote repository already has the image (same name/tag)? Will the successfully uploaded layers overwrite the existing images, may be corrupting it? In the same way, locally could happen that same thing.

Has anyone already investigated in this way?


Solution

  • Existing layers are not overwritten.

    This is how docker push/pull works according to v2 API:

    Docker image is made up of a singed manifest file and the individual layers. These layers are stored as blobs in the registry keyed by their digests. Manifest file will have the all the details required to pull, install, validate and run an image. It also contains the list of layers making up the image.

    Pushing an image

    When you are pushing an image, client will push the layers first and then upload the signed manifest. So if the push is interrupted in between before the manifest is uploaded, the registry will have some unreferenced blobs lying around. When the garbage collection is triggered, these blobs will be removed.

    When uploading a layer, client asks the registry if it already has the layer or not. If registry already has the layer, the upload of the particular layer is skipped. If registry doesn't have the layer, client will request for upload and registry returns a URL which the client can use to upload the layer. Layer can be uploaded in chunks or as monolithic single chunk. Once all chunks are uploaded, client must send the digest of the layer to the registry which the registry will validate and return success message if the digest of the uploaded content matches. Only after verifying the digest is the upload considered complete.

    Once all the layers are pushed, client uploads the image manifest file. Registry checks that it has all the layers references in the manifest and returns an appropriate errors like BLOB_UNKNOWN if it doesn't.

    Pulling an image

    Pulling images work in similar way but in opposite order. When pulling an image, client will first request for the image manifest and then download the layers that it doesn't have. Download is complete only if the digests are verified.