Tekton Trigger Interceptors 基础

Interceptors 概述

Interceptor是针对特定平台的的事件处理器，在 TriggerBinding 之前运行。它允许您执行有效负载过滤、验证（使用秘密）、转换、定义和测试触发条件，以及实现其他有用的处理。一旦事件数据通过Interceptor，它就会在将有效负载数据传递到 TriggerBinding 之前转到Trigger。还可以使用Interceptor来修改关联Trigger的行为。

Interceptor 实现方式

Standalone Interceptors，是Interceptors或 ClusterInterceptor 自定义资源定义 (CRD) 的实例。可以通过在 EventListener 中引用这些Interceptors以及所需的参数来指定它们。也可以使用 ClusterInterceptor CRD 来实现您自己的自定义Interceptors。

Tekton Trigger 内置的 Interceptor

# kubectl get ClusterInterceptor

NAME        AGE
bitbucket   3d20h
cel         3d20h
github      3d20h
gitlab      3d20h
slack       3d20h

Interceptor 资源规范

interceptors:
    - name:                     # 可选）唯一标识此interceptor定义的名称
      ref:                      # 对 ClusterInterceptor 或 Interceptor 对象的引用
        name:                   # 引用的 ClusterInterceptor 的名称。可选值：github、gitlab、bitbucket、cel、slack
        kind：                  # （可选）指定引用的 Kubernetes 对象是 ClusterInterceptor 对象还是 NamespacedInterceptor。默认值为 ClusterInterceptor
        apiVersion：            # （可选）指定目标API版本，例如triggers.tekton.dev/v1alpha1
        params：                #  指定要传递给 ClusterInterceptor 的参数的name/value键值对。
      params:                   # （可选）name/value键值对，指定Interceptor所需的参数；name字段采用字符串，而value字段采用有效的 JSON 对象
      - name: "secretRef"
        value:
          secretName: github-secret
          secretKey: secretToken
      - name: "eventTypes"
        value: ["pull_request"]

GitHub Interceptors

GitHub Interceptor包含验证和过滤 GitHub Webhooks 的逻辑。它可以验证 Webhook 的来源，并按您指定的条件过滤传入事件。GitHub Interceptor始终在其响应中保留有效负载数据（标头和正文）。

GitHub Interceptor 创建流程

1. 创建一个secret用于连接GitHub Webhook。 创建命令：openssl rand -base64 12
2. 配置 GitHub Webhook。
3. 创建 Kubernetes secret。
4. 将Kubernetes secret 传递给GitHub Interceptor。

添加更改的文件

GitHub Interceptor还可以添加一个逗号分隔的列表，其中包含了针对push和pull_request事件发生的所有更改(添加、修改或删除)的文件。更改的文件列表被添加到顶级扩展字段中事件有效负载的changed_files属性中。

triggers:
  - name: github-listener
      interceptors:
        - ref:
            name: "github"
            kind: ClusterInterceptor
            apiVersion: triggers.tekton.dev
          params:
          - name: "secretRef"
            value:
              secretName: github-secret
              secretKey: secretToken
          - name: "eventTypes"
            value: ["pull_request", "push"]
          - name: "addChangedFiles"
            value:
              enabled: true
              personalAccessToken:
                secretName: github-pat
                secretKey: token
        - ref:
            name: cel
          params:
          - name: filter
            # execute only when a file within the controllers directory has changed
            value: extensions.changed_files.matches('controllers/')

GitHub Interceptor 示例

---
apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: github-add-changed-files-pr-listener
spec:
  triggers:
    - name: github-add-changed-files-pr-listener
      interceptors:
        - ref:
            name: "github"
          params:
            - name: "eventTypes"
              value: ["pull_request", "push"]
            - name: "addChangedFiles"
              value:
                enabled: true
      bindings:
        - ref: github-add-changed-files-pr-pr-binding
      template:
        ref: github-add-changed-files-pr-template
  resources:
    kubernetesResource:
      spec:
        template:
          spec:
            serviceAccountName: tekton-triggers-example-sa
            containers:
              - resources:
                  requests:
                    memory: "64Mi"
                    cpu: "250m"
                  limits:
                    memory: "128Mi"
                    cpu: "500m"
---
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: github-add-changed-files-pr-pr-binding
spec:
  params:
    - name: changedfiles
      value: $(extensions.changed_files)

---
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: github-add-changed-files-pr-template
spec:
  params:
    - name: changedfiles
  resourcetemplates:
    - apiVersion: tekton.dev/v1beta1
      kind: TaskRun
      metadata:
        generateName: github-add-changed-files-pr-run-
      spec:
        taskSpec:
          steps:
            - image: ubuntu
              script: |
                #! /bin/bash
                echo "Changed Files: $(tt.params.changedfiles)"

旧版 GitHub Interceptor 示例

triggers:
  - name: github-listener
      interceptors:
        - github:
            secretRef:
              secretName: github-secret
              secretKey: secretToken
            eventTypes: ["pull_request"]

GitLab Interceptors

GitLab Interceptor包含验证和过滤GitLab webhook的逻辑。它可以验证Webhooks中描述的webhook的来源，也可以根据您指定的标准过滤传入事件。GitLab Interceptor总是在其响应中保留有效负载数据(both header and body)。

GitLab Interceptor 创建流程

1. 创建一个secret用于连接GitHub Webhook。 创建命令：openssl rand -base64 12
2. 配置 GitHub Webhook。
3. 创建 Kubernetes secret。
4. 将Kubernetes secret 传递给GitHub Interceptor。

GitLab Interceptor 示例

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: gitlabb-add-changed-files-pr-listener
spec:
  triggers:
    - name: gitlab-add-changed-files-pr-listener
      interceptors:
        - ref:
            name: "gitlab"
          params:
          - name: "secretRef"
            value:
              secretName: foo
              secretKey: bar
          - name: "eventTypes"
            value: ["Push Hook"]

旧版 GitLab Interceptor 示例

apiVersion: triggers.tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: gitlab-listener-interceptor
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: foo-trig
      interceptors:
        - gitlab:
            secretRef:
              secretName: foo
              secretKey: bar
            eventTypes:
              - Push Hook
      bindings:
        - ref: pipeline-binding
      template:
        ref: pipeline-template

CEL Interceptors

CEL Interceptor允许使用 CEL 表达式语言过滤和修改传入事件的有效负载。

CEL Interceptors支持overlays，这是 Tekton Triggers 添加到顶级扩展字段中的事件负载的 CEL 表达式。可以从 TriggerBindings 访问overlays。

CEL Interceptors 添加字段示例

在下面的overlays定义示例中，Interceptor除了标准header和body字段之外，还向相应的 TriggerBinding 将接收的事件负载添加了两个新字段:extensions.truncated_sha和extensions.branch_name

triggers:
    - name: cel-trig
      interceptors:
        - ref:
            name: cel
          params:
          - name: "overlays"
            value:
            - key: truncated_sha
              expression: "body.pull_request.head.sha.truncate(7)"
            - key: branch_name
              expression: "body.ref.split('/')[2]"

CEL Interceptors 匹配字段示例

cel-trig-with-matches Trigger会过滤不具有与“pull_request”匹配的“X-GitHub-Event”标头的事件，并使用从钩子主体派生的截断字符串向负载的 JSON 主体添加额外的键:

triggers:
    - name: cel-trig-with-matches
      interceptors:
        - ref:
            name: "cel"
          params:
          - name: "filter"
            value: "header.match('X-GitHub-Event', 'pull_request')"
          - name: "overlays"
            value:
              - key: truncated_sha
                expression: "body.pull_request.head.sha.truncate(7)"
      bindings:
      - name: sha
        value: $(extensions.truncated_sha)

CEL Interceptors no-filter示例

filter表达式必须返回true，此Trigger才能执行并应用指定的overlays。还可以选择完全省略过滤表达式，在这种情况下，Interceptor将指定的overlays应用于有效负载的主体。

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: cel-eventlistener-no-filter
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: cel-trig
      interceptors:
        - ref:
            name: "cel"
          params:
            - name: "overlays"
              value:
                - key: extensions.truncated_sha
                  expression: "body.pull_request.head.sha.truncate(7)"
      bindings:
      - ref: pipeline-binding
      template:
        ref: pipeline-template

参考文档

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