简要:本文主要是对镜像结构及 Registry API 使用进行了总结。
API1、拉取镜像一个镜像是由 JSON 元数据和独立的层文件组成,而镜像检索的重点就是找到这两部分。
拉取镜像的第一步是取回元数据(manifest),注册表(registry)相关字段如下:
字段 | 描述 |
name | 镜像名称 |
tag | 镜像版本 |
fsLayers | 层描述符列表(包括摘要) |
signature | 元数据签名 |
当获取元数据清单后,客户端必须验证签名保证名称和层的有效性。确认后,客户端将使用摘要(digest)下载层文件(layer)。
1.1、拉取 manifestsGET /v2/<name>/manifests/<reference>
name和reference是定义镜像的必需参数,能够指定唯一镜像,reference可以是 tag 或 digest
返回数据
{ "schemaVersion": 1, "name": <name>, "tag": <tag>, "architecture": "amd64", "fsLayers": [ { "blobSum": "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4" } ], "history": [<v1 images>], "signatures": [<JWS>]}
客户端应在获取层文件之前验证返回的元数据签名的真实性。
1.1.1、镜像是否存在HEAD /v2/<name>/manifests/<reference>
name和reference是定义镜像的必需参数,能够指定唯一镜像,reference可以是 tag 或 digest
如果返回 404 表示镜像不存在。如果镜像存在返回 200
HTTP/1.1 200 OKContent-Length: 9116Content-Type: application/vnd.docker.distribution.manifest.v1+prettyjwsDocker-Content-Digest: sha256:0f09fdacdca588279f0cb332ed0768daa9ed734c491d5d04b89d215982c2bfac
1.2、拉取层文件
层存储在注册表的 blob 部分中,由摘要键入。 拉取层是通过标准的 http 请求进行的
GET /v2/<name>/blobs/<digest>
对层的访问由存储库中的 name 控制,但是在注册表中由摘要唯一标识。
这个 api 可能会响应 307 重定向到另一个服务去下载层,客户端应要处理重定向。
2、推送镜像推送镜像和拉取镜像的工作顺序相反。在组装镜像清单后,客户端必须先推送每个层,当层文件完全推送到注册表中,客户端需要上传元数据签名。
2.1、推送层文件层文件上传需要两步:
在注册表服务开始上传,返回 url 进行第二步使用 url 传输实际的数据上传是用 POST 请求开始,该请求返回可用于推送数据和检查上传状态的 url。
请求头“Location”将用于定位每次请求上传后的位置。
2.1.1、开始上传POST /v2/<name>/blobs/uploads
请求的参数是将镜像空间链接到层文件
2.1.2、层是否存在HEAD /v2/<name>/blobs/<digest>
如果指定的层文件的摘要存在,则响应 200,没有 body。
200 OKContent-Length: <length of blob>Docker-Content-Digest: <digest>
当收到响应,客户端能知道层已经存在注册表中,不需要进行上传操作
2.1.3、上传层文件如果 POST 请求成功,响应 202,然后在响应头中会有“Location”指定上传 url
202 AcceptedLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Content-Length: 0Docker-Upload-UUID: <uuid>
上传过程用返回的 url 进行,对上传 url 的所有响应,无论是发送数据还是获取状态,都按照这种格式。尽管指定了“Location”标头的 URI 格式,但是客户端应将其视为黑盒,不要自己去组装。如果客户端需要将本地上传状态和远程上传状态关联,应使用Docker-Upload-UUID:标头的内容,在断点重传时,uuid 可以键入最后使用的位置。
2.1.4、上传进度上传进度是通过头Range标识,虽然不是Range的标准使用方法,仍有很多例子使用。
对于刚刚开始的上传,例如一个 1000 字节的层文件,“Range”标头如下:
Range: bytes=0-0
使用 GET 方法获取上传进度
GET /v2/<name>/blobs/uploads/<uuid>Host: <registry host>
响应类似,会返回 204
204 No ContentLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Docker-Upload-UUID: <uuid>
2.1.5、单块上传
单块上传是上传单个块,避免分块复杂性,要执行单块上传,只需将整个 blob 放到提供的 url 中
PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>Content-Length: <size of layer>Content-Type: application/octet-stream<Layer Binary Data>
digest参数必须要在 PUT 电脑 请求中使用
2.1.6、分块上传要执行一个块的上传,客户端可以指定Range并且只包含层的Range部分
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。
如果收到 416,客户端应从“最后一个有效范围”恢复上传,在此情况下返回 416:
无效的请求头Content-Range乱序块:下一个块的范围必须在前一个响应的“最后一个有效范围”之后立即开始如果块被成功接收,会返回 202
2.1.7、完成上传为了保证上传完整性,客户端在上传 url 提交一个带有摘要参数的 PUT 请求,如果未提供,则不认为上传完成。
PUT /v2/<name>/blobs/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>
可选的,如果所有块都已上传,则可以发送带有 digest 参数和 0 长度的 body 的 PUT 请电脑求以验证完成上传。
当最后一个块被接收,层校验完毕,客户端会收到 201 响应
201 CreatedLocation: /v2/<name>/blobs/<digest>Content-Length: 0Docker-Content-Digest: <digest>
Location会包含可访问的层 url,Docker-Content-Digest返回上传的 blob 摘要。
2.1.8、取消上传DELETE /v2/<name>/blobs/uploads/<uuid>
发出此请求后,上传的 uuid 将不再有效,注册服务器将转储所有中间数据。虽然上传未完成会超时,但是如果客户端遇到致命错误仍可发出 http 请求,则应发出此请求。
2.1.9、跨存储库挂载可以从客户端具有读取访问权限的另一个存储库安装 blob,从而无需上传注册表已知的 blob。 要发出 blob 挂载而不是上传,应按以下格式发出 POST 请求
POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<repository name>Content-Length: 0
如果 blob 成功被挂载,客户端会收到响应 201
201 CreatedLocation: /v2/<name>/blobs/<digest>Content-Length: 0Docker-Content-Digest: <digest>
Location将包含用于访问已经接收层文件的注册表 URI,Docker-Content-Digest返回上传的 blob 的摘要。
如果由于无效的存储库或摘要导致挂载失败,则注册表会回退到标准上传行为,并返回 202
202 AcceptedLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Content-Length: 0Docker-Upload-UUID: <uuid>
2.2、删除层文件
DELETE /v2/<name>/blobs/<digest>
如果存储库存在并且成功被删除,会响应 202,如果已经被删除或不存在,会响应 404。
如果删除注册表(registry)中清单(manifest)引用的层,则无法解析完整的镜像
2.3、推送镜像元数据所有层文件已经上传,客户端能够上传镜像元数据了。
PUT /v2/`<name>`/manifests/`<reference>` Content-Type: `<manifest media type>` { "name":`<name>`, "tag": `<tag>`, "fsLayers": [ { "blobSum": `<digest>` }, ... ] ], "history": `<v1 images>`, "signature": `<JWS>`, ... }
如果上传出现问题,会响应 4xxx。如果在注册表中层文件不存在,会返回BLOB_UNKNOWN错误
{ "errors:" [{ "code": "BLOB_UNKNOWN", "message": "blob unknown to registry", "detail": { "digest":`<digest>` } }, ... ] }
3、小结
pull 分为两个步骤,第一步拉取清单 manifest,然后再根据清单中的 layers 拉取层文件。
push 分为两步,第一步会先去推送层文件 layer,会判断仓库中是否存在,是否需要分块上传,所有层文件上传完成之后,再去上传清单 manifest。
电脑