容器镜像服务 使用 TCR 触发器自动预热 Agent 沙箱镜像

一、操作场景

镜像预热通过 TCR 现有的触发器机制实现，适用于以下场景：

·推送即预热：向实例推送镜像后，满足触发规则的推送会自动发起 AGS 镜像预热调用，无需人工操作。

·按命名空间配置预热策略：每条规则必须选定一个命名空间，命名空间下的仓库可精确指定，也可使用正则表达式匹配。

·系统托管触发器：触发器类型选择 Agent 沙箱镜像预热，无需填写 URL 和 Header，也无需引入独立的触发服务。

注意：说明：

注意：TCR 仅记录并展示预热接口的调用结果（成功或失败），不同步预热任务状态。任务状态请在 Agent 沙箱的 加速中心 > 镜像预热页面查询。

二、前提条件

在配置 Agent 沙箱镜像预热前，你需要完成以下准备工作：

·实例版本与功能开通：该功能处于灰度发布阶段，相关 TCR 实例需提交工单升级后方可使用。Agent 沙箱镜像预热触发器类型仅对白名单用户可见。

·CAM 授权：预热动作依赖服务角色 TCR_QCSRole 绑定预设策略 QcloudAccessForAgsRoleInTCR，以授权调用 CreatePreCacheImageTask 等接口。首次提交配置时，控制台会自动弹出授权窗口；如子账号无 CAM 授权权限，需联系主账号完成授权。

·地域要求：预热目标地域为 AGS 所在地域。TCR 实例与 AGS 需保持同地域，不支持跨地域预热。

·命名空间：目标 TCR 实例中已创建至少一个命名空间，预热规则以命名空间为维度配置。

五、步骤1：进入触发器页面

1. 登录 容器镜像服务控制台，进入目标实例详情页。

2. 在左侧导航栏选择触发器。

六、步骤2：新建触发器

单击新建触发器，按以下参数填写配置：

仓库名称和版本 Tag 的填写方式请参考下文 配置仓库名称与版本 Tag 匹配规则。

七、步骤3：完成授权并提交配置

单击确认提交配置：

·若 TCR_QCSRole 尚未绑定预设策略，将弹出 CAM 授权窗口，请按提示完成授权。该操作需由主账号或具备 CAM 权限的子账号确认。

·授权失败时，提交会被阻止，避免创建无法成功调用预热接口的规则。

八、配置仓库名称与版本 Tag 匹配规则

触发规则中的仓库名称和版本 Tag 使用正则表达式匹配：

·仓库名称匹配的是完整路径，即 命名空间/仓库，可包含多级路径，因此需要带命名空间前缀。

·匹配采用非锚定的子串匹配方式。需要精确限定时，请使用 ^ 和 $ 锚定。

·. 表示任意字符。匹配字面量点号（如版本号分隔符）时，需转义为 \\.。

以下写法均已在 TCR 实例上实测验证，以命名空间 demo 为例：

注意：*、**、?、{a,b} 在此不是通配符语法，请勿直接套用同步规则或版本保留规则的通配符写法。

十、步骤1：推送镜像触发预热

配置完成后，使用 docker push 向实例推送镜像。任何满足触发规则的镜像推送都会自动发起预热调用，无需人工操作。

十一、步骤2：查看触发日志

在控制台的触发器页面，单击对应触发器行的触发日志，查看每次推送的调用记录与结果。

注意：说明：

注意：触发日志中的调用结果仅代表预热任务发起是否成功，不代表预热任务已完成。

十二、步骤3：查询 AGS 预热任务状态

预热任务状态请在 AGS 侧查询。你可前往 API Explorer，调用 DescribePreCacheImageTask 接口查看任务状态。

十三、通过云 API 配置触发器

除控制台外，你也可通过云 API 创建、查询或修改镜像预热触发器，并查询触发日志。

十四、创建镜像预热触发器

调用 CreateWebhookTrigger 接口，请求参数示例如下：

{ "RegistryId": "tcr-ejwv1234", "Namespace": "nginx-test", "Product": "ags", "PreheatRegion": "ap-guangzhou", "Trigger": { "Name": "preheat-demo", "Targets": [], "EventTypes": ["pushImage"], "Condition": ".*", "Enabled": true, "Description": "Agent 沙箱镜像预热示例" }}

十五、查询触发器列表

调用 DescribeWebhookTrigger 接口，请求参数示例如下：

{ "RegistryId": "tcr-ejwv1234", "Product": "ags", "Limit": 20, "Offset": 1}

十六、查询触发日志

调用 DescribeWebhookTriggerLog 接口，请求参数示例如下：

{ "RegistryId": "tcr-ejwv1234", "Namespace": "nginx-test", "Id": 38, "Limit": 20, "Offset": 1}

十七、修改触发器

调用 ModifyWebhookTrigger 接口，请求参数示例如下：

{ "RegistryId": "tcr-ejwv1234", "Namespace": "nginx-test", "Product": "ags", "PreheatRegion": "ap-shanghai", "Trigger": { "Id": 38, "Name": "preheat-demo", "Targets": [], "EventTypes": ["pushImage"], "Condition": ".*", "Enabled": true }}

注意：说明：

注意：上述请求中的实例 ID、命名空间、触发器 ID 和地域均为示例值，请替换为实际配置。创建和修改触发器时，PreheatRegion 均需与目标 TCR 实例保持同地域。

十八、关键参数说明

20、常见问题与排查