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可以是不同对象,组合决定操作类型:SourceDestination操作本地实现版本RegistryImage Storepull1.7Image StoreRegistrypush1.7Object stream (Archive)Image Storeimport1.7Image StoreObject stream (Archive)export1.7Image StoreImage Storetag1.7Object stream (Layer)Mount/Snapshotunpack未实现Mount/SnapshotObject stream (Layer)diff未实现RegistryRegistrymirror registry image未实现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 keyvalue ref传输排障时可以用--http-dump(dump 与 registry 的全部 HTTP 请求/响应)或--http-trace(开启 HTTP tracing)把交互过程打到日志里。两个必须知道的限制:以下参数在 transfer 模式下不被支持,如果设置了会直接报错要求加--local:--max-concurrent-downloads、--print-chainid、--skip-verify、--tlscacert、--tlscert、--tlskey。也就是说传输模式下不能通过 client 侧 flag 跳过证书校验或自定义 TLS 证书,这类需求要么加--local,要么通过--hosts-dir的 hosts 配置处理。Docker Schema 1 镜像(application/vnd.docker.distribution.manifest.v1prettyjws)默认不再支持拉取。2.0 发布文档给出的恢复方式是给 containerd(以及 ctr,且必须加--local)设置环境变量CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE1;但在 v2.1 之后的 client 本地拉取路径中,client/pull.go 对 Schema 1 media type 直接返回ErrNotImplemented。两个版本的说法以你实际运行版本的报错为准,建议直接重建镜像为 Docker Schema 2 或 OCI 格式。push:推送镜像到 registryctr 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:v1push 成功时命令无错误退出,进度树中各 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/barsha256: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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 containerd 2.x 如何使用 transfer service 完成镜像的 pull、push、import 与 export
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可以是不同对象,组合决定操作类型:SourceDestination操作本地实现版本RegistryImage Storepull1.7Image StoreRegistrypush1.7Object stream (Archive)Image Storeimport1.7Image StoreObject stream (Archive)export1.7Image StoreImage Storetag1.7Object stream (Layer)Mount/Snapshotunpack未实现Mount/SnapshotObject stream (Layer)diff未实现RegistryRegistrymirror registry image未实现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 keyvalue ref传输排障时可以用--http-dump(dump 与 registry 的全部 HTTP 请求/响应)或--http-trace(开启 HTTP tracing)把交互过程打到日志里。两个必须知道的限制:以下参数在 transfer 模式下不被支持,如果设置了会直接报错要求加--local:--max-concurrent-downloads、--print-chainid、--skip-verify、--tlscacert、--tlscert、--tlskey。也就是说传输模式下不能通过 client 侧 flag 跳过证书校验或自定义 TLS 证书,这类需求要么加--local,要么通过--hosts-dir的 hosts 配置处理。Docker Schema 1 镜像(application/vnd.docker.distribution.manifest.v1prettyjws)默认不再支持拉取。2.0 发布文档给出的恢复方式是给 containerd(以及 ctr,且必须加--local)设置环境变量CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE1;但在 v2.1 之后的 client 本地拉取路径中,client/pull.go 对 Schema 1 media type 直接返回ErrNotImplemented。两个版本的说法以你实际运行版本的报错为准,建议直接重建镜像为 Docker Schema 2 或 OCI 格式。push:推送镜像到 registryctr 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:v1push 成功时命令无错误退出,进度树中各 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/barsha256: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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考