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.待更新