Agent Runtime 为 Agent 集群开启镜像加速

当 Agent 使用包含 Python 依赖、浏览器或开发工具的大镜像时，新节点首次运行任务往往需要等待镜像下载和解压。镜像加速通过提前转换镜像、在节点上按需读取数据，减少这一阶段的等待，适合扩容后启动 Agent、首次部署大镜像和批量创建沙箱等场景。
开启后，业务继续使用原始镜像地址和原有的镜像拉取凭证，无需将工作负载中的 image 改为转换后的制品地址。镜像加速不改变您选择的容器或沙箱运行时，也不会省去应用初始化、模型加载和健康检查的时间。
适用场景
场景
使用建议
新节点首次启动大镜像，启动时只读取其中部分文件
优先评估镜像加速，比较首次任务可执行时间。
同时启动多个使用相同镜像的 Agent
分别测试首批和后续批次；同一节点上的任务会共享缓存。
镜像已在节点缓存，或镜像本身较小
加速收益可能有限，应与原有启动方式对比。
启动时遍历大量文件或读取完整模型
按需读取可能把等待转移到应用运行阶段，应同时测试首次业务请求。
开始前准备
准备存放业务镜像的 TCR 实例。在 TCR 控制台的镜像加速页面核对该实例是否已开通 Agent 集群使用的 EROX 能力；没有对应入口或实例不可选时，通过腾讯云工单联系技术支持，提供实例 ID、地域和访问域名。普通镜像加速规则不等于已开通 EROX。
确认目标节点的操作系统、内核和 containerd 版本支持该加速组件；镜像架构应与节点一致。多架构镜像需完成对应平台的转换。
在 TCR 控制台的访问控制 > 内网访问中接入 Agent 集群所在 VPC，选择子网分配内网解析地址，并开启默认域名的自动解析。内网接入覆盖整个 VPC，所选子网仅用于分配地址。等待链路正常及解析生效后，从目标节点确认仓库域名解析到页面显示的内网 IP，并能通过 HTTPS 连接。准备源仓库的拉取凭据。按需加载在运行期间仍可能读取仓库数据，应持续保持网络和凭证可用。
准备一个独立测试工作负载，先验证业务结果和首次请求耗时，再扩大使用范围。
镜像转换需要时间，生成的加速制品也会占用仓库存储空间；加速制品不一定比原镜像小。
在 TCR 镜像加速页面，如果按钮不可操作，将鼠标移到按钮上查看原因。提示“仅对高级版实例开放”时，说明当前入口受实例规格限制。
步骤一：配置镜像转换规则
1. 登录 TCR 控制台，进入镜像加速，选择已开通 EROX 能力的实例地域和实例。
2. 添加镜像加速规则，填写规则名称，选择业务镜像所在的命名空间，并配置仓库名称和版本 Tag 的匹配条件。首次使用建议只匹配测试仓库和测试版本。
3. 使用规则验证功能检查业务镜像地址是否匹配，保存并启用规则。
4. 按仓库的推送指引上传一个匹配规则的新镜像版本，等待该版本转换成功，并确认转换结果对应目标节点的 CPU 架构。
规则针对匹配的镜像推送触发转换。仅启用规则，不代表仓库中已有的所有版本都已转换；首次验证请向测试仓库推送一个匹配规则的新版本，按转换任务确认成功。已有版本需使用实例提供的补转换入口；没有该入口时，联系技术支持确认支持方式，不修改正在使用的版本来触发测试。转换完成后，记录源镜像版本和 digest，后续部署仍填写源镜像地址。
新建集群按以下步骤开启镜像加速。已安装镜像加速组件、需要更换关联 TCR 实例的集群，按下文“更换关联的 TCR 实例”操作；该流程不用于为尚未安装组件的集群首次安装镜像加速。
步骤二：在创建 Agent 集群时开启镜像加速
1. 登录 Agent 集群控制台，在集群总览单击新建 Agent 集群。
2. 在基础与网络配置中开启镜像加速，选择步骤一使用的 TCR 实例。
3. 完成地域、网络及其他必填配置，提交创建，并按照 创建集群和节点池 添加用于运行 Agent 的节点。
4. 待节点就绪后，检查镜像加速组件和目标节点的安装结果，再部署测试工作负载。
以下为安装结果的只读检查。先参考 通过 Kubernetes API 访问 Agent 集群 取得访问配置。准备 Helm 3，TARGET_NODE 填写实际节点名称。
export KUBECONFIG='/absolute/path/to/kubeconfig'
export TARGET_NODE='<目标节点名称>'
﻿
helm status erox-node --kubeconfig="$KUBECONFIG" -n kube-system
kubectl --kubeconfig="$KUBECONFIG" -n kube-system get daemonset \\
  -l app.kubernetes.io/instance=erox-node -o wide
﻿
kubectl --kubeconfig="$KUBECONFIG" get node "$TARGET_NODE" \\
  -o jsonpath='{.metadata.labels.agc\\.cloud\\.tencent\\.com/erox}{"\\n"}{.metadata.labels.erox\\.tencentcloud\\.com/enabled}{"\\n"}{.metadata.labels.erox\\.tencentcloud\\.com/ready}{"\\n"}'
Helm 发布状态应为 deployed，安装器 DaemonSet 的目标实例应就绪。Agent 集群默认安装的节点通过 agc.cloud.tencent.com/erox=true 选中；独立安装方式可能使用 erox.tencentcloud.com/enabled=true，按实际安装器的节点选择条件核对。目标节点的 erox.tencentcloud.com/ready 应为 true，不要仅因其中一种启用标签不存在就判断安装失败。如果未满足，先检查安装器 Pod 的日志、事件和节点状态；不要手动写入 ready 标签。扩容后也要检查新增节点，已有节点安装成功不代表新节点已经可以加速。
步骤三：使用原始镜像运行 Agent
创建测试工作负载，核对以下配置：
配置
填写方式
镜像地址
填写步骤一完成转换的原始镜像地址，保持版本不变。
私有仓库凭证
使用原有源镜像的拉取凭证；凭证应位于工作负载所在命名空间。
运行时
保留业务原有运行时选择；使用 Cube 的任务仍需具备可用的 Cube 运行时。
调度范围
将测试工作负载调度到已完成镜像加速安装的目标节点，保留业务所需的其他调度约束。
启动命令与健康检查
使用真实业务命令和就绪条件，验证任务能执行并返回正确结果。
部署后记录命名空间和 Pod 名称，执行以下只读检查：
export TEST_NAMESPACE='<测试命名空间>'
export TEST_POD='<测试 Pod 名称>'
﻿
kubectl --kubeconfig="$KUBECONFIG" -n "$TEST_NAMESPACE" get pod "$TEST_POD" -o wide
kubectl --kubeconfig="$KUBECONFIG" -n "$TEST_NAMESPACE" describe pod "$TEST_POD"
kubectl --kubeconfig="$KUBECONFIG" -n "$TEST_NAMESPACE" logs "$TEST_POD" --all-containers=true
确认 Pod 落在目标节点、镜像版本正确，并完成一次真实任务。转换任务失败时，先查看失败信息，检查源镜像访问权限、平台架构和转换规则，不把失败任务当作已完成转换。仅看到 Running 或 Ready，还不能判断本次启动是否使用了镜像加速。
步骤四：确认加速生效并比较效果
将本次 Pod 的节点、创建时间和源镜像 digest，与节点上的加速记录对应起来。在有节点运维权限的终端登录实际运行该 Pod 的节点，检查服务状态及本次启动时段的日志：
sudo systemctl is-active erox-tcr-adapter erox-node-snapshotter containerd kubelet
sudo journalctl -u erox-tcr-adapter -u erox-node-snapshotter \\
  --since '10 min ago' --no-pager
核对日志中本次镜像对应的加速制品发现与挂载结果。监控指标 erox_snapshotter_accelerated_mount_total 的增长可辅助确认新增加速挂载，但其他任务也会影响该计数，复用已有挂载时计数可能不增长。应结合镜像身份、节点和时间判断本次任务，不能仅凭节点累计值认定命中。
比较效果时，保持源镜像 digest、节点规格、业务命令、资源配置、运行时和并发量一致，分别记录：
检查项
衡量内容
镜像准备耗时
镜像拉取与准备阶段的等待。
首条业务命令开始时间
容器启动后多久可以实际执行代码。
应用就绪时间
包含语言运行时、依赖和应用初始化的完整等待。
首次任务耗时与结果
验证按需读取后续数据时的影响，并核对成功率。
冷缓存和暖缓存结果分别统计；同一节点并发使用相同镜像的多个任务不是多个独立冷启动样本。不要在共享业务节点上清空缓存来构造测试。
更换关联的 TCR 实例
业务镜像迁移到新的 TCR 实例后，需要同步修改集群镜像加速组件关联的仓库域名。在 TCR 控制台切换查看实例，不会修改集群配置。
1. 准备新实例
确认新实例已开通 EROX、测试镜像已转换成功，并已接入集群所在 VPC。为工作负载准备新仓库的拉取凭据。镜像、转换规则和凭据不会随关联变更自动迁移，原实例应保留到验证完成。
2. 修改关联域名
连接集群，在运维终端使用 Helm 3 更新已安装的 erox-node 组件，无需调用云 API。操作账号需具备组件管理及节点维护权限。准备与集群当前组件同版本的原始 Chart 安装包；没有安装包时，通过腾讯云工单获取，不更换组件版本。
先查看当前版本和参数，将输出保存为备份，并记录原来的 registry.host：
export KUBECONFIG='/absolute/path/to/kubeconfig'
helm list -n kube-system --filter '^erox-node$'
helm get values erox-node -n kube-system
将下列路径替换为同版本 Chart 安装包路径，域名替换为新实例访问域名，只填域名，不带 https:// 或镜像路径：
helm upgrade erox-node '<同版本 Chart 安装包路径>' \\
  -n kube-system --reuse-values \\
  --dry-run=client --hide-secret \\
  --set-string registry.host='<新 TCR 实例访问域名>'
核对预览只变更关联域名及其派生配置，其他参数不变后，去掉 --dry-run=client --hide-secret 两个选项 再执行。命令失败时先停止处理。
3. 逐节点应用
安排维护窗口，一次处理一个节点：
1. 暂停该节点调度，迁移相关业务，确认没有仍在使用的 EROX 挂载。
2. 检查 EROX 安装器 DaemonSet 的更新策略为 OnDelete、模板域名已更新；其他策略不要套用此流程。
3. 只删除该节点的 EROX 安装器 Pod，等待 DaemonSet 重建，检查新 Pod 的日志及就绪状态。
4. 确认节点上的 /etc/erox-tcr-adapter/adapter.toml 使用新域名，erox-tcr-adapter、erox-node-snapshotter、containerd、kubelet 四项服务均正常，节点和加速状态均就绪，再恢复原先可调度的节点。
任一步异常，停止处理后续节点。不要批量重建安装器，也不要强制删除业务挂载。
4. 验证与回退
使用新实例中已转换的源镜像地址和对应拉取凭据运行一个测试 Agent，按本文“确认加速生效并比较效果”检查业务结果及加速挂载，再迁移其他业务。Pod 能运行不等于命中加速。
需要回退时，将第二步命令的域名改为备份中的原域名，先预览、再执行，并按第三步逐节点应用。已迁移的工作负载还需恢复原镜像地址和凭据。
通过 Helm 更新后，TKE 组件管理中保存的参数可能仍为旧值。后续在控制台升级或重装组件时，需保留新的关联域名。
一次功能验证的结果
使用一个 Linux amd64 测试镜像，在安装 EROX 的节点上创建 runtimeClassName: cube 的 Pod，并执行文件校验命令，得到以下结果：
验证项
结果
TCR 内网接入与解析
接入集群所在 VPC 并开启自动解析后，6 个节点均通过内网连接 Registry，原先的连接超时消失。
私有镜像与 Cube 运行
使用源镜像地址及拉取凭据，Pod 成功运行，业务命令和文件校验完成。
EROX 加速制品与挂载
测试镜像推送后未发现对应 EROX 制品；节点日志显示 route=native、metadata_missing，未确认加速挂载。
启动性能对比
未进行加速前后对比；普通路径运行成功不作为加速效果。
本次验证确认了内网访问和 Cube 普通启动路径，尚未通过镜像加速验收。遇到相同情况，应先确认目标 TCR 实例的 EROX 转换服务与规则，再检查转换成功的制品，最后重新创建测试 Pod 验证挂载；不要仅凭组件 Ready 或 Pod Running 判断加速生效。
常见问题
现象
检查与处理
镜像推送后没有转换结果
检查实例是否开通 EROX、规则是否启用，以及命名空间、仓库和版本是否匹配；确认本次推送已经触发转换。
节点未完成加速安装
检查 Helm 发布状态、安装器 Pod 的日志与事件、节点启用标签及操作系统和 containerd 兼容性。
Pod 一直 Pending
检查节点选择条件、污点、可调度状态和剩余资源，确认目标节点能够接收该任务。
私有镜像拉取失败
检查命名空间中的拉取凭证、仓库访问权限和节点网络；不要将鉴权失败视为正常回退。
镜像可以运行，但没有加速记录
核对实际节点、镜像版本、平台及转换结果；未发现可用加速制品的普通 OCI 镜像可能走常规路径。
已发现制品却启动失败
检查制品关联信息和完整性及访问权限；制品校验失败不代表会自动回退成功。
容器启动快，但首次任务仍慢
检查应用是否全量扫描镜像文件、导入大量依赖或加载模型，同时分析首次读取和应用初始化耗时。
﻿

场景	使用建议
新节点首次启动大镜像，启动时只读取其中部分文件	优先评估镜像加速，比较首次任务可执行时间。
同时启动多个使用相同镜像的 Agent	分别测试首批和后续批次；同一节点上的任务会共享缓存。
镜像已在节点缓存，或镜像本身较小	加速收益可能有限，应与原有启动方式对比。
启动时遍历大量文件或读取完整模型	按需读取可能把等待转移到应用运行阶段，应同时测试首次业务请求。

配置	填写方式
镜像地址	填写步骤一完成转换的原始镜像地址，保持版本不变。
私有仓库凭证	使用原有源镜像的拉取凭证；凭证应位于工作负载所在命名空间。
运行时	保留业务原有运行时选择；使用 Cube 的任务仍需具备可用的 Cube 运行时。
调度范围	将测试工作负载调度到已完成镜像加速安装的目标节点，保留业务所需的其他调度约束。
启动命令与健康检查	使用真实业务命令和就绪条件，验证任务能执行并返回正确结果。

检查项	衡量内容
镜像准备耗时	镜像拉取与准备阶段的等待。
首条业务命令开始时间	容器启动后多久可以实际执行代码。
应用就绪时间	包含语言运行时、依赖和应用初始化的完整等待。
首次任务耗时与结果	验证按需读取后续数据时的影响，并核对成功率。

验证项	结果
TCR 内网接入与解析	接入集群所在 VPC 并开启自动解析后，6 个节点均通过内网连接 Registry，原先的连接超时消失。
私有镜像与 Cube 运行	使用源镜像地址及拉取凭据，Pod 成功运行，业务命令和文件校验完成。
EROX 加速制品与挂载	测试镜像推送后未发现对应 EROX 制品；节点日志显示 `route=native`、`metadata_missing`，未确认加速挂载。
启动性能对比	未进行加速前后对比；普通路径运行成功不作为加速效果。

现象	检查与处理
镜像推送后没有转换结果	检查实例是否开通 EROX、规则是否启用，以及命名空间、仓库和版本是否匹配；确认本次推送已经触发转换。
节点未完成加速安装	检查 Helm 发布状态、安装器 Pod 的日志与事件、节点启用标签及操作系统和 containerd 兼容性。
Pod 一直 Pending	检查节点选择条件、污点、可调度状态和剩余资源，确认目标节点能够接收该任务。
私有镜像拉取失败	检查命名空间中的拉取凭证、仓库访问权限和节点网络；不要将鉴权失败视为正常回退。
镜像可以运行，但没有加速记录	核对实际节点、镜像版本、平台及转换结果；未发现可用加速制品的普通 OCI 镜像可能走常规路径。
已发现制品却启动失败	检查制品关联信息和完整性及访问权限；制品校验失败不代表会自动回退成功。
容器启动快，但首次任务仍慢	检查应用是否全量扫描镜像文件、导入大量依赖或加载模型，同时分析首次读取和应用初始化耗时。

为 Agent 集群开启镜像加速

本页目录：

适用场景

开始前准备

步骤一：配置镜像转换规则

步骤二：在创建 Agent 集群时开启镜像加速

步骤三：使用原始镜像运行 Agent

步骤四：确认加速生效并比较效果

更换关联的 TCR 实例

1. 准备新实例

2. 修改关联域名

3. 逐节点应用

4. 验证与回退

一次功能验证的结果

常见问题