Docker Registry V2 api

本篇總結(jié)docker registry v2 api描述和使用docker-registry v2

API清單

名詞解釋

• repository name(存儲(chǔ)庫(kù)名詞)

  存儲(chǔ)庫(kù)指在庫(kù)中存儲(chǔ)的鏡像。/project/redis:latest

  • 語(yǔ)法：

    1. 經(jīng)典存儲(chǔ)庫(kù)名稱(chēng)由2級(jí)路徑構(gòu)成，每級(jí)路徑小于30個(gè)字符，V2的api不強(qiáng)制要求這樣的格式。
    2. 每級(jí)路徑名至少有一個(gè)小寫(xiě)字母或者數(shù)字，使用句號(hào)，破折號(hào)和下劃線(xiàn)分割。更嚴(yán)格來(lái)說(shuō)，它必須符合正則表達(dá)式：[a-z0-9]+[._-][a-z0-9]+)
    3. 多級(jí)路徑用/分隔
    4. 存儲(chǔ)庫(kù)名稱(chēng)總長(zhǎng)度（包括/）不能超過(guò)256個(gè)字符

• digest(摘要)

  摘要是鏡像每個(gè)層的唯一標(biāo)示。雖然算法允許使用任意算法，但是為了兼容性應(yīng)該使用sha256。例如sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b

  1. 生成摘要的偽代碼

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

鏡像pull過(guò)程

鏡像由一個(gè)json清單和層疊文件組成，pull鏡像的過(guò)程就是檢索這兩個(gè)組件的過(guò)程。拉去鏡像的第一步就是獲取清單，清單由下面幾個(gè)字段組成: registry:5000/v2/redis/manifests/latest(獲取redis:latest清單文件)

當(dāng)獲取清單之后，客戶(hù)端需要驗(yàn)證前面(signature)，以確保名稱(chēng)和fsLayers層是有效的。確認(rèn)后，客戶(hù)端可以使用digest去下載各個(gè)fs層。在V2api中，層存儲(chǔ)在blobs中已digest作為鍵值.

1. 首先拉取鏡像清單(pulling an Image Manifest)
  
  $ HEAD /v2/<image/manifests/<reference>#檢查鏡像清單是否存在
  $ GET /v2/<image>/manifests/<reference>#拉取鏡像清單
  提示：reference可是是tag或者是digest
  
2. 開(kāi)始拉取每個(gè)層(pulling a Layer)
   $ GET /v2/<image>/blobs/<digest>
   提示：digest是鏡像每個(gè)fsLayer層的唯一標(biāo)識(shí)。存在于清單的fsLayers里面。

Push鏡像過(guò)程

推送鏡像和拉取鏡像過(guò)程相反,先推各個(gè)層到registry倉(cāng)庫(kù)，然后上傳清單.

1. Pushing a Layer(上傳層)

   上傳層分為2步,第一步使用post請(qǐng)求在registry倉(cāng)庫(kù)啟動(dòng)上傳服務(wù),
   返回一個(gè)url，這個(gè)url用來(lái)上傳數(shù)據(jù)和檢查狀態(tài)。

   • 首先Existing Layers(檢查層是否存在)

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

     若返回200 OK 則表示存在，不用上傳

   • 開(kāi)始上傳服務(wù)(Starting An Upload)

     $POST /v2/image/blobs/uploads/

     如果post請(qǐng)求返回202 accepted，一個(gè)url會(huì)在location字段返回.

          202 Accepted
          Location: /v2/\<image>/blobs/uploads/\<uuid>
          Range: bytes=0-<offset>
          Content-Length: 0
          Docker-Upload-UUID: <uuid> # 可以用來(lái)查看上傳狀態(tài)和實(shí)現(xiàn)斷點(diǎn)續(xù)傳
     

   • 開(kāi)始上傳層(Uploging the Layer)

     1. 上傳進(jìn)度(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>
        
        如果服務(wù)器不接受這個(gè)塊，則返回:
            
              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)

  分塊上傳在最后一塊上傳完畢后，需要提交一個(gè)上傳完成的請(qǐng)求

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

  這個(gè)請(qǐng)求執(zhí)行后UUID將失效，當(dāng)上傳超時(shí)或者沒(méi)有完成，客戶(hù)端都應(yīng)該發(fā)送這個(gè)請(qǐng)求。

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

• 交叉上傳(Cross Repository Blob Mount)

  可以把客戶(hù)端有訪(fǎng)問(wèn)權(quán)限的已有存儲(chǔ)庫(kù)中的層掛載到當(dāng)前存儲(chǔ)庫(kù)中

  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錯(cuò)誤

3. 上傳鏡像清單(Pushing an Image Manifest)

   我們上傳完鏡像層之后，就開(kāi)始上傳鏡像清單

    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. 列出所有存儲(chǔ)庫(kù)(Listing Repositories)

   GET /v2/_catalog

   返回：

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

2. 列出部分存儲(chǔ)庫(kù)(Pagination)

   GET /v2/_catalog?n=<integer>

   Note： integer表示要列出庫(kù)的個(gè)數(shù)

   返回：

    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錯(cuò)誤
   注意：默認(rèn)情況下，registry不允許刪除鏡像操作，需要在啟動(dòng)registry時(shí)指定環(huán)境變量REGISTRY_STORAGE_DELETE_ENABLED=true,或者修改其配置文件即可。reference必須是digest,否則刪除將失敗。在registry2.3或更高版本刪除清單時(shí)，必須在HEAD或GET獲取清單以獲取要?jiǎng)h除的正確digest攜帶以下頭：

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

6.待更新