#使用 Harbor 事件触发器

#Overview

Harbor Event Triggers 允许您通过 Harbor 的 Webhook 事件自动触发 Tekton pipeline。它支持多种事件类型，包括 artifact 推送、拉取、删除和扫描完成，帮助您构建完整的容器镜像和 OCI chart 的 CI/CD 自动化流程。

#Core Features

• 多事件类型支持：支持 Harbor 的多种事件，如 Push Artifact、Pull Artifact、Delete Artifact 和 Scanning Completed。
• 标准化触发绑定：提供标准化的 ClusterTriggerBindings，确保跨平台一致性。
• 灵活的参数映射：自动从 Harbor 事件中提取关键信息作为 pipeline 参数。
• 多 artifact 类型支持：支持容器镜像和 OCI chart。

#Supported Event Types

#Basic Event Information

所有输出变量均可用于 pipeline 参数映射。您可以通过 $(tt.params.<param name>) 访问参数值。

#基础变量（所有事件通用）

#1. Push Artifact 事件

当 artifact（容器镜像或 OCI chart）被推送到 Harbor 仓库时触发。适用于：

• 自动镜像构建与部署
• 镜像验证与测试
• 自动打标签与版本管理
• 多阶段构建流水线

#Push Artifact 事件变量

以上所有基础变量同样可用。

#2. Pull Artifact 事件

当 artifact 从 Harbor 仓库被拉取时触发。适用于：

• 使用情况跟踪与分析
• 安全监控
• 资源消耗统计
• 部署验证

#Pull Artifact 事件变量

以上所有基础变量同样可用。

#3. Delete Artifact 事件

当 artifact 从 Harbor 仓库被删除时触发。适用于：

• 清理自动化
• 审计日志
• 资源管理
• 合规追踪

#Delete Artifact 事件变量

以上所有基础变量均可用。注意 repository-date-created 在删除事件中不可用。

#4. Scanning Completed 事件

当 artifact 的漏洞扫描完成时触发。适用于：

• 安全策略执行
• 自动安全检查
• 漏洞报告
• 自动修复流程

#Scanning Completed 事件变量

以上所有基础变量均可用。注意 repository-date-created 在扫描事件中不可用。

#配置指南

#可选字段处理

Harbor 事件中的某些字段可能因事件类型或 artifact 引用方式不同而可选或缺失。例如：

• artifact-tag：若 artifact 仅通过摘要引用，可能缺失
• repository-date-created：仅在 push 和 pull 事件中存在，delete 和 scanning 事件中缺失

重要：使用引用可选字段的 ClusterTriggerBindings 时，您必须在 TriggerTemplate 中为对应参数提供默认值。若 payload 中缺失字段且无默认值，触发器会因 JSONPath 解析错误而失败。

示例：处理可选的 artifact-tag 字段，TriggerTemplate 配置示例如下：

spec:
  params:
    - name: artifact-tag
      default: ""  # 可选字段的空字符串默认值

这样当 Harbor 事件 payload 中缺失 tag 字段时，触发器会使用空字符串而非失败。

#前置条件

1. 已在环境中创建 EventListener，且能够处理目标命名空间中的 Trigger。详情请联系平台管理员。
2. Harbor 能访问上述 EventListener。
3. 已创建所需的 Pipeline 及相关运行配置。
4. 您有权限修改 Harbor 项目的 Webhook 设置。

#通过 Harbor UI 配置 Webhook

1. 进入 Harbor 项目设置。
2. 选择 Webhooks。
3. 点击 New Webhook。
4. 配置 webhook：
   • 名称：填写描述性名称（如 tekton-webhook）
   • Endpoint URL：填写 EventListener 地址，例如：

     http://<your-eventlistener-url>
     或

     https://<your-eventlistener-url>
   • 认证头：（可选）如需认证则配置
   • 跳过证书验证：使用自签名证书时启用
5. 根据需要选择事件类型：
   • Push Artifact：artifact 推送时触发
   • Pull Artifact：artifact 拉取时触发
   • Delete Artifact：artifact 删除时触发
   • Scanning Completed：漏洞扫描完成时触发
6. 点击 保存。

#Pipeline 触发配置示例

若目标是通过触发器实现持续集成，满足以下需求：

• 镜像推送时自动触发自动构建和部署
• 扫描完成时自动触发安全检查

为简化说明，假设 pipeline 已准备好并提供以下参数：

接下来只需配置以下两个触发器：

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
    name: my-pipeline-push   # 建议根据 pipeline 名称修改前缀
    namespace: my-namespace  # 修改为实际命名空间
spec:
    bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-push-artifact
    interceptors: # 过滤仅处理 PUSH_ARTIFACT 事件
    - ref:
        kind: ClusterInterceptor
        name: cel
      params:
      - name: filter
        value: body.type == "PUSH_ARTIFACT"  # 仅触发推送事件
    template:
      spec:
        params:
        - name: repository-full-name
        - name: artifact-tag
          default: ""  # 可选字段：若 artifact 仅通过摘要引用则可能为空
        - name: artifact-digest
        resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
              generateName: my-pipeline-push- # 建议根据 pipeline 名称修改前缀
          spec:
              pipelineRef:
                name: my-pipeline  # 修改为实际 pipeline 名称
              params:
              - name: repository-full-name
                value: $(tt.params.repository-full-name)
              - name: artifact-tag
                value: $(tt.params.artifact-tag)
              - name: artifact-digest
                value: $(tt.params.artifact-digest)
              workspaces: # 工作空间需根据 pipeline 需求和环境配置修改
              - name: output
                emptyDir: {}

kubectl apply -f harbor-push-trigger.yaml

interceptors:
- ref:
    kind: ClusterInterceptor
    name: cel
  params:
  - name: filter
    value: body.type == "PUSH_ARTIFACT"

interceptors:
- ref:
    kind: ClusterInterceptor
    name: cel
  params:
  - name: filter
    value: body.type == "PULL_ARTIFACT"

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: my-pipeline-scanning # 建议根据 pipeline 名称修改前缀
  namespace: my-namespace # 修改为实际命名空间
spec:
  bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-scanning-completed
  interceptors: # 添加拦截器过滤仅处理成功扫描，或按漏洞严重级别过滤
  - ref:
      kind: ClusterInterceptor
      name: cel
    params:
    - name: filter
      value: |
        # 仅过滤成功扫描
        # 注意：scan_overview 结构因扫描类型不同而异，请根据实际调整路径
        # 漏洞扫描示例路径：body.event_data.resources[0].scan_overview["application/vnd.security.vulnerability.report; version=1.1"].scan_status == "Success"
  template:
    spec:
      params:
        - name: repository-full-name
        - name: artifact-tag
          default: ""  # 可选字段：若 artifact 仅通过摘要引用则可能为空
        - name: artifact-digest
      resourcetemplates:
      - apiVersion: tekton.dev/v1
        kind: PipelineRun
        metadata:
          generateName: my-pipeline-scan- # 建议根据 pipeline 名称修改前缀
        spec:
          pipelineRef:
            name: my-pipeline # 根据 pipeline 名称修改
          params:
            - name: repository-full-name
              value: $(tt.params.repository-full-name)
            - name: artifact-tag
              value: $(tt.params.artifact-tag)
            - name: artifact-digest
              value: $(tt.params.artifact-digest)
          workspaces: # 工作空间需根据 pipeline 需求和环境配置修改
            - name: output
              emptyDir: {}

kubectl apply -f harbor-scanning-trigger.yaml

#Use Cases

#用例 1：自动镜像部署

场景：当容器镜像推送到 Harbor 时，自动部署到测试或生产环境。

配置：

• 使用 harbor-push-artifact 绑定创建 Trigger
• pipeline 配置拉取镜像（通过 artifact-resource-url）并部署到目标环境
• 可选使用 CEL 拦截器按仓库命名空间或标签模式过滤

示例用例：

• 部署标签为 production 的镜像到生产环境
• 部署特定命名空间的镜像到测试环境
• 仅触发符合特定命名规则的镜像部署

#用例 2：安全策略执行

场景：通过阻止含有关键漏洞的镜像部署，执行安全策略。

配置：

• 使用 harbor-scanning-completed 绑定创建 Trigger
• 使用 CEL 拦截器过滤含关键漏洞的扫描结果
• pipeline 配置：
  • 检查扫描结果中的漏洞数量
  • 若关键漏洞超阈值则阻止部署
  • 向安全团队发送通知

示例用例：

• 阻止含关键漏洞的镜像部署
• 自动隔离高风险漏洞镜像
• 生成安全合规报告

#用例 3：Artifact 生命周期管理

场景：基于使用情况和保留策略自动管理 artifact 生命周期。

配置：

• 为 harbor-pull-artifact 和 harbor-delete-artifact 事件创建 Trigger
• 跟踪 artifact 使用频率和存储时间
• 根据策略自动删除过期或未使用的 artifact

示例用例：

• 归档 90 天未被拉取的旧 artifact
• 部署完成后清理开发阶段的 artifact
• 符合数据保留合规要求

#用例 4：多阶段 CI/CD 流水线

场景：构建完整的 CI/CD 流水线，基于镜像推送触发，执行测试、扫描，并根据扫描结果部署。

配置：

• 创建多个 Trigger：
  1. harbor-push-artifact 触发：启动构建和测试流水线
  2. harbor-scanning-completed 触发：扫描通过后继续部署
• 使用 pipeline 依赖和工作空间共享阶段间的 artifact

示例用例：

• 构建 → 测试 → 扫描 → 部署 工作流
• 并行测试和扫描以加快反馈
• 基于测试和扫描结果的条件部署