Docker Registry V2 api

本篇总结docker registry v2 api描述和使用docker-registry v2

API清单

名词解释

• repository name(存储库名词)

  存储库指在库中存储的镜像。/project/redis:latest

  • 语法：

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

• digest(摘要)

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

  1. 生成摘要的伪代码

     import hashlib
     C = 'a small string'
     B = hashlib.sha256(C)
     D = 'sha256:' + B.hexdigest()
     

镜像pull过程

镜像由一个json清单和层叠文件组成，pull镜像的过程就是检索这两个组件的过程。拉去镜像的第一步就是获取清单，清单由下面几个字段组成: registry:5000/v2/redis/manifests/latest(获取redis:latest清单文件)

当获取清单之后，客户端需要验证前面(signature)，以确保名称和fsLayers层是有效的。确认后，客户端可以使用digest去下载各个fs层。在V2api中，层存储在blobs中已digest作为键值.

1. 首先拉取镜像清单(pulling an Image Manifest)
  
  $ HEAD /v2/<image/manifests/<reference>#检查镜像清单是否存在
  $ GET /v2/<image>/manifests/<reference>#拉取镜像清单
  提示：reference可是是tag或者是digest
  
2. 开始拉取每个层(pulling a Layer)
   $ GET /v2/<image>/blobs/<digest>
   提示：digest是镜像每个fsLayer层的唯一标识。存在于清单的fsLayers里面。

Push镜像过程

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

1. Pushing a Layer(上传层)

   上传层分为2步,第一步使用post请求在registry仓库启动上传服务,
   返回一个url，这个url用来上传数据和检查状态。

   • 首先Existing Layers(检查层是否存在)

     $ HEAD /v2/image/blobs/<digest>

     若返回200 OK 则表示存在，不用上传

   • 开始上传服务(Starting An Upload)

     $POST /v2/image/blobs/uploads/

     如果post请求返回202 accepted，一个url会在location字段返回.

          202 Accepted
          Location: /v2/\<image>/blobs/uploads/\<uuid>
          Range: bytes=0-<offset>
          Content-Length: 0
          Docker-Upload-UUID: <uuid> # 可以用来查看上传状态和实现断点续传
     

   • 开始上传层(Uploging the Layer)

     1. 上传进度(Upload Progress)

        $ GET /v2/<image>/blobs/uploads/<uuid>

        返回

           204 No Content
           Location: /v2/<name>/blobs/uploads/<uuid>
           Range: bytes=0-<offset>
           Docker-Upload-UUID: <uuid>
        

     2. 整块上传(Monolithic Upload)

     > PUT /v2/<name>/blobs/uploads/<uuid>?digest=\<digest>
     
     > Content-Length: \<size of layer>
     
     > Content-Type: application/octet-stream
     

<Layer Binary Data>

    3. 分块上传(Chunked Upload)
         
        > 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>
        
        如果服务器不接受这个块，则返回:
            
              416 Requested Range Not Satisfiable
              Location: /v2/<name>/blobs/uploads/<uuid>
              Range: 0-<last valid range>
              Content-Length: 0
              Docker-Upload-UUID: <uuid>
             
         成功则返回：
         
            202 Accepted
            Location: /v2/<name>/blobs/uploads/<uuid>
            Range: bytes=0-<offset>
            Content-Length: 0
            Docker-Upload-UUID: <uuid>

• 上传完成(Completed Upload)

  分块上传在最后一块上传完毕后，需要提交一个上传完成的请求

     > 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>
  

  返回：

     201 Created
     Location: /v2/<name>/blobs/<digest>
     Content-Length: 0
     Docker-Content-Digest: <digest>
  

• 取消上传(Canceling an Upload)

  这个请求执行后UUID将失效，当上传超时或者没有完成，客户端都应该发送这个请求。

  DELETE /v2/image/blobs/uploads/<uuid>

• 交叉上传(Cross Repository Blob Mount)

  可以把客户端有访问权限的已有存储库中的层挂载到当前存储库中

  POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<repository name>
  Content-Length: 0

  成功返回：

    201 Created
    Location: /v2/<name>/blobs/<digest>
    Content-Length: 0
    Docker-Content-Digest: <digest>
  

  失败返回:

    202 Accepted
    Location: /v2/<name>/blobs/uploads/<uuid>
    Range: bytes=0-<offset>
    Content-Length: 0
    Docker-Upload-UUID: <uuid>
  

2. 删除层(Deleting a Layer)

   DELETE /v2/<image>/blobs/<digest>

   成功返回:

    202 Accepted
    Content-Length: None
   

   失败返回404错误

3. 上传镜像清单(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>,
    ...
    }
   

   返回：

    如果清单中有层("blobSum":<digest>)是未知的，则返回
    {
     "errors:" [{
             "code": "BLOB_UNKNOWN",
             "message": "blob unknown to registry",
             "detail": {
                 "digest": <digest>
             }
         },
         ...
      ]
    }
   

检索功能

1. 列出所有存储库(Listing Repositories)

   GET /v2/_catalog

   返回：

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

2. 列出部分存储库(Pagination)

   GET /v2/_catalog?n=<integer>

   Note： integer表示要列出库的个数

   返回：

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

3. 列出镜像所有tags(Listing Image Tags)

   GET /v2/image/tags/list

   返回:

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

4. 列出镜像部分tags(Pagination)

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

   返回：

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

5. 删除镜像(Deleting an Image)

   DELETE /v2/image/manifests/<reference>
   返回

    202 Accepted
    Content-Length: None
   

   失败返回404错误
   注意：默认情况下，registry不允许删除镜像操作，需要在启动registry时指定环境变量REGISTRY_STORAGE_DELETE_ENABLED=true,或者修改其配置文件即可。reference必须是digest,否则删除将失败。在registry2.3或更高版本删除清单时，必须在HEAD或GET获取清单以获取要删除的正确digest携带以下头：

Accept: application/vnd.docker.distribution.manifest.v2+json

6.待更新