docker registry http api v2

来源：互联网发布：win7 网络打印机脱机编辑：程序博客网时间：2024/05/16 09:59

docker registry v2版本的http api 一直没有找到合适的，自己通过阅读官方文档整理了一下。

概要

methodpathEntityDescriptionGET/v2/BaseCheck that the endpoint implements Docker Registry API V2.GET/v2/<name>/tags/listTagsFetch the tags under the repository identified by name.GET/v2/<name>/manifests/<reference>ManifestFetch the manifest identified by nameand referencewhere referencecan be a tag or digest. A HEADrequest can also be issued to this endpoint to obtain resource information without receiving all data.PUT/v2/<name>/manifests/<reference>ManifestPut the manifest identified by nameand referencewhere referencecan be a tag or digest.DELETE/v2/<name>/manifests/<reference>ManifestDelete the manifest identified by nameand reference. Note that a manifest can only be deleted by digest.GET/v2/<name>/blobs/<digest>BlobRetrieve the blob from the registry identified bydigest. A HEADrequest can also be issued to this endpoint to obtain resource information without receiving all data.DELETE/v2/<name>/blobs/<digest>BlobDelete the blob identified by nameand digestPOST/v2/<name>/blobs/uploads/Initiate Blob UploadInitiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if thedigest parameter is present, the request body will be used to complete the upload in a single request.GET/v2/<name>/blobs/uploads/<uuid>Blob UploadRetrieve status of upload identified byuuid. The primary purpose of this endpoint is to resolve the current status of a resumable upload.PATCH/v2/<name>/blobs/uploads/<uuid>Blob UploadUpload a chunk of data for the specified upload.PUT/v2/<name>/blobs/uploads/<uuid>Blob UploadComplete the upload specified by uuid, optionally appending the body as the final chunk.DELETE/v2/<name>/blobs/uploads/<uuid>Blob UploadCancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout.GET/v2/_catalogCatalogRetrieve a sorted, json list of repositories available in the registry.

专有名词解释

repository name（存储库名称）

存储库指在库中存储的镜像
语法
经典存储库名称由两级路径构成，每级路径小于30个字符，v2的api不强制要求这样的格式
每级路径名至少有一个小写字母或者数字，使用句号，破折号和下划线分隔。更严格来说，它必须符合正则表达式：[a-z0-9]+(?:[._-][a-z0-9]+)*
多级路径用/分隔
存储库名称总长度（包括/）不能超过256个字符

digest（概要）

概要是镜像各个层的唯一标识。虽然算法允许使用任意算法，但是为了兼容性应该使用sha256。例：sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b

语法

digest    := algorithm ":" hexalgorithm := /[A-Fa-f0-9_+.-]+/hex       := /[A-Fa-f0-9]+/

生成摘要的伪代码

let C = 'a small string'let B = sha256(C)let D = 'sha256:' + EncodeHex(B)let ID(C) = D

PULL镜像过程

镜像由一个json清单和层叠文件组成，pull镜像的过程就是检索这两个组件的过程。

拉取镜像的第一步就是获取清单，清单由下面几个字段组成：

字段描述name镜像名称tag镜像当前版本的tagfsLayers层描述列表(包含摘要)signature一个JWS签名，用来验证清单内容

当获取清单之后，客户端需要验证签名（signature），以确保名称和层是有效的。确认后，客户端可以使用digest去下载各个层，在v2API中，层存储在blobs中以digest作为键值。

Pulling an Image Manifest（拉取镜像清单）

>>> HEAD /v2/<name>/manifests/<reference> #检查镜像清单是否存在>>> GET /v2/<name>/manifests/<reference>  #拉取镜像清单

Note

reference可以是tag或者是digest

Pulling a Layer（拉取层）

>>> GET /v2/<name>/blobs/<digest>

PUSHING镜像过程

推镜像和拉取镜像过程相反，先推各个层到registry仓库，然后上传清单。

Pushing a Layer（上传层）

上传层分为两步，第一步使用post请求在registry仓库启动上传服务
，返回一个url，这个url可以用来上传数据和检查状态。
Existing Layers(检查层是否存在)
API
>>> HEAD /v2/<name>/blobs/<digest>
RETURN
若返回200 OK则表示存在，不用上传
Starting An Upload(启动上传服务)
API
>>> POST /v2/<name>/blobs/uploads/
RETURN
如果post请求返回202 accepted，一个url会在location字段返回.
202 AcceptedLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Content-Length: 0Docker-Upload-UUID: <uuid> # 可以用来查看上传状态和实现断点续传
Uploading the Layer(上传层)
Upload Progress(上传进度)
API
>>> GET /v2/<name>/blobs/uploads/<uuid>>>> Host: <registry host>
RETURN
204 No ContentLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Docker-Upload-UUID: <uuid>
Monolithic Upload(整块上传）
API
>>> PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>>>> Content-Length: <size of layer>>>> Content-Type: application/octet-stream<Layer Binary Data>
Chunked Upload（分块上传）
API
>>> 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>
RETURN
如果服务器不接受这个块，则返回：
416 Requested Range Not SatisfiableLocation: /v2/<name>/blobs/uploads/<uuid>Range: 0-<last valid range>Content-Length: 0Docker-Upload-UUID: <uuid>
成功返回：
202 AcceptedLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Content-Length: 0Docker-Upload-UUID: <uuid>
Completed Upload(上传完成)
分块上传在最后一块上传完毕后，需要提交一个上传完成的请求
API
>>> PUT /v2/<name>/blob/uploads/<uuid>?digest=<digest>>>> Content-Length: <size of chunk>>>> Content-Range: <start of range>-<end of range>>>> Content-Type: application/octet-stream<Last Layer Chunk Binary Data>
RETURN
201 CreatedLocation: /v2/<name>/blobs/<digest>Content-Length: 0Docker-Content-Digest: <digest>
Canceling an Upload(取消上传)
这个请求执行后uuid将失效，当上传超时或者没有完成，客户端都应该发送这个请求。
API
>>> DELETE /v2/<name>/blobs/uploads/<uuid>
Cross Repository Blob Mount（交叉挂载层）
此api可把客户端有访问权限的已有存储库中的层挂载到当前储存库中。
API
>>> POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<repository name>Content-Length: 0
RETURN
成功返回：
201 CreatedLocation: /v2/<name>/blobs/<digest>Content-Length: 0Docker-Content-Digest: <digest>
失败返回：
202 AcceptedLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Content-Length: 0Docker-Upload-UUID: <uuid>

Deleting a Layer(删除层)

API
>>> DELETE /v2/<name>/blobs/<digest>
RETURN
成功返回：
202 AcceptedContent-Length: None
失败返回404错误。

Pushing an Image Manifest（上传镜像清单）

当镜像层上传完毕后，可以上传清单。

>>> PUT /v2/<name>/manifests/<reference>Content-Type: <manifest media type>{   "name": <name>,   "tag": <tag>,   "fsLayers": [      {         "blobSum": <digest>      },      ...    ]   ],   "history": <v1 images>,   "signature": <JWS>,   ...}

RETURN

如果清单中有层是未知的，则返回：

{ "errors:" [{         "code": "BLOB_UNKNOWN",         "message": "blob unknown to registry",         "detail": {             "digest": <digest>         }     },     ...  ]}

检索功能

Listing Repositories（列出存储库）

>>> GET /v2/_catalog

RETURN

200 OKContent-Type: application/json{  "repositories": [    <name>,    ...  ]}

Pagination(部分列出存储库)

>>> GET /v2/_catalog?n=<integer>
Note
integer表示要列出库的个数

RETURN

200 OKContent-Type: application/jsonLink: <<url>?n=<n from the request>&last=<last repository in response>>; rel="next"{  "repositories": [    <name>,    ...  ]}

Listing Image Tags(列出镜像tag)

>>> GET /v2/<name>/tags/list

RETURN

200 OKContent-Type: application/json{    "name": <name>,    "tags": [        <tag>,        ...    ]}

Pagination(部分列出镜像tag)

>>> GET /v2/<name>/tags/list?n=<integer>

RETURN

200 OKContent-Type: application/jsonLink: <<url>?n=<n from the request>&last=<last tag value from previous response>>; rel="next"{  "name": <name>,  "tags": [    <tag>,    ...  ]}

Deleting an Image(删除镜像)

>>> DELETE /v2/<name>/manifests/<reference>

RETURN

成功
202 AcceptedContent-Length: None
失败返回404错误

1 0