使用 Harbor Event Triggers
目录
概述核心功能支持的事件类型基本事件信息基本变量(所有事件通用)1. Push Artifact 事件Push Artifact 事件变量2. Pull Artifact 事件Pull Artifact 事件变量3. Delete Artifact 事件Delete Artifact 事件变量4. Scanning Completed 事件Scanning Completed 事件变量配置指南处理可选字段前提条件通过 Harbor UI 配置 WebhookPipeline Trigger 配置示例使用场景使用场景 1:自动化镜像部署使用场景 2:安全策略强制执行使用场景 3:制品生命周期管理使用场景 4:多阶段 CI/CD Pipeline推荐设置概述
Harbor Event Triggers 允许您通过 Harbor 的 Webhook 事件自动触发 Tekton pipeline。它支持多种事件类型,包括 artifact 推送、拉取、删除和扫描完成,从而帮助您为容器镜像和 OCI chart 构建完整的 CI/CD 自动化工作流。
核心功能
- 多事件类型支持:支持多种 Harbor 事件,例如 Push Artifact、Pull Artifact、Delete Artifact 和 Scanning Completed。
- 标准化触发器绑定:提供标准化的 ClusterTriggerBindings,确保跨平台的一致性。
- 灵活的参数映射:自动从 Harbor 事件中提取关键信息,供 pipeline 参数使用。
- 多 artifact 类型支持:同时支持容器镜像和 OCI chart。
支持的事件类型
基本事件信息
所有输出变量都可用于 pipeline 参数映射。您可以使用 $(tt.params.<param name>) 访问参数值。
基本变量(所有事件通用)
处理可选字段:artifact-tag 字段为可选字段;如果 artifact 仅通过 digest 引用,则 payload 中可能缺少该字段。repository-date-created 字段可用于推送和拉取事件,但不适用于删除和扫描事件。
重要提示:如果 TriggerBinding 中引用的字段可能缺少于 payload,您必须在 TriggerTemplate 中为该参数设置 default 值。否则,字段缺失时触发器将失败。例如,如果 artifact-tag 可能缺失,请在 TriggerTemplate 的参数定义中添加 default: ""。
1. Push Artifact 事件
当 artifact(容器镜像或 OCI chart)推送到 Harbor 仓库时触发。适用于:
- 自动化镜像构建和部署
- 镜像验证和测试
- 自动化标记和版本控制
- 多阶段构建 pipeline
Push Artifact 事件变量
上述所有基本变量也可用。
2. Pull Artifact 事件
当从 Harbor 仓库拉取 artifact 时触发。适用于:
- 使用情况跟踪和分析
- 安全监控
- 资源消耗跟踪
- 部署验证
Pull Artifact 事件变量
上述所有基本变量也可用。
3. Delete Artifact 事件
当从 Harbor 仓库删除 artifact 时触发。适用于:
- 清理自动化
- 审计日志记录
- 资源管理
- 合规性跟踪
Delete Artifact 事件变量
上述所有基本变量均可用。请注意,repository-date-created 不适用于删除事件。
4. Scanning Completed 事件
当 artifact 的漏洞扫描完成时触发。适用于:
- 安全策略实施
- 自动化安全检查
- 漏洞报告
- 自动化修复工作流
Scanning Completed 事件变量
上述所有基本变量均可用。请注意,repository-date-created 不适用于扫描事件。
scan_overview 字段的结构取决于扫描类型(SBOM、漏洞检查)。其键为 MIME 类型,例如 application/vnd.security.vulnerability.report; version=1.1,其中包含点号和空格。要在 TriggerBinding 中读取此类键下的字段,请使用反斜杠转义键中的每个点号和空格,例如 $(body.event_data.resources[0].scan_overview.application/vnd\.security\.vulnerability\.report;\ version=1\.1.scan_status)。如果不使用反斜杠,将其作为普通路径或放在 ['…'] 中,EventListener 会记录 failed to replace JSONPath value for param <name>: … application/vnd is not found,且 Trigger 不会创建资源,尽管发送方仍会收到 HTTP 202。当 TriggerTemplate 参数没有 default 时也是如此。如果存在该字段(对于可选字段,建议设置),Triggers 会静默使用默认值,不产生错误,并且运行将获得默认值,而不是扫描字段。在 CEL interceptor 中,请将该键用作字符串索引:body.event_data.resources[0].scan_overview["application/vnd.security.vulnerability.report; version=1.1"].scan_status。如果需要不同扫描类型的结果,请为每种类型创建单独的绑定。
有关事件结构的更多详细信息,请参阅 Harbor 官方 Webhook 文档。
配置指南
处理可选字段
Harbor 事件中的某些字段可能是可选的,或根据事件类型或 artifact 的引用方式而缺失。例如:
artifact-tag:如果 artifact 仅通过 digest 引用,则可能缺失repository-date-created:在 push 和 pull 事件中可用,但在 delete 和扫描事件中不可用
重要事项:使用引用可选字段的 ClusterTriggerBindings 时,必须在 TriggerTemplate 中为这些参数提供默认值。如果 payload 中缺少某个字段且未提供默认值,trigger 将因 JSONPath 解析错误而失败。
示例:要处理可选的 artifact-tag 字段,请按如下方式配置 TriggerTemplate:
这样,如果 Harbor 事件 payload 中缺少 tag 字段,trigger 将使用空字符串,而不会失败。
前提条件
- 环境中已创建
EventListener,并且能够在目标 namespace 中处理Trigger。有关详细信息,请联系平台管理员。 - Harbor 可以访问上述
EventListener。 - 已创建所需的
Pipeline以及必要的运行配置。 - 你拥有修改 Harbor 项目 Webhook 设置的权限。
通过 Harbor UI 配置 Webhook
- 访问 Harbor 项目设置。
- 导航到 Webhooks。
- 点击 New Webhook。
- 配置 webhook:
- Name:输入描述性名称(例如
tekton-webhook) - Endpoint URL:输入 EventListener URL,例如: 或
- Auth Header:设置身份验证标头,并在 Trigger 中进行检查,具体如推荐设置和Webhook Secret 身份验证中所述。
- Skip Certificate Verification:保持禁用状态。启用验证后,Harbor 必须信任签发 listener 证书的 CA,否则投递将失败。项目 webhook 设置中没有用于配置此项的字段:受信任的 CA 会添加到 Harbor 安装中,通常由 Harbor 管理员完成;请参阅 Harbor 文档。仅在使用自签名证书进行测试时启用此选项。
- Name:输入描述性名称(例如
- 根据需要选择事件类型:
- Push Artifact:在 artifact 被推送时触发
- Pull Artifact:在 artifact 被拉取时触发
- Delete Artifact:在 artifact 被删除时触发
- Scanning Completed:在漏洞扫描完成时触发
- 点击 Save。
Pipeline Trigger 配置示例
如果目标是通过 trigger 实现持续集成,并满足以下要求:
- 在 image 被推送时自动触发自动构建和部署。
- 在扫描完成时自动触发安全检查。
事件类型过滤:如果 Harbor webhook 配置为发送多种事件类型(例如同时发送 Push Artifact 和 Pull Artifact),则必须在 Triggers 中配置 CEL interceptor,按类型过滤事件。如果没有 interceptor,所有已配置的事件类型都会触发同一 pipeline,这可能导致非预期的执行。
例如,如果 webhook 将 PUSH_ARTIFACT 和 PULL_ARTIFACT 事件发送到同一个 EventListener,并且你有一个未配置 interceptor 的 Trigger,则这两种事件都会触发该 pipeline。请使用 interceptor 将不同的事件类型路由到不同的 Trigger 或 pipeline。
为简化本文档,我们假设 pipeline 已准备就绪,并提供了以下参数:
请替换为实际的 pipeline 信息。
以下示例 Triggers 仅根据事件内容进行过滤,不会检查事件的发送者。在公开 listener 之前,请将推荐设置中的 Authorization 标头检查添加为每个 Trigger 的第一个 interceptor。
接下来,只需配置以下两个 trigger:
创建 Push Artifact Trigger
将以下 YAML 保存为 harbor-push-trigger.yaml:
在环境中创建资源:
事件类型过滤示例:如果 Harbor webhook 配置为同时发送 Push 和 Pull 事件,并且你希望对它们进行不同处理,则可以创建单独的 Triggers,并使用 CEL interceptor 按事件类型进行过滤:
Push 事件 Trigger(如上所示):
Pull 事件 Trigger(如有需要):
这样可以确保 push 事件仅触发 push pipeline,pull 事件仅触发 pull pipeline,即使两种事件类型都发送到同一个 EventListener。
创建 Scanning Completed Trigger
将以下 YAML 保存为 harbor-scanning-trigger.yaml:
请根据需要调整 Interceptor 配置。你可以根据扫描状态、漏洞严重性等条件进行过滤。请注意,scan_overview 结构使用动态 MIME 类型键,因此可能需要根据扫描类型调整 CEL 表达式。
在环境中创建资源:
验证 Triggers
通过向 Harbor 推送 image 并触发漏洞扫描进行验证。
CLI:
你可以使用 kubectl -n <namespace> get pipelinerun 获取 pipeline 执行状态。
控制台:
访问 Pipelines > PipelineRuns 查看已触发的 pipelines。
使用场景
使用场景 1:自动化镜像部署
场景:当容器镜像推送到 Harbor 时,自动将其部署到 staging 或 production 环境。
配置:
- 使用
harbor-push-artifact绑定创建 Trigger - 配置 pipeline,使用
artifact-resource-url拉取镜像并将其部署到目标环境 - 可选:使用 CEL 拦截器按 repository namespace 或 tag 模式进行筛选
示例使用场景:
- 将带有
production标签的镜像部署到 production 环境 - 将特定 namespace 中的镜像部署到 staging 环境
- 仅对符合特定命名模式的镜像触发部署
使用场景 2:安全策略强制执行
场景:通过阻止包含严重漏洞的镜像进行部署来强制执行安全策略。
配置:
- 使用
harbor-scanning-completed绑定创建 Trigger - 使用 CEL 拦截器筛选包含严重漏洞的扫描结果
- 配置 pipeline:
- 检查扫描结果中的漏洞数量
- 如果严重漏洞超过阈值,则阻止部署
- 向安全团队发送通知
示例使用场景:
- 防止部署包含严重漏洞的镜像
- 自动隔离包含高风险漏洞的镜像
- 生成用于合规性检查的安全报告
使用场景 3:制品生命周期管理
场景:根据使用模式和保留策略自动管理制品生命周期。
配置:
- 为
harbor-pull-artifact和harbor-delete-artifact事件创建 Triggers - 跟踪制品的使用情况和存留时间
- 根据策略自动删除旧制品或未使用的制品
示例使用场景:
- 归档 90 天未被拉取的旧制品
- 部署到 production 后清理开发制品
- 遵循数据保留策略以满足合规性要求
使用场景 4:多阶段 CI/CD Pipeline
场景:构建完整的 CI/CD pipeline,在镜像推送时触发,运行测试、执行安全扫描,并根据扫描结果进行部署。
配置:
- 创建多个 Triggers:
harbor-push-artifacttrigger:启动构建和测试 pipelineharbor-scanning-completedtrigger:如果扫描通过,则继续部署
- 使用 pipeline 依赖项和工作区在各阶段之间共享制品
示例使用场景:
- 构建 → 测试 → 扫描 → 部署工作流
- 并行测试和扫描,以更快获得反馈
- 根据测试和扫描结果进行条件部署
推荐设置
启用时机。当已完成的构建应自动交接给下一阶段,而不是等待有人启动下一阶段时,启用 Harbor 事件触发器。例如,staging 仓库中的 PUSH_ARTIFACT 事件应启动组件的交付运行。
推荐值。每个 staging 项目使用一个独立的制品监听器,与处理代码事件的监听器分开,并使用其自身的服务帐户运行。在 Harbor webhook 中,仅启用 Push Artifact,将其指向监听器的内部 TLS 端点,设置 Auth Header,并保持证书验证启用。只有当 Harbor 信任签发监听器证书的 CA 时,此配置才有效;否则交付会失败。受信任的 CA 应添加到 Harbor 安装中,通常由 Harbor 管理员完成,而不是在项目 webhook 设置中配置(参见 Harbor 文档)。将确切配置的 Authorization header 值存储在 Secret 中,键名为 authorization,使用第一个 CEL 拦截器(header.canonical('Authorization').compareSecret('authorization', '<secret-name>'))检查该值,并在 body.type == 'PUSH_ARTIFACT' 上添加第二个 CEL 过滤器,检查准确的 body.event_data.repository.repo_full_name、单个资源、有效的 sha256: digest,以及 CI 生成的标签格式(例如 40 个字符的 commit SHA),这样标签不符合该格式的推送就会被忽略。标签格式无法证明是谁推送了制品:使用符合 CI 格式标签的手动推送仍会通过过滤器。切勿将 production registry 注册为此监听器的发送方:promotion 不得触发自身。按照处理可选字段中的说明设置可选字段的默认值,并记住,PUSH_ARTIFACT 不是扫描或签名判定结果。有关完整的 Trigger、TriggerBinding 和 EventListener manifest,请参见 Automate CI with Events 的制品事件部分以及 Enable Artifact-Driven Delivery。如需撤销设置,请先删除 Harbor 项目设置中 Webhooks 下的 webhook(参见通过 Harbor UI 配置 Webhook),使 Harbor 停止发送事件。然后删除为制品监听器创建的对象:EventListener、其 Triggers 和 TriggerBinding(在关联的 manifest 中,即 EventListener application-cicd-artifact-events、Triggers application-cicd-backend-artifact 和 application-cicd-frontend-artifact,以及 TriggerBinding application-cicd-artifact-push)、保存 authorization 值的 Secret,以及监听器的服务帐户(如果没有其他对象使用它)。
前提条件。前提条件中列出的项目必须已准备就绪,并且拦截器必须能够读取 webhook Secret;参见 Webhook Secret 身份验证。下游 Pipeline 及其运行配置必须已经能够手动启动并正常工作;只有在手动运行成功后,才启用 webhook。
检查 Authorization header 检查。向 Harbor webhook 的 Endpoint URL 发送带有错误 Authorization header 的请求,例如使用 curl(如果证书由内部 CA 签发,则添加 --cacert <ca-file>):
监听器仍会返回 HTTP_STATUS 202,并且 kubectl -n <namespace> get pipelinerun 中不会出现新的 PipelineRun。由于第二个过滤器也会拒绝此请求,只有位于 tekton-pipelines 中的核心拦截器日志会显示 header 检查拒绝了该请求:它会显示 expression header.canonical('Authorization').compareSecret('authorization', '<secret-name>') did not return true(kubectl logs -n tekton-pipelines -l app=tekton-triggers-core-interceptors --tail=-1 --timestamps,用于读取 Deployment 中每个 Pod 的日志)。核心拦截器每次调用都会记录一行,不包含事件 ID,因此应根据请求时间匹配这些行。如果该行显示的是带有 failed to find secret 的 error evaluating cel expression,则表示 Trigger 所在命名空间中缺少 Secret 或其 authorization 键。如果该时间点两行都没有出现,则可能是 header 检查不是 Trigger 的第一个拦截器,或者监听器没有为该 Trigger 提供服务:此时不会为它运行任何拦截器,也不会记录任何日志。读取此日志需要对 tekton-pipelines 中的 Pod 日志具有读取权限,通常需要集群管理员权限。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果安装使用其他命名空间,请在命令中替换该值。