soci-snapshotter常见问题解答：从入门到精通

soci-snapshotter常见问题解答：从入门到精通

【免费下载链接】soci-snapshotterA containerd snapshotter plugin which enables standard OCI images to be lazily loaded without requiring a build-time conversion step.项目地址: https://gitcode.com/gh_mirrors/so/soci-snapshotter

soci-snapshotter是一个containerd快照器插件，它能让标准OCI镜像实现延迟加载，无需构建时转换步骤。本文将解答使用soci-snapshotter过程中的常见问题，帮助新手快速上手并精通这个强大工具。

安装与配置相关问题

如何安装soci-snapshotter？

安装soci-snapshotter需要先确保系统中已安装containerd。推荐通过源码编译安装，具体步骤如下：

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/so/soci-snapshotter
2. 进入项目目录：cd soci-snapshotter
3. 编译安装：make install

安装完成后，需要配置containerd以使用soci-snapshotter作为快照器。

配置文件在哪里？

soci-snapshotter的默认配置文件路径为/etc/soci-snapshotter-grpc/config.toml。可以通过修改此文件来配置快照器的各种参数，如metrics地址、调试地址等。

如何启用 metrics 收集？

要启用metrics收集，需要在配置文件中设置metrics_address。例如：

metrics_address="localhost:8000"

配置完成后，重启soci-snapshotter，就可以通过curl localhost:8000/metrics获取metrics数据了。

镜像拉取相关问题

如何判断镜像是否使用了延迟加载？

soci-snapshotter在拉取镜像时会输出日志，通过查看日志可以判断镜像的拉取方式。如果日志中出现以下信息，则表示使用了延迟加载：

• using provided soci index digest：使用显式提供的SOCI索引摘要
• using soci v2 index annotation：通过SOCI-enabled镜像使用SOCI索引清单v2
• using soci v1 index via referrers API：通过Referrers API使用SOCI索引清单v1

如果日志中出现deferring to container runtime，则表示没有使用SOCI索引，而是提前拉取了镜像。

为什么没有实现延迟加载？

如果发现所有层都被拉取，或者带有zTOC的层没有创建FUSE挂载，可能是以下原因：

• 层没有关联的zTOC：日志中会出现skipping mounting layer <layer_digest> as FUSE mount: no zTOC for layer。这通常是因为层大小未达到创建SOCI索引/zTOCs时设定的最小层大小标准。
• 无法获取SOCI artifacts：日志中会出现unable to fetch SOCI artifacts: <error>。最常见的原因是无法对远程 registry 进行身份验证。可以使用docker登录来解决：

  export ECR_PASS=$(aws ecr get-login-password --region <region>) echo $ECR_PASS | sudo docker login -u AWS --password-stdin $ECR_REGISTRY

拉取镜像时间过长怎么办？

如果拉取镜像时间异常，可以从以下几个方面排查：

• 查看日志中是否有failed to resolve layer (timeout)，这表示远程挂载可能因层解析问题而超时。默认远程挂载超时时间为30秒。
• 检查operation_duration_mount指标，看挂载层是否花费了异常长的时间。正常情况下，拉取应该只需要几秒钟，如果超过3-5秒可能存在问题。
• 检查operation_duration_init_metadata_store指标，看解析zTOC和初始化元数据db是否过慢。
• 查看日志中是否有HTTP失败代码，格式为Received status code。

容器运行相关问题

什么是背景获取（Background Fetching）？

背景获取是snapshotter启动时初始化的功能，它会在拉取期间/之后执行网络请求来获取数据。可以通过以下指标来分析背景获取器：

• background_span_fetch_failure_count：背景获取失败的次数
• background_span_fetch_count：背景获取器获取的跨度数量

如果background_span_fetch_count为0，可能表示存在网络故障。可以在日志中查找Retrying request来确定远程 registry 返回的错误和响应。

出现FUSE读取失败怎么办？

运行中的容器会产生许多读取请求，如果请求的文件位于延迟加载的层中，读取请求会通过层的FUSE文件系统路由。如果出现FUSE读取失败，可以查看日志中是否有failed to read the file或unexpected copied data size for on-demand fetch。

常见的FUSE读取失败原因及解决方法：

• 数据损坏：日志中会出现span digests do not match。可以通过soci ztoc info <digest>命令检查zTOC是否包含适当的数据。
• 网络故障：snapshotter在从远程 registry 获取跨度（数据）时包含自定义重试逻辑，默认最多尝试9次。可以在日志中查找retrying request来确定错误，或检查operation_duration_remote_registry_get指标了解GET请求的耗时。

日常维护相关问题

如何删除镜像？

删除镜像会额外删除所有相关联的快照。使用sudo nerdctl image rm [image tag]命令应该会在删除镜像本身之前删除与该镜像相关联的所有快照。可以通过sudo nerdctl image ls确认镜像是否已被删除。

如何重启snapshotter？

虽然建议优雅地停止/重启进程，但有时可能需要直接终止进程。如果之前加载的快照仍然存在，可能会导致无法正常启动snapshotter。例如，如果从需要凭据的存储库拉取后停止snapshotter，启动时凭据已过期，snapshotter将无法正常启动。

可以在/etc/soci-snapshotter-grpc/config.toml中设置allow_invalid_mounts_on_restart=true来绕过许多与已加载快照相关的错误。但请注意，这可能会使snapshotter处于不稳定状态，直到当前加载的快照被删除。

如何创建干净的环境？

如果所有其他方法都失败，可以通过以下步骤创建干净的环境（注意：这将清除整个容器存储，请确保备份重要文件）：

sudo killall -2 soci-snapshotter-grpc # SIGINT允许更优雅的清理，可以省略-2标志发送SIGTERM # 如有必要，卸载任何剩余的fuse挂载，尽管向守护进程发送SIGINT应该会自动处理 sudo rm -rf /var/lib/containerd sudo rm -rf /var/lib/soci-snapshotter-grpc sudo systemctl restart containerd sudo soci-snapshotter-grpc

调试工具相关问题

有哪些有用的SOCI CLI命令？

以下是一些在调试SOCI索引/zTOCs问题时有用的SOCI CLI命令：

如何进行CPU分析？

可以使用Golang的pprof工具对snapshotter进行分析。要启用分析，必须在snapshotter的配置文件（默认：/etc/soci-snapshotter-grpc/config.toml）中设置debug_address：

debug_address = "localhost:6060"

配置完成后，可以向/debug/pprof/profile端点发送GET请求来获取snapshotter的CPU分析。可以指定可选参数seconds来限制结果的时间跨度：

curl http://localhost:6060/debug/pprof/profile?seconds=40 > out.pprof

然后使用Go CLI提供的pprof工具在Web浏览器中可视化数据：

go tool pprof -http=:8080 out.pprof

总结

通过本文的常见问题解答，相信你已经对soci-snapshotter有了更深入的了解。如果你在使用过程中遇到其他问题，可以查阅项目的官方文档，或在社区寻求帮助。soci-snapshotter作为一个强大的containerd快照器插件，能够有效提升镜像加载效率，希望本文能帮助你更好地使用它。

【免费下载链接】soci-snapshotterA containerd snapshotter plugin which enables standard OCI images to be lazily loaded without requiring a build-time conversion step.项目地址: https://gitcode.com/gh_mirrors/so/soci-snapshotter