EventListener

EventListener 是 Tekton Triggers 中的基础组件,充当外部事件的入口点。它提供了一种 Kubernetes 原生方式,用于接收、验证、筛选和处理来自外部系统的事件,并最终触发 Tekton 资源(如 PipelineRun 和 TaskRun)的执行。

术语说明

术语描述
EventListener一种 Kubernetes 对象,用于在 Kubernetes 集群的指定端口上监听事件
Trigger指定 EventListener 检测到事件时执行的操作,包括 TriggerTemplate、TriggerBinding 和可选的 Interceptor
Interceptor在事件到达 TriggerBinding 之前对其进行处理和筛选的组件
TriggerBinding从事件负载中提取字段,并将其绑定到参数
TriggerTemplate指定接收到事件时要创建的资源(如 PipelineRun)的模板

为什么需要 EventListener

传统 CI/CD 面临的挑战

在传统 CI/CD 系统中,集成外部事件源通常需要:

  • 为每个事件源编写自定义 webhook 处理程序
  • 手动配置事件处理逻辑
  • 复杂的 webhook 接收器部署和管理
  • 缺乏标准化的安全和验证机制

这些挑战会导致 CI/CD 流水线碎片化、安全漏洞以及维护开销。

EventListener 解决方案

EventListener 通过以下方式解决这些挑战:

  1. 为所有外部事件提供统一入口
  2. 通过 Kubernetes 资源实现声明式配置
  3. 内置安全和验证机制
  4. 与 Tekton 的流水线执行系统无缝集成
  5. Kubernetes 原生部署和扩缩容

优势

  • Kubernetes 原生:作为标准 Kubernetes 资源(Deployment 和 Service)部署
  • 声明式配置:使用 YAML 定义,遵循 Kubernetes 模式
  • 可扩展:支持各种事件源和自定义拦截器
  • 安全:内置身份验证和验证机制
  • 可扩展性:可以进行水平扩展,以处理大量事件
  • 灵活部署:支持各种网络配置(虚拟 IP、主机端口、负载均衡器、Ingress)

适用场景

EventListener 适用于:

  1. CI/CD 自动化:在代码推送或创建 PR 时自动触发流水线
  2. GitOps 工作流:响应 Git 仓库中的变更
  3. 多系统集成:将各种系统(GitHub、GitLab、Jenkins 等)连接到 Tekton 流水线
  4. 自定义事件处理:处理来自内部系统的自定义事件
  5. Webhook 管理:集中管理多个服务的 webhook

约束和限制

  • Kubernetes 依赖:需要 Kubernetes 集群才能运行
  • 资源要求:需要根据事件量配置适当的 CPU 和内存资源
  • 网络配置:需要正确配置网络以支持外部访问
  • 安全注意事项:需要正确配置 RBAC,并可能需要配置 TLS
  • 扩展限制:事件量非常大时,可能需要仔细规划资源

原理

EventListener 基于以下原理运行:

  1. 事件接收:EventListener 暴露一个 HTTP 端点,用于接收来自外部系统的 webhook 事件。

  2. 事件处理流程:

    • EventListener 服务接收事件
    • 配置的拦截器验证并处理事件
    • 使用 TriggerBindings 提取事件数据
    • 根据 TriggerTemplates 创建资源
    • 创建的资源(例如 PipelineRuns)由 Tekton 执行
  3. 部署架构:

    • EventListener 作为 Kubernetes Deployment 部署
    • 创建一个 Service 以暴露 EventListener
    • EventListener 使用具有适当权限的 ServiceAccount
    • 可选的 Ingress/Route 用于外部访问
  4. 安全模型:

    • 通过拦截器进行身份验证
    • 通过 Kubernetes RBAC 进行授权
    • 验证事件负载
    • 可选的 TLS 加密

配置示例

基本 EventListener

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: github-listener
spec:
  serviceAccountName: triggers-default-sa
  triggers:
    - name: github-push
      interceptors:
        - ref:
            name: "github"
          params:
            - name: "secretRef"
              value:
                secretName: github-secret
                secretKey: secretToken
            - name: "eventTypes"
              value:
                - "push"
      bindings:
        - ref: github-push-binding
      template:
        ref: build-template

包含多个 Trigger 的 EventListener

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: multi-listener
spec:
  serviceAccountName: triggers-default-sa
  triggers:
    - name: github-push
      interceptors:
        - ref:
            name: "github"
          params:
            - name: "secretRef"
              value:
                secretName: github-webhook-secret
                secretKey: secretToken
            - name: "eventTypes"
              value:
                - "push"
      bindings:
        - ref: github-push-binding
      template:
        ref: build-template
    - name: github-pr
      interceptors:
        - ref:
            name: "github"
          params:
            - name: "secretRef"
              value:
                secretName: github-webhook-secret
                secretKey: secretToken
            - name: "eventTypes"
              value:
                - "pull_request"
      bindings:
        - ref: github-pr-binding
      template:
        ref: pr-template

重要参数说明

ServiceAccountName

ServiceAccount 参数对于 EventListener 至关重要,因为它决定了 EventListener 创建资源时所拥有的权限。

适用场景

  • EventListener 需要在多个命名空间中创建资源时
  • 需要满足特定安全约束时

约束和限制

  • ServiceAccount 必须具有适当的 RBAC 权限
  • 应遵循最小权限原则

原理

ServiceAccount 需要具有以下权限:

  • 读取 ConfigMaps、Secrets 和 ServiceAccounts
  • 创建和管理 PipelineRuns 和 TaskRuns
  • 访问 TriggerBindings 和 TriggerTemplates

Resources 配置

resources 参数允许你自定义 EventListener 的部署方式。

适用场景

  • 高可用部署
  • 自定义资源需求
  • 特定网络需求

原理

你可以配置:

  • 用于实现高可用的 Replica 数量
  • 资源限制和请求
  • Service 类型(ClusterIP、NodePort、LoadBalancer)
  • 自定义 Pod 模板规范

Webhook Secret 身份验证

Webhook Secret 身份验证是一种关键的安全机制:当拦截器具有 secretRef 参数时,只有请求携带与外部系统共享的 Secret 所对应的有效签名或令牌,才允许请求继续处理。如果没有适当的身份验证,恶意行为者可能会利用你的 webhook 端点触发未经授权的流水线执行。

Webhook Secret 身份验证的重要性

  1. 防止未经授权的访问:仅当拦截器具有 secretRef 参数时,才会处理具有有效签名或令牌的请求。GitHub 和 GitLab 拦截器仅在设置了 secretRef 时检查签名或令牌。未设置该参数时,如果 eventTypes 未设置或列出了请求的事件标头,请求会通过 GitLab 拦截器;而对于 GitHub 拦截器,除满足相同条件外,还必须通过 GitHub Interceptor with Secret Authentication 中所述的其他 GitHub 检查
  2. 验证事件来源:只接受使用你在外部系统(GitHub、GitLab 等)中设置的 Secret 签名或携带该 Secret 的请求
  3. 检测被篡改的负载:签名(例如 GitHub 的签名)基于请求正文计算,因此正文发生更改的请求会被拒绝。令牌(例如 GitLab 的令牌)不涵盖请求正文。签名和令牌都无法阻止已捕获的请求被再次发送(重放)
  4. 合规性:许多组织出于安全合规要求 webhook 身份验证

工作原理

不同平台使用不同的身份验证机制:

  • GitHub:在 X-Hub-Signature-256 标头中使用 HMAC-SHA256 签名
  • GitLab:在 X-GitLab-Token 标头中使用 Secret 令牌

设置 secretRef 参数后,拦截器会先根据存储在 Kubernetes Secret 中的 Secret 验证传入请求,然后才允许事件继续传递到 TriggerBinding。

创建 Webhook Secret

第 1 步:生成或获取 Secret 令牌

对于 GitHub:

  1. 转到仓库 → Settings → Webhooks → Add webhook
  2. 生成一个 Secret 令牌(或使用现有令牌)
  3. 复制 Secret 令牌值

对于 GitLab:

  1. 转到项目 → Settings → Webhooks
  2. 生成一个 Secret 令牌
  3. 复制 Secret 令牌值

第 2 步:创建 Kubernetes Secret

创建一个包含 webhook Secret 令牌的 Kubernetes Secret。在 bash 或 zsh 中运行命令:在 POSIX sh(例如 dash)中,read -rs 会失败并使变量为空。首先单独运行 read -rs 行,然后粘贴令牌并按 Enter:read -rs 不会显示令牌,因此它不会出现在屏幕或 shell 历史记录中。如果将该行与后续行一起粘贴,不支持括号粘贴的 shell 会将下一行读取为令牌:

read -rs SECRET_TOKEN

然后使用适用于你平台的命令创建 Secret。创建 Secret 后,unset 会从 shell 中删除令牌。因此,如果要创建两个 Secret,请在运行第二条命令前再次运行 read -rs 行;否则第二个 Secret 会获得空的 secretToken。对于 GitHub:

kubectl create secret generic github-webhook-secret \
  --from-literal=secretToken="$SECRET_TOKEN" \
  -n <namespace>
unset SECRET_TOKEN

对于 GitLab:

kubectl create secret generic gitlab-webhook-secret \
  --from-literal=secretToken="$SECRET_TOKEN" \
  -n <namespace>
unset SECRET_TOKEN

或者,你也可以使用 YAML 创建 Secret:

apiVersion: v1
kind: Secret
metadata:
  name: github-webhook-secret
  namespace: tekton-triggers-demo
type: Opaque
stringData:
  secretToken: <your-secret-token-here>
WARNING

安全最佳实践:切勿将 Secret 令牌提交到版本控制系统。请使用 Kubernetes Secrets,并确保配置了适当的 RBAC 权限,以限制对 Secret 的访问。

配置拦截器身份验证

使用 Secret 身份验证的 GitHub 拦截器

GitHub 拦截器仅在设置了 secretRef 参数时,才会使用 HMAC-SHA256 验证 webhook 签名。如果未设置 secretRef,它不会检查签名,但仍会拒绝 X-GitHub-Event 标头未列在 eventTypes 中的请求(设置了 eventTypes 时)。将 GitHub webhook 的内容类型设置为 application/json。设置 application/x-www-form-urlencoded 后,GitHub 会将事件作为 payload=<encoded JSON> 发送:EventListener 默认会检查正文是否为 JSON,因此它会以 HTTP 400 响应,并返回 Invalid event body format(该信息也会出现在 EventListener Pod 的日志中),并且不会运行任何拦截器。当 JSON 正文携带 Content-Type 标头时,核心拦截器日志中会出现拦截器消息 form parameter encoding not supported, please change the hook to send JSON payloads;此类请求会获得 HTTP 202 响应,并且不会创建资源。启用 addChangedFiles 或 githubOwners 时,这些步骤也可能拒绝请求。配置如下:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: github-secure-listener
spec:
  serviceAccountName: triggers-default-sa
  triggers:
    - name: github-push-secure
      interceptors:
        - ref:
            name: "github"
          params:
            - name: "secretRef"
              value:
                secretName: github-webhook-secret  # Name of the Kubernetes Secret
                secretKey: secretToken             # Key in the Secret
            - name: "eventTypes"
              value:
                - "push"
                - "pull_request"
      bindings:
        - ref: github-push-binding
      template:
        ref: build-template

工作原理:

  • GitHub 发送携带 X-Hub-Signature-256 标头的 webhook 请求,其中包含 HMAC-SHA256 签名
  • 拦截器从 Kubernetes Secret 中获取 Secret
  • 使用该 Secret 对请求正文计算 HMAC-SHA256,并验证签名
  • 设置 secretRef 后,只有签名有效的请求才允许继续处理。签名错误的请求仍会从 EventListener 获得 HTTP 202 响应,但不会创建资源;拒绝信息(payload signature check failed)只会出现在核心拦截器(tekton-triggers-core-interceptors)的日志中

参考:GitHub Webhook Security Documentation

使用 Secret 身份验证的 GitLab 拦截器

GitLab 拦截器仅在设置了 secretRef 参数时,才会使用恒定时间比较验证 webhook 令牌。如果未设置 secretRef,它不会检查令牌:当 eventTypes 未设置或列出了请求的 X-Gitlab-Event 标头时,请求会通过。配置如下:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: gitlab-secure-listener
spec:
  serviceAccountName: triggers-default-sa
  triggers:
    - name: gitlab-push-secure
      interceptors:
        - ref:
            name: "gitlab"
          params:
            - name: "secretRef"
              value:
                secretName: gitlab-webhook-secret  # Name of the Kubernetes Secret
                secretKey: secretToken             # Key in the Secret
            - name: "eventTypes"
              value:
                - "Push Hook"
                - "Merge Request Hook"
      bindings:
        - ref: gitlab-push-binding
      template:
        ref: build-template

工作原理:

  • GitLab 发送携带 X-GitLab-Token 标头的 webhook 请求,其中包含 Secret 令牌
  • 拦截器从 Kubernetes Secret 中获取 Secret
  • 使用恒定时间比较将标头值与 Secret 进行比较,以防止计时攻击
  • 设置 secretRef 后,只有令牌匹配的请求才允许继续处理。令牌错误的请求仍会从 EventListener 获得 HTTP 202 响应,但不会创建资源;拒绝信息(Invalid X-GitLab-Token)只会出现在核心拦截器(tekton-triggers-core-interceptors)的日志中

参考:GitLab Webhook Security Documentation

完整示例:安全的 GitHub Webhook 设置

下面是一个展示如何设置安全 GitHub webhook 的完整示例:

第 1 步:创建命名空间和 Secret

在 bash 或 zsh 中运行命令:在 POSIX sh(例如 dash)中,read -rs 会失败并使变量为空。创建命名空间;这需要创建 Namespace 对象的权限,通常需要集群管理员权限:

kubectl create namespace tekton-triggers-demo

单独运行 read -rs 行,然后粘贴令牌并按 Enter:

read -rs SECRET_TOKEN

然后创建 Secret 并从 shell 中删除令牌:

kubectl create secret generic github-webhook-secret \
  --from-literal=secretToken="$SECRET_TOKEN" \
  -n tekton-triggers-demo
unset SECRET_TOKEN

第 2 步:创建 TriggerBinding 和 TriggerTemplate

第 3 步中的 EventListener 会引用这两个对象。该模板会创建一个 TaskRun,用于打印推送事件的提交。TaskRun 将其步骤作为内联 taskSpec 保存;当集群设置 disable-inline-spec 包含 taskrun 时,Tekton webhook 会拒绝此类 TaskRun(请参阅 Constrain Tekton Pipeline Execution with Kyverno),因此在此类集群中,请创建一个 Task,并改用 taskRef 引用它。将 YAML 保存到文件中,并使用 kubectl apply -f <file> 应用:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: github-push-binding
  namespace: tekton-triggers-demo
spec:
  params:
    - name: revision
      value: $(body.after)
---
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: build-template
  namespace: tekton-triggers-demo
spec:
  params:
    - name: revision
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: TaskRun
      metadata:
        generateName: build-
      spec:
        taskSpec:
          steps:
            - name: echo
              image: alpine  # In air-gapped environments, replace with an image from your internal registry
              script: |
                #!/bin/sh
                echo "triggered for revision $(tt.params.revision)"

第 3 步:创建带身份验证的 EventListener

以相同方式应用以下 YAML:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: secure-github-listener
  namespace: tekton-triggers-demo
spec:
  serviceAccountName: triggers-default-sa
  triggers:
    - name: github-push-secure
      interceptors:
        - ref:
            name: "github"
          params:
            - name: "secretRef"
              value:
                secretName: github-webhook-secret
                secretKey: secretToken
            - name: "eventTypes"
              value:
                - "push"
      bindings:
        - ref: github-push-binding
      template:
        ref: build-template

第 4 步:配置 GitHub Webhook

  1. 转到 GitHub 仓库 → Settings → Webhooks → Add webhook
  2. 将 Payload URL 设置为 GitHub 可以访问的 EventListener 地址。第 3 步中的 EventListener 未设置 serviceType,因此其 Service el-secure-github-listener 只能在集群内部访问。请先按照 Network Configuration 中的说明,或使用自动暴露规则暴露它;当匹配的规则设置了 externalHosts 时,这些规则会将地址发布到 EventListener 的 status.addresses 字段中,然后在此处使用该地址
  3. 将 Content type 设置为 application/json
  4. 将 Secret 令牌粘贴到“Secret”字段中
  5. 选择要触发的事件(例如“Just the push event”)
  6. 点击“Add webhook”

第 5 步:验证设置

检查 EventListener 是否已就绪:

kubectl get eventlistener secure-github-listener -n tekton-triggers-demo

AVAILABLE 和 READY 列显示 True。向仓库执行下一次推送后,会出现一个名为 build-<suffix> 的 TaskRun,其日志包含 triggered for revision <commit SHA>:

kubectl get taskruns -n tekton-triggers-demo

读取 TaskRun 的 Pod 日志,其名称为 <taskrun-name>-pod:

kubectl logs -n tekton-triggers-demo <taskrun-name>-pod --all-containers

如果推送后没有出现 TaskRun,请按照 Troubleshooting Secret Authentication 中的说明读取核心拦截器日志和 EventListener 日志。如果两个日志中都没有推送时间附近的记录,则请求未到达 EventListener:请检查 GitHub webhook 的 Recent Deliveries 中的传送情况,以及第 4 步中的暴露配置。否则,请按照该部分中的说明操作。

要确认 secretRef 已生效,请向第 4 步中的 Payload URL 发送不带签名的推送事件,例如使用 curl(对于内部 CA 签发的证书,请添加 --cacert <ca-file>)。在集群内的 Pod 中,也可以使用 Service URL http://el-secure-github-listener.tekton-triggers-demo.svc.cluster.local:8080 作为 <payload-url>:

curl -sS -X POST -H 'Content-Type: application/json' -H 'X-GitHub-Event: push' \
  -d '{"ref":"refs/heads/main","after":"0123456789abcdef0123456789abcdef01234567"}' \
  -w '\nHTTP_STATUS %{http_code}\n' <payload-url>

正文必须包含 after,第 2 步中的 TriggerBinding 会读取该内容:没有它,就无法解析 revision 参数,即使 Trigger 没有 secretRef,也不会创建 TaskRun。EventListener 仍会响应 HTTP_STATUS 202,但 kubectl get taskruns -n tekton-triggers-demo 中不会出现新的 TaskRun,并且核心拦截器日志(请参阅 Troubleshooting Secret Authentication)会显示 no X-Hub-Signature-256 header set。日志行没有事件 ID,因此请根据请求时间进行匹配:将 --timestamps 添加到 kubectl logs 命令中,以打印每行日志的时间。如果此请求创建了 TaskRun,则说明 Trigger 没有 secretRef。

第 6 步:清理

不再需要该示例时,请删除 GitHub 仓库中的 webhook(Settings → Webhooks),以及你在第 4 步中为暴露 EventListener 而自行创建的所有对象,例如 Ingress 及其 TLS Secret。然后删除第 1-3 步中的对象以及该示例创建的 TaskRun:

kubectl delete eventlistener secure-github-listener -n tekton-triggers-demo
kubectl delete triggerbinding github-push-binding -n tekton-triggers-demo
kubectl delete triggertemplate build-template -n tekton-triggers-demo
kubectl delete secret github-webhook-secret -n tekton-triggers-demo
kubectl delete taskrun <taskrun-name> -n tekton-triggers-demo

仅当该命名空间中没有其他需要保留的内容时,才使用 kubectl delete namespace tekton-triggers-demo 删除命名空间,例如 Setup EventListener 使用的 Triggers Quick Start 对象。

Secret 身份验证故障排除

常见问题:

  1. 身份验证失败

    • 验证外部系统与 Kubernetes Secret 中的 Secret 令牌是否完全匹配
    • 检查 Secret 键名称(secretKey)是否与 Secret 中的键匹配
    • 确保 Secret 存在于 Trigger 所在的命名空间中:对于在 EventListener 中内联定义或使用 triggerRef 引用的 Trigger,使用 EventListener 的命名空间;对于通过 namespaceSelector 选择的 Trigger,使用 Trigger 自身的命名空间
  2. 找不到 Secret

    • 验证 secretRef.secretName 中的 Secret 名称是否与实际 Secret 名称匹配
    • 检查 ServiceAccount 是否具有读取 Secrets 的权限:
      - apiGroups: [""]
        resources: ["secrets"]
        verbs: ["get", "list"]
  3. 签名验证失败

    • 对于 GitHub/Bitbucket:确保 webhook 在外部系统中配置了正确的 Secret
    • 对于 GitLab:验证 X-GitLab-Token 标头是否与 Secret 令牌匹配
    • 检查核心拦截器日志,其中会记录被拒绝的签名或令牌(payload signature check failed、Invalid X-GitLab-Token)。例如,没有签名标头的 GitHub 请求(例如未设置 Secret 的 GitHub webhook)会记录为 no X-Hub-Signature-256 header set。EventListener 仍会向被拒绝的请求返回 HTTP 202。读取此日志需要 tekton-pipelines 中 Pod 日志的读取权限,通常需要集群管理员权限。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果你的安装使用其他命名空间,请在命令中替换它。标签选择器会读取 tekton-triggers-core-interceptors Deployment 中每个 Pod 的日志:
      kubectl logs -n tekton-pipelines -l app=tekton-triggers-core-interceptors --tail=-1
    • EventListener Pod 日志不会显示被拦截器拒绝的请求,但会显示 Invalid event body format 拒绝信息。使用 -l 时,除非设置了 --tail,否则 kubectl logs 只会打印最后 10 行;--tail=-1 会打印所有行:
      kubectl logs -n <namespace> -l eventlistener=<eventlistener-name> --tail=-1

参考资料