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 類型：攔截器的引用方式

1. 內置攔截器（官方提供，無需手動創建）

2. 自定義攔截器（用戶創建的 Interceptor 資源）

三、params 寫法：傳遞參數給攔截器

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

2. github 攔截器的 params

3. webhook 攔截器的 params

四、攔截器執行順序