概要

专有名词解释

• repository name（存储库名称）

存储库指在库中存储的镜像

• 语法

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

• digest（概要）

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

• 语法

digest    := algorithm ":" hex
algorithm := /[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镜像过程

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

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

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

• API

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

Note

reference可以是tag或者是digest

1. Pulling a Layer（拉取层）

• API

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

PUSHING镜像过程

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

1. Pushing a Layer（上传层）

上传层分为两步，第一步使用post请求在registry仓库启动上传服务

，返回一个url，这个url可以用来上传数据和检查状态。

1. Existing Layers(检查层是否存在)

• API

>>> HEAD /v2/<name>/blobs/<digest>

• RETURN

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

1. Starting An Upload(启动上传服务)

• API

>>> POST /v2/<name>/blobs/uploads/

• RETURN

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

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

1. Uploading the Layer(上传层)

1. Upload Progress(上传进度)

• API

>>> GET /v2/<name>/blobs/uploads/<uuid>
>>> Host: <registry host>

• RETURN

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

1. Monolithic Upload(整块上传）

• API

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

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

1. 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 Created
Location: /v2/<name>/blobs/<digest>
Content-Length: 0
Docker-Content-Digest: <digest>

1. Canceling an Upload(取消上传)

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

• API

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

1. Cross Repository Blob Mount（交叉挂载层）

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

• API

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

• RETURN

• 成功返回：

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>

1. Deleting a Layer(删除层)

• API

>>> DELETE /v2/<name>/blobs/<digest>

• RETURN

• 成功返回：

202 Accepted
Content-Length: None

• 失败返回404错误。

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

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

• API

>>> 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>}},...]
}

检索功能

1. Listing Repositories（列出存储库）

• API

>>> GET /v2/_catalog

• RETURN

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

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

• API

>>> GET /v2/_catalog?n=<integer>

Note

integer表示要列出库的个数

• RETURN

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

1. Listing Image Tags(列出镜像tag)

• API

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

• RETURN

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

1. Pagination(部分列出镜像tag)

• API

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

• RETURN

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>,...]
}

Deleting an Image(删除镜像)

• API

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

• RETURN

• 成功

202 Accepted
Content-Length: None

• 失败返回404错误