企业官网建设流程全解析

containerd 2.x 如何使用 transfer service 完成镜像的 pull、push、import 与 export

【免费下载链接】containerdAn open and reliable container runtime项目地址: https://gitcode.com/GitHub_Trending/co/containerd

在 containerd 2.x 中,transfer service 已在 2.0 版本进入稳定状态,并内置了一个本地 transfer 插件。ctr的images pull、images push、images import、images export四条子命令默认就走 transfer service 完成操作,只有显式加上--local才会回退到由 client 本地直接读写内容的旧路径。本文按拉取、推送、导入、导出四个动作逐一给出可直接执行的ctr命令、各自的参数限制,以及用ctr images list验证结果的方法。

开始前:确认 daemon 与 transfer 插件

transfer 本地插件随 containerd 内置,不需要额外安装。按 transfer 服务文档,它和其他 containerd 插件一样可以通过 daemon 配置段定制,需要时在配置中加入:

[plugins] [plugins."io.containerd.transfer.v1"]

前提是你已经有一个正在运行的 containerd daemon,并且ctr能够连上它(可用ctr version或任意ctr子命令确认连接正常)。

transfer service 覆盖的四类操作

transfer API 只有一个操作,source和destination可以是不同对象,组合决定操作类型:

ctr的四个镜像命令分别对应表中前四种组合:pull 是 Registry 源到 Image Store 目的地,push 方向相反,import 用归档文件流作为源,export 用归档文件流作为目的地。import 发送的是io.Reader二进制流,export 发送的是io.WriteCloser二进制流,进度则通过 streaming service 的回调持续发回 client,所以ctr在传输过程中能实时打印进度树,事件包括resolving、downloading、uploading、extracting、complete、extracted等。

对用 Go 开发 client 的读者,入口是client.Transfer(ctx, source, destination, opts...)(见 client/transfer.go),每次调用会自动创建一个 lease,避免传输中的内容被 GC 回收;进度通过transfer.WithProgress选项传入回调。

pull:从 registry 拉取镜像

默认命令就是走 transfer service:

ctr images pull <ref>

例如ctr images pull docker.io/library/busybox:latest。执行过程中会看到实时的进度树(各层downloading、随后extracting、最后complete),结束时不再报错误即表示成功。

pull 的关键行为:

• 默认拉取本机默认平台的镜像;在 darwin 系统上,transfer 路径默认改用linux平台做解包。
• 拉取后默认解包到 snapshotter(--snapshotter指定,默认值为配置中的默认 snapshotter)。
• 不指定平台时默认拉取所有平台的元数据;--skip-metadata可以跳过未使用平台的元数据,但文档提示这样做后镜像可能无法再 push。

常用参数:

# 指定平台,并可重复 ctr images pull --platform linux/amd64 --platform linux/arm64 <ref> # 拉取所有平台的内容与元数据(与 --platform 互斥,二者不能同时给) ctr images pull --all-platforms <ref> # 私有 registry 认证,--user 支持 User[:password] 形式 ctr images pull --user 'username:password' <ref> # 自定义 hosts 配置目录,兼容 /etc/docker/certs.d 风格 ctr images pull --hosts-dir /etc/containerd/certs.d <ref> # 给镜像附加 label ctr images pull --label 'key=value' <ref>

传输排障时可以用--http-dump(dump 与 registry 的全部 HTTP 请求/响应)或--http-trace(开启 HTTP tracing)把交互过程打到日志里。

两个必须知道的限制:

1. 以下参数在 transfer 模式下不被支持,如果设置了会直接报错要求加--local:--max-concurrent-downloads、--print-chainid、--skip-verify、--tlscacert、--tlscert、--tlskey。也就是说传输模式下不能通过 client 侧 flag 跳过证书校验或自定义 TLS 证书,这类需求要么加--local,要么通过--hosts-dir的 hosts 配置处理。
2. Docker Schema 1 镜像(application/vnd.docker.distribution.manifest.v1+prettyjws)默认不再支持拉取。2.0 发布文档给出的恢复方式是给 containerd(以及 ctr,且必须加--local)设置环境变量CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE=1;但在 v2.1 之后的 client 本地拉取路径中,client/pull.go 对 Schema 1 media type 直接返回ErrNotImplemented。两个版本的说法以你实际运行版本的报错为准,建议直接重建镜像为 Docker Schema 2 或 OCI 格式。

push:推送镜像到 registry

ctr images push <remote> [<local>]

<remote>是目标 registry 的完整引用,<local>是本地已有的镜像名,省略时默认与<remote>相同。前置条件是本地镜像 manifest 必须先存在——push 不会现场构建镜像,它只是把已有内容推到 registry。先验证本地确实有这个镜像:

ctr images list

在REF、TYPE、DIGEST、SIZE、PLATFORMS列中确认要推的镜像在列。然后:

# 本地镜像名与远端引用同名 ctr images push myregistry.example.com:5000/app:v1 # 本地镜像名与远端引用不同 ctr images push myregistry.example.com:5000/app:v1 app:latest # 私有 registry 认证 ctr images push --user 'username:password' myregistry.example.com:5000/app:v1 # 本地是多架构镜像,只推特定平台 ctr images push --platform linux/arm64 myregistry.example.com:5000/app:v1

push 成功时命令无错误退出,进度树中各 blob 显示uploading直至complete。

transfer 模式下同样有一组参数需要--local才能用:--manifest、--manifest-type、--max-concurrent-uploaded-layers、--allow-non-distributable-blobs、--skip-verify、--tlscacert、--tlscert、--tlskey、--http-dump、--http-trace。默认行为下,标记为 non-distributable 的 blob 会被跳过(transfer 路径没有--allow-non-distributable-blobs这个开关)。

import:从本地归档导入镜像

ctr images import <in>

支持的归档格式:oci.v1、docker.v1.1、docker.v1.2。<in>是 tar 归档路径,传-表示从 stdin 读取,例如:

ctr images import image.tar tar -cf - -C /some/dir | ctr images import -

命名规则要注意:OCI 归档里可能只有不带仓库名的 tag。不提供--base-name时,导入的镜像会用import-<YYYY-MM-DD>日期前缀生成名称;提供--base-name后,只有匹配该前缀的引用会被导入。命令描述中给出的示例是:ctr images import --base-name foo/bar foobar.tar,若归档里含latest与匿名 digest 引用,会在 store 中创建foo/bar:latest和foo/bar@sha256:<digest>两个镜像。

常用参数:

# 指定前缀导入并解包 ctr images import --base-name foo/bar --snapshotter overlayfs image.tar # 按 digest 引用创建镜像 ctr images import --digests image.tar # 只导入不解包 ctr images import --no-unpack image.tar # 导入所有平台内容(transfer 模式下仍只解包默认或 --platform 指定的平台) ctr images import --all-platforms image.tar

--compress-blobs仅对 Docker 格式生效(创建 manifest 时压缩未压缩的 blob);--discard-unpacked-layers需要--local。导入完成后用ctr images list确认前缀下的镜像已出现。

export:导出镜像为归档

ctr images export <out> <image> ...

<out>是输出文件名,<image>可以跟多个。输出是 OCI archive 格式的 tar,当指定单一目标平台时归档里还会附一份 Docker 兼容的manifest.json。输出到 stdout 用-:

# 导出单个镜像到文件 ctr images export busybox.tar busybox:latest # 指定平台 ctr images export --platform linux/amd64 busybox.tar busybox:latest # 导出所有平台(要求 manifest list 里所有平台的镜像都已在本地可用) ctr images export --all-platforms all.tar multiarch:latest # 不带 Docker manifest.json,或跳过 non-distributable blob(如 Windows 层) ctr images export --skip-manifest-json --skip-non-distributable out.tar img:tag # 导出到 stdout ctr images export - busybox:latest > busybox.tar

配合 import 就构成一条离线迁移路径:在联网机器上ctr images export出归档,把文件拷到另一台机器,再ctr images import回去,目标端可用ctr images list核对导入结果。

验证与常见限制汇总

四条命令统一用ctr images list(别名ls)验证,输出列为REF TYPE DIGEST SIZE PLATFORMS LABELS:

ctr images list ctr images list --quiet # 只打印镜像引用

pull/import 后新镜像出现在列表中;export 的产物用文件是否存在(或喂给 import 再验证)确认。

容易踩的坑按文档归纳:

• transfer 模式与 local 模式参数不通用:pull、push、import 各自有一组参数只在--local下可用,设置错会收到明确的"--xxx" requires "--local" flag报错。
• Schema 1 镜像默认不可拉取,恢复方式受版本影响,见 pull 一节。
• pull 的--platform与--all-platforms互斥,同时指定会直接报错。
• unpack/diff/registry 镜像这三类 transfer 操作在本地插件中尚未实现,不要指望ctr的某条命令通过 transfer service 完成它们。

如果需要在拉取时做策略校验(例如强制镜像已签名或限定镜像名),transfer service 还支持 image verifier 插件,细节见 镜像校验文档。

【免费下载链接】containerdAn open and reliable container runtime项目地址: https://gitcode.com/GitHub_Trending/co/containerd