Tekton interceptors介绍

在 Tekton Triggers 中，interceptors 是事件处理的核心环节，用于对输入事件进行过滤、验证、转换或增强。以下从 ref 类型、params 写法两方面详细介绍，并提供官方参考文档。

一、`interceptors` 基本结构

interceptors 是 Trigger 或 EventListener 中的数组配置，每个拦截器包含 ref（指定拦截器类型）和 params（传递参数给拦截器）：

yaml
 
 

interceptors:
  - ref:  # 定义拦截器类型
      name: <拦截器名称>
      # 可选：apiVersion（默认 triggers.tekton.dev/v1beta1）
    params:  # 传递给拦截器的参数
      - name: <参数名>
        value: <参数值>
      - name: <参数名2>
        value: <参数值2>

 

二、`ref` 类型：拦截器的引用方式

ref 用于指定使用哪种拦截器，Tekton 支持两种类型的拦截器引用：内置拦截器和自定义拦截器。

1. 内置拦截器（官方提供，无需手动创建）

Tekton Triggers 内置了多种常用拦截器，可直接通过 name 引用，无需提前创建 Interceptor 资源。常见内置拦截器包括：

`ref.name`	作用	适用场景
`cel`	基于 CEL（Common Expression Language）表达式过滤 / 转换事件	通用过滤（如字段存在性、值校验）、事件数据加工（通过 `overlays`）
`github`	专门处理 GitHub 事件（如验证签名、过滤事件类型）	GitHub Webhook 事件（push、pull_request 等）
`gitlab`	专门处理 GitLab 事件（验证签名、提取事件字段）	GitLab Webhook 事件
`bitbucket`	处理 Bitbucket 事件	Bitbucket 代码仓库事件
`webhook`	调用外部 HTTP 服务验证事件（将事件转发给外部服务，根据返回结果决定是否放行）	自定义验证逻辑（如调用内部权限服务、安全扫描服务）

示例：引用内置 cel 拦截器（如开头的配置）。

2. 自定义拦截器（用户创建的 `Interceptor` 资源）

若内置拦截器不满足需求，可通过 Interceptor 资源定义自定义拦截器（如组合多个逻辑），然后通过 ref.name 引用其名称。

步骤：

（1）创建自定义 Interceptor 资源：

yaml
 
 

apiVersion: triggers.tekton.dev/v1beta1
kind: Interceptor
metadata:
  name: my-custom-interceptor  # 自定义拦截器名称
spec:
  # 例如：组合 CEL 过滤和外部 webhook 验证
  cel:
    filter: "body.env == 'prod'"
  webhook:
    url: "https://my-service.com/validate"  # 外部验证服务

 

（2）在 Trigger 中引用：

yaml
 
interceptors:
  - ref:
      name: my-custom-interceptor  # 引用自定义拦截器

三、`params` 写法：传递参数给拦截器

params 是键值对数组，用于向拦截器传递配置（如过滤规则、URL、密钥等）。不同拦截器支持的 params 不同，以下是常见拦截器的 params 写法：

1. `cel` 拦截器的 `params`（最常用）

支持 filter（过滤事件）和 overlays（修改事件数据）：

yaml
 
 

interceptors:
  - ref:
      name: cel
    params:
      # 1. 过滤条件：仅放行满足表达式的事件
      - name: filter
        value: |
          # 示例：事件中必须包含 body.tag，且 tag 以 "v" 开头
          has(body.tag) && body.tag.startsWith("v")
      
      # 2. 事件加工：新增/修改字段（可选）
      - name: overlays
        value:
          # 示例1：从 tag 中提取版本号（如 "v1.2.3" → "1.2.3"）
          - key: body.version
            expression: "body.tag.substring(1)"
          
          # 示例2：拼接镜像标签
          - key: body.image
            expression: "body.repo + ':' + body.version"

 

filter：CEL 表达式，返回 true 则事件放行，false 则拦截。
overlays：数组，每个元素通过 key（目标字段路径）和 expression（CEL 表达式计算值）修改事件。

2. `github` 拦截器的 `params`

用于验证 GitHub 事件签名、过滤事件类型等：

yaml
 
 

interceptors:
  - ref:
      name: github
    params:
      # 1. 验证 GitHub Webhook 签名（必填，防止伪造事件）
      - name: secretRef
        value:
          secretName: github-webhook-secret  # 存储 GitHub 密钥的 Secret 名称
          secretKey: secret                  # Secret 中存储密钥的 key
      
      # 2. 过滤事件类型（如只处理 pull_request 事件）
      - name: eventTypes
        value: ["pull_request"]
      
      # 3. 进一步过滤（如 PR 状态为 open）
      - name: filter
        value: "body.action == 'opened'"  # CEL 表达式

 

secretRef：引用存储 GitHub Webhook 密钥的 Secret（GitHub 配置 Webhook 时设置的密钥）。

3. `webhook` 拦截器的 `params`

用于调用外部服务验证事件：

yaml
 
 

interceptors:
  - ref:
      name: webhook
    params:
      # 外部服务 URL
      - name: url
        value: "https://my-validator.example.com/check"
      
      # 请求方法（默认 POST）
      - name: method
        value: "POST"
      
      # 传递给外部服务的头部（可选，如认证信息）
      - name: headers
        value:
          - name: "Authorization"
            value: "Bearer $(params.token)"  # 可引用 Secret 中的值
      
      # 外部服务返回 2xx 状态码则放行（默认），可自定义规则
      - name: successCondition
        value: "response.statusCode == 200 && response.body.allowed == true"

 

四、拦截器执行顺序

多个拦截器按配置顺序执行，前一个拦截器处理后的事件会作为后一个的输入：

yaml
 
 

interceptors:
  # 第一步：验证 GitHub 签名
  - ref: {name: github}
    params: [...]
  # 第二步：用 CEL 过滤事件
  - ref: {name: cel}
    params: [{name: filter, value: "body.ref == 'refs/heads/main'"}]
  # 第三步：调用外部服务二次验证
  - ref: {name: webhook}
    params: [...]

 

五、官方参考文档

Tekton Triggers 拦截器总览：

https://tekton.dev/docs/triggers/interceptors/
内置拦截器详细说明：
- CEL 拦截器：https://tekton.dev/docs/triggers/interceptors/#cel-interceptor
- GitHub 拦截器：https://tekton.dev/docs/triggers/interceptors/#github-interceptor
- Webhook 拦截器：https://tekton.dev/docs/triggers/interceptors/#webhook-interceptor
CEL 表达式语法（用于 filter 和 overlays）：

https://tekton.dev/docs/triggers/cel_expressions/

通过合理配置 interceptors，可以精准控制事件的处理流程，确保只有符合条件的事件才会触发流水线，同时对事件数据进行预处理以适配后续需求。

问题一： interceptors 在 Trigger 和 EventListener 中的写法有什么区别，分别适用什么场景？

在 Tekton Triggers 中，interceptors 既可以配置在 Trigger 中，也可以配置在 EventListener 中，二者的核心功能都是对事件进行过滤、验证或转换，但作用范围、执行时机和使用场景有显著区别。

一、核心区别对比表

维度	`EventListener` 中的 `interceptors`	`Trigger` 中的 `interceptors`
作用范围	对所有进入该 `EventListener` 的事件生效（全局拦截）。	仅对当前 `Trigger` 关联的事件生效（局部拦截）。
执行顺序	先于 `Trigger` 中的拦截器执行（事件进入后先经过全局拦截）。	后于 `EventListener` 的拦截器执行（全局拦截通过后才执行）。
职责	处理通用逻辑（如身份验证、格式校验、跨 `Trigger` 共享的过滤）。	处理特定逻辑（如当前 `Trigger` 专属的事件过滤、数据加工）。
配置位置	`EventListener.spec.interceptors`	`Trigger.spec.interceptors`

二、详细说明

1. `EventListener` 中的 `interceptors`（全局拦截）

EventListener 是接收外部事件的入口，其配置的 interceptors 会对所有通过该 EventListener 进入的事件进行处理，无论事件最终匹配哪个 Trigger。

典型用途：

通用身份验证：验证所有事件的来源合法性（如 GitHub Webhook 签名验证、统一的 Token 校验）。
格式校验：确保事件是预期的 JSON 格式，避免无效格式的事件进入后续流程。
跨 Trigger 共享的过滤：例如 “只处理生产环境相关的事件”，对所有 Trigger 生效。

示例配置：

yaml
 
 

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: global-listener
spec:
  # 全局拦截器：所有事件先经过这里
  interceptors:
    - ref:
        name: github  # 验证所有 GitHub 事件的签名（通用逻辑）
      params:
        - name: secretRef
          value:
            secretName: github-global-secret
            secretKey: secret
    - ref:
        name: cel  # 所有事件必须包含 body.environment 字段
      params:
        - name: filter
          value: "has(body.environment)"
  # 关联多个 Trigger
  triggers:
    - ref: trigger-1
    - ref: trigger-2

 

2. `Trigger` 中的 `interceptors`（局部拦截）

Trigger 是事件与流水线的绑定桥梁，其配置的 interceptors 仅对匹配当前 Trigger 的事件生效，且在 EventListener 的拦截器执行之后。

典型用途：

Trigger 专属过滤：例如 trigger-1 只处理 environment: dev 的事件，trigger-2 只处理 environment: prod 的事件。
事件数据加工：为当前 Trigger 后续的 TriggerBinding 提取参数做准备（如字段转换、新增计算字段）。

示例配置：

yaml
 
 

# Trigger 1：只处理 dev 环境的事件
apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: trigger-1
spec:
  interceptors:
    - ref:
        name: cel  # 局部过滤：仅 environment 为 dev 的事件
      params:
        - name: filter
          value: "body.environment == 'dev'"
  bindings: [...]
  template: [...]

---
# Trigger 2：只处理 prod 环境的事件
apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: trigger-2
spec:
  interceptors:
    - ref:
        name: cel  # 局部过滤：仅 environment 为 prod 的事件
      params:
        - name: filter
          value: "body.environment == 'prod'"
  bindings: [...]
  template: [...]

 

三、执行流程对比

事件处理的完整流程：

plaintext
 
 

外部事件 → EventListener 接收 → 
  第一步：执行 EventListener 的 interceptors（全局拦截，如签名验证） → 
    若拦截（不通过）→ 事件被丢弃  
    若通过 → 进入下一步  
  第二步：匹配对应的 Trigger（根据事件属性或路由规则） → 
  第三步：执行该 Trigger 的 interceptors（局部拦截，如环境过滤） → 
    若拦截 → 事件被丢弃  
    若通过 → 执行 TriggerBinding 和 TriggerTemplate → 触发流水线

 

四、如何选择配置位置？

若逻辑是所有事件都需要处理的通用规则（如身份验证、基础格式校验），配置在 EventListener 中。
若逻辑是某个 Trigger 专属的规则（如特定环境、特定事件类型的过滤），配置在 Trigger 中。

这种分层设计既能保证全局规则的统一性，又能满足不同 Trigger 的个性化需求，提升事件处理的灵活性。

官方文档参考

EventListener 拦截器：https://tekton.dev/docs/triggers/eventlisteners/#configuring-interceptors
Trigger 拦截器：https://tekton.dev/docs/triggers/triggers/#interceptors

posted @ 2025-10-29 13:43 呆瓜小贼66 阅读(9) 评论(0) 收藏举报

刷新页面返回顶部

呆瓜小贼66

Tekton interceptors介绍

一、interceptors 基本结构

二、ref 类型：拦截器的引用方式