设置 EventListener

本文档帮助您完成的操作

本文档将帮助您配置和部署 EventListener,以接收来自外部系统(例如 GitHub、GitLab 或自定义 Webhook)的 Webhook 事件,并自动触发 Tekton pipeline。您将学习:

  • 如何创建和配置 EventListener 资源
  • 如何向外部系统公开 EventListener(使用 Ingress、LoadBalancer 或 NodePort)
  • 如何配置权限和安全设置
  • 如何根据您的环境选择合适的部署策略

前提条件:您应具备 Tekton Pipelines 和 Kubernetes 基础知识。如果您不熟悉 EventListener 概念,建议先阅读深入了解 EventListener文档。

TIP

如需深入了解 EventListener 的概念、架构和原理,请参阅深入了解 EventListener文档。

概述

EventListener 是 Tekton Triggers 中的核心资源,负责接收和处理外部事件(例如 Webhook)。当外部系统触发事件时,EventListener 会根据配置的触发器创建 Kubernetes 资源(例如 PipelineRun)。

主要功能

EventListener 具有以下主要功能:

  • 事件监听:提供 HTTP 端点,用于接收来自外部系统的 Webhook 事件
  • 事件过滤:使用拦截器验证和过滤接收到的事件
  • 资源创建:根据触发器定义自动创建 Kubernetes 资源
  • 可扩展性:支持自定义拦截器和各种事件源
  • 安全性:内置多种安全机制,例如 Webhook 验证

配置说明

基本结构

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
spec:
  serviceAccountName: triggers-default-sa
  resources:
    kubernetesResource:
      serviceType: NodePort  # Service type
      spec:
        template:
          spec:
            containers:
              - resources:    # Resource limits
                  requests:
                    memory: "64Mi"
                    cpu: "250m"
                  limits:
                    memory: "128Mi"
                    cpu: "500m"
  triggers:                  # Trigger configuration
    - name: trigger-1       # Trigger name
      interceptors:         # Interceptor configuration
        - ref:
            name: "cel"
          params:
            - name: "filter"
              value: "header.match('X-GitHub-Event', 'pull_request')"
      bindings:            # Trigger bindings
        - ref: pipeline-binding
      template:            # Trigger template
        ref: pipeline-template

主要字段说明

spec.resources.kubernetesResource

用于配置 EventListener 的 Kubernetes 资源:

  • serviceType:Service 类型(NodePort/ClusterIP/LoadBalancer)
  • servicePort:Service 端口(与 serviceType: NodePort 一起使用时,也用作节点端口,因此必须处于 30000-32767 范围内)
  • spec:Pod 模板配置

spec.triggers

定义一组触发器配置:

  • name:触发器名称
  • interceptors:拦截器配置列表
  • bindings:触发器绑定配置
  • template:触发器模板配置

安全配置

EventListener 支持多种安全配置:

  1. ServiceAccount:
    • 默认 ServiceAccount(triggers-default-sa):显式设置 spec.serviceAccountName: triggers-default-sa。如果省略该字段,EventListener 将使用 config-defaults-triggers ConfigMap 的 default-service-account 值;如果未配置,该值为 default。default ServiceAccount 没有 Triggers 权限。控制台的创建对话框会填入命名空间的默认 Triggers ServiceAccount,即标记为 triggers.tekton.dev/default-service-account 的 ServiceAccount(如果未配置,则为 triggers-default-sa)。系统会自动向 triggers-default-sa 授予 EventListener 在同一命名空间内处理触发器所需的命名空间范围权限。这些权限会自动绑定到 ServiceAccount 所在的命名空间。
    • 自定义 ServiceAccount:当您需要跨多个命名空间处理触发器时(例如配置了 namespaceSelector),必须指定具有集群范围权限的自定义 ServiceAccount。请确保指定的 ServiceAccount 已配置相应权限(请参阅下方的权限指南)。
  2. 拦截器验证:使用 CEL 拦截器验证事件。
  3. TLS:支持配置 HTTPS 证书。

权限指南

默认 ServiceAccount 与自定义 ServiceAccount

  • 默认 ServiceAccount(triggers-default-sa):显式设置 spec.serviceAccountName: triggers-default-sa。如果省略该字段,EventListener 将使用 config-defaults-triggers ConfigMap 的 default-service-account 值;如果未配置,该值为 default。default ServiceAccount 没有 Triggers 权限。控制台的创建对话框会填入命名空间的默认 Triggers ServiceAccount,即标记为 triggers.tekton.dev/default-service-account 的 ServiceAccount(如果未配置,则为 triggers-default-sa)。系统会自动向 triggers-default-sa 授予 EventListener 在同一命名空间内处理触发器所需的命名空间范围权限。这些权限会自动绑定到 ServiceAccount 所在的命名空间,因此您无需手动配置 Role 或 RoleBinding。

  • 具有集群权限的自定义 ServiceAccount:当您配置 namespaceSelector 以监听来自多个命名空间的触发器(包括所有命名空间的 '*')时,必须指定具有集群范围权限的自定义 ServiceAccount。triggers-default-sa ServiceAccount 仅具有命名空间范围权限,没有访问跨命名空间资源所需的集群范围权限。

所需权限

为了正确触发 pipeline 和 task,EventListener 使用的 ServiceAccount 需要具备以下权限:

权限资源描述
get, list, watchconfigmaps读取 ConfigMap
get, list, watchsecrets读取 Secret
get, list, watchserviceaccounts读取 ServiceAccount
create, get, list, watch, patch, updatedeployments管理 Deployment
create, get, list, watch, patch, updateservices管理 Service
create, get, list, watch, patch, updatepods管理 Pod
create, get, list, watch, patch, updateevents管理 Event
createpipelineruns创建 PipelineRun
createtaskruns创建 TaskRun
get, list, watchclustertriggerbindings读取 ClusterTriggerBinding
get, list, watchtriggerbindings读取 TriggerBinding
get, list, watchclusterinterceptors读取 ClusterInterceptor
get, list, watchinterceptors读取 Interceptor
get, list, watchtriggers读取 Trigger
get, list, watchtriggertemplates读取 TriggerTemplate
get, list, watcheventlisteners读取 EventListener

可参考的 ClusterRole:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eventlistener-role
rules:
- apiGroups: [""]
  resources: ["configmaps", "secrets", "serviceaccounts"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: [""]
  resources: ["services", "pods", "events"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: ["tekton.dev"]
  resources: ["pipelineruns", "taskruns"]
  verbs: ["create"]
- apiGroups: ["triggers.tekton.dev"]
  resources:
    - "clustertriggerbindings"
    - "triggerbindings"
    - "clusterinterceptors"
    - "interceptors"
    - "triggers"
    - "triggertemplates"
    - "eventlisteners"
  verbs:
    - "get"
    - "list"
    - "watch"

用户指南

EventListener 的部署需要根据环境的规模和实际网络情况进行规划,下面介绍如何根据规划进行不同配置:

EventListener Trigger 配置场景

EventListener 支持三种不同的 Trigger 配置场景,每种场景适用于不同的使用情形:

1. 命名空间级 EventListener

命名空间级 EventListener 通过在 EventListener spec 中显式配置 triggers 字段,绑定同一命名空间中的指定 Trigger。这是最简单的场景,适用于单命名空间部署。

使用场景和建议:

  • 使用场景:

    • 为单个项目或团队进行独立部署和管理
    • 需要明确的资源隔离和权限控制
    • 团队深入了解 EventListener 配置,并需要对每个 Trigger 进行细粒度控制
    • 不同命名空间需要不同的 EventListener 配置或资源限制
    • 对性能和故障隔离有较高要求
  • 建议用于:

    • 有经验的 DevOps 团队或需要高度自定义的场景
    • 不同项目需要不同的 EventListener 配置、资源配额或安全策略时
    • 要求租户之间完全隔离的多租户环境
    • 不同命名空间需要不同的副本数、资源限制或网络策略时

配置示例:

spec:
  # serviceAccountName defaults to "default-service-account" in config-defaults-triggers ("default" unless configured),
  # which has no Triggers permissions; set it to triggers-default-sa explicitly. The console create dialog fills in
  # the namespace's default Triggers ServiceAccount (labelled triggers.tekton.dev/default-service-account).
  serviceAccountName: triggers-default-sa
  triggers:
    - name: trigger-1
      bindings:
        - ref: gitlab-push
          kind: ClusterTriggerBinding
      template:
        ref: pipeline-template
    - name: trigger-2
      bindings:
        - ref: gitlab-mergerequest
          kind: ClusterTriggerBinding
      template:
        ref: pipeline-template

2. 项目级 EventListener

项目级 EventListener 使用 namespaceSelector,绑定多个指定命名空间中的 Trigger。适用于管理一组相关命名空间(例如项目或团队)中的 Trigger。

使用场景和建议:

  • 使用场景:

    • 多个相关项目或命名空间需要共享同一个 EventListener
    • 在项目组或部门级别统一处理事件
    • 需要在多个命名空间之间共享资源,但不覆盖整个集群
    • 有一定的性能隔离要求,但可以接受项目组内部的资源共享
  • 建议用于:

    • 需要在多个相关命名空间之间统一管理 Trigger 的中型团队或项目组
    • 多个项目使用相似配置和资源要求,从而降低运维成本时
    • 需要集中管理一组相关项目的 Webhook 事件时
    • 对 EventListener 有一定了解,能够配置和管理跨命名空间权限的团队

配置示例:

spec:
  serviceAccountName: eventlistener  # Custom SA with cluster permissions
  namespaceSelector:
    matchNames:
      - project-a
      - project-b
      - project-c

3. 全局级 EventListener

全局级 EventListener 使用 namespaceSelector 和通配符('*'),绑定集群中所有命名空间的 Trigger。适用于整个集群的集中式事件处理。

使用场景和建议:

  • 使用场景:

    • 集群范围内统一处理和管理事件
    • 用户对性能隔离没有严格要求,可以接受资源共享
    • 一次配置即可让所有用户开箱即用,无需在每个命名空间中单独配置
    • 用户不需要深入了解 EventListener,由平台统一管理
    • 事件量相对可控的中小型集群
  • 建议用于:

    • 由平台管理员统一配置和管理的平台场景
    • 集群规模较小,且所有用户都需要使用相同 EventListener 配置时
    • 简化用户操作流程,降低学习成本和配置复杂度
    • 统一监控和故障排查的集中式运维管理
    • 注意:在大型集群或高并发场景中,应考虑性能影响和故障隔离

配置示例:

spec:
  serviceAccountName: eventlistener  # Custom SA with cluster permissions
  namespaceSelector:
    matchNames:
      - '*'  # Wildcard for all namespaces

对比表:

场景命名空间范围ServiceAccount配置复杂度使用场景
命名空间级单个命名空间triggers-default-sa(显式设置)简单单个项目/团队
项目级多个指定命名空间自定义 SA(集群权限)中等多个相关项目
全局级所有命名空间(*)自定义 SA(集群权限)复杂集群范围管理

规模

在不同的规划场景中,可以使用不同的配置来满足不同的要求。

规模Trigger 数量资源设置
小规模2(Trigger)* 100(命名空间)* 10(Pipeline)= 2,000 个 Trigger/集群两个或更多副本;从基本结构示例中的 requests 和 limits 开始,然后根据观察到的使用情况进行调整(参见下方的最佳实践)
中等规模2(Trigger)* 1,000(命名空间)* 10(Pipeline)= 20,000 个 Trigger/集群两个或更多副本;从基本结构示例中的 requests 和 limits 开始,然后根据观察到的使用情况进行调整(参见下方的最佳实践);按命名空间部署不同的 EventListener

网络配置

根据环境的优先级和可用网络资源,可以选择不同的网络配置。

网络配置协议描述
官方域名和证书https通过 ClusterIP + Ingress 设置 TLS 证书
自定义域名和证书https使用自签名证书进行 TLS。注意:工具端配置存在风险,并非所有工具/平台都支持跳过或忽略 TLS 验证。
NodePorthttp通过 NodePort + 集群 / 节点 IP 设置可访问地址
TIP

选择合适的网络配置

  • 生产环境:使用带 HTTPS 的 LoadBalancer 或 Ingress,以确保安全性和可靠性
  • 开发/测试环境:NodePort 已足够,且更易于设置
  • 自动管理:如果希望系统自动创建 Ingress 资源,请使用通过 TektonConfig 配置的自动暴露功能
  • 手动控制:如果更倾向于手动控制 Ingress 资源,请按照下面示例手动创建

Triggers 为 EventListener 创建的 Service 有两个端口,与其 serviceType 无关:事件端口和 metrics 端口 9000(http-metrics)。因此,NodePort 或 LoadBalancer Service 会将两个端口都发布到集群外部。只有事件端口需要能够从 Git provider 访问:请使用负载均衡器、防火墙或 NetworkPolicy 限制 metrics 端口的访问,或者使用 Ingress 或自动暴露功能,这些功能会将流量路由到事件端口。

NodePort 配置示例

NodePort 适用于开发、测试,或未配置 LoadBalancer 或 Ingress controller 的环境。此方法会在集群中的每个节点上通过高位端口(30000-32767)暴露 EventListener Service。

前提条件

  • 完成 快速入门中的第 2 步和第 3 步,并保留资源(跳过其中的“清理资源”步骤):此示例使用其中创建的 tekton-triggers-demo 命名空间、hello-binding TriggerBinding 和 hello-template TriggerTemplate
  • 具有可从外部系统访问的节点的 Kubernetes 集群
  • 至少知道一个节点的外部 IP 地址
  • 防火墙规则应允许流量访问 EventListener 事件端口对应的 NodePort,该端口位于 NodePort 范围(30000-32767)内;请参阅网络配置
  • 运行命令的机器上需要有 curl CLI,用于在测试 NodePort Webhook中发送测试请求

配置示例

使用 NodePort Service 创建 EventListener

将以下 YAML 保存为 eventlistener-nodeport.yaml:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: el-demo
  namespace: tekton-triggers-demo
spec:
  # serviceAccountName defaults to "default-service-account" in config-defaults-triggers ("default" unless configured),
  # which has no Triggers permissions; set it to triggers-default-sa explicitly. The console create dialog fills in
  # the namespace's default Triggers ServiceAccount (labelled triggers.tekton.dev/default-service-account).
  serviceAccountName: triggers-default-sa
  resources:
    kubernetesResource:
      serviceType: NodePort  # Use NodePort service type
  triggers:
    - name: hello-trigger
      bindings:
        - ref: hello-binding
      template:
        ref: hello-template
kubectl apply -f eventlistener-nodeport.yaml

获取 NodePort Webhook 地址

创建 EventListener 后,需要获取 NodePort 和节点 IP,以构造 Webhook URL。kubectl get nodes 命令需要对集群范围的 nodes 资源具有读取权限,通常需要集群管理员权限;否则,NODE_IP 将保持为空:

# 1. Get the NodePort assigned to the EventListener service
# Replace 'el-el-demo' with your actual service name (format: el-<eventlistener-name>)
# Replace 'tekton-triggers-demo' with your namespace
export NODEPORT=$(kubectl get svc el-el-demo -n tekton-triggers-demo -o jsonpath='{.spec.ports[0].nodePort}')
echo "NodePort: $NODEPORT"

# 2. Get a node's external IP address
# This gets the first node's external IP, you can also use internal IP if nodes are not directly accessible
export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="ExternalIP")].address}')

# If no ExternalIP, try InternalIP
if [ -z "$NODE_IP" ]; then
  export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
fi
echo "Node IP: $NODE_IP"

# 3. Construct the webhook URL
export WEBHOOK_URL="http://${NODE_IP}:${NODEPORT}"
echo "Webhook URL: $WEBHOOK_URL"

替代方法:获取所有节点 IP 和 NodePort

# Get NodePort
NODEPORT=$(kubectl get svc el-el-demo -n tekton-triggers-demo -o jsonpath='{.spec.ports[0].nodePort}')

# Get all node external IPs
kubectl get nodes -o jsonpath='{range .items[*]}{.status.addresses[?(@.type=="ExternalIP")].address}{"\n"}{end}'

# Or get internal IPs if external IPs are not available
kubectl get nodes -o jsonpath='{range .items[*]}{.status.addresses[?(@.type=="InternalIP")].address}{"\n"}{end}'

Webhook URL 格式为:http://<node-ip>:<nodeport>

测试 NodePort Webhook

# Test the webhook endpoint
curl -v -X POST -H 'Content-Type: application/json' \
  -d '{"message":"Hello from NodePort!"}' \
  $WEBHOOK_URL

curl -v 输出会显示 < HTTP/1.1 202 Accepted,后跟一行 JSON:

{"eventListener":"el-demo","namespace":"tekton-triggers-demo","eventListenerUID":"<eventlistener-uid>","eventID":"<event-id>"}

快速入门中的 hello-template 随后会创建名为 hello-run-<suffix> 的 TaskRun。其日志包含 Hello from NodePort!:

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

验证 EventListener 状态

# Check EventListener is ready
kubectl get eventlistener el-demo -n tekton-triggers-demo

# Check the service
kubectl get svc el-el-demo -n tekton-triggers-demo

# View EventListener Pod logs (with -l, kubectl logs prints only the last 10 lines unless --tail is set)
kubectl logs -n tekton-triggers-demo -l eventlistener=el-demo --tail=-1

不再需要 NodePort 测试时,请删除 EventListener:

kubectl delete eventlistener el-demo -n tekton-triggers-demo

NodePort 重要说明

  • 安全性:NodePort 使用 HTTP(而非 HTTPS),因此不适用于安全性要求较高的生产环境
  • 可访问性:节点 IP 必须能够被发送 Webhook 的外部系统访问
  • 高可用性:如果某个节点宕机,需要使用其他节点的 IP。请考虑在多个节点前配置负载均衡器
  • 端口范围:NodePort 使用 30000-32767 范围内的端口。请确保防火墙允许流量访问事件端口对应的 NodePort(请参阅网络配置)
  • 多个节点:可以使用任意节点的 IP 地址,因为所有节点上都可以访问该 NodePort

何时使用 NodePort

  • 开发和测试:快速设置本地开发或测试环境
  • 内部网络:Webhook 发送方与集群节点位于同一内部网络时
  • 没有可用的 LoadBalancer:集群没有 LoadBalancer Service 或 Ingress controller 时
  • 成本考虑:希望避免 LoadBalancer 成本时
WARNING

生产环境建议:对于生产环境,强烈建议使用带 HTTPS 的 LoadBalancer 或 Ingress,而不是 NodePort,因为 NodePort 缺少加密和基于域名的适当路由功能。

从 NodePort 迁移到 Ingress

如果最初使用 NodePort 进行测试,现在希望迁移到使用 Ingress 的生产环境:

  1. 更新 EventListener Service 类型:在 EventListener spec 中,将 serviceType 从 NodePort 修改为 ClusterIP
  2. 配置自动暴露(推荐):使用自动暴露功能自动创建 Ingress 资源
  3. 或手动创建 Ingress:按照下面的示例手动创建 Ingress 资源。将 Ingress 后端指向 EventListener 的 Service,即 el-<eventlistener-name>,并使用其 Service 端口:当未设置 servicePort 时为 8080。从 Secret 设置 TLS_CERT 和 TLS_KEY 环境变量的 EventListener 会提供 HTTPS 服务;当未设置 servicePort 时,使用 Service 端口 8443。下面的 Ingress 示例没有设置 HTTPS 后端,因此不适用于此类 listener。该示例在端口 80 上使用 el-eventlistener,因为其 EventListener 设置了 servicePort: 80

下面的示例展示了如何为生产环境设置带 Ingress 的 EventListener。

小规模 + HTTPS + Ingress 配置示例

前提条件

在配置带 Ingress 的 EventListener 之前,请确保满足以下前提条件:

  1. LoadBalancer/Gateway 配置:

    • 集群中应已部署并配置 LoadBalancer 或 Gateway(例如 ALB)
    • LoadBalancer 应可被发送 Webhook 的外部系统访问
    • 有关配置 Load Balancer 的更多信息,请参阅 Configure a Load Balancer。
  2. 域名和证书设置:

    • 域名已正确配置,并指向 LoadBalancer
    • TLS 证书已准备就绪(可以手动创建,也可以通过 cert-manager 和无需互联网访问即可工作的 issuer 创建,例如 CA issuer)
    • DNS 记录已正确配置
  3. Ingress Controller:

    • 已正确部署和配置 Ingress controller(例如平台 ALB)。在下面的 Ingress 示例中,将 <ingress-class> 设置为该 controller 的 IngressClass(kubectl get ingressclass 会列出这些 IngressClass)
    • Ingress controller 已准备好处理 Ingress 资源
    • 有关创建 Ingress 的更多信息,请参阅 Creating Ingresses。
    • 在 Alauda Container Platform 上,可以将 ALB 限制为某些项目的命名空间。如果 ALB 以这种方式受到限制,则 EventListener 命名空间必须属于其中一个项目(在控制台中创建,或使用 kubectl label namespace tekton-webhooks cpaas.io/project=<project> 添加标签),然后才能创建 Ingress。否则,Ingress 不会获得地址,对 <host> 的请求会到达 ALB 的默认服务器,而不是 EventListener。添加标签需要更新 Namespace 对象的权限,通常需要集群管理员权限。如果在 Ingress 已存在后添加标签,请删除 Ingress 并重新创建,然后检查 kubectl get ingress eventlistener-ingress -n tekton-webhooks 是否显示 ADDRESS。
INFO

注意:如果使用自动暴露功能(通过 TektonConfig 配置),通常无需手动创建 Ingress 资源。系统会根据导出规则自动创建这些资源。本示例展示了手动创建 Ingress 的方式,适用于希望手动控制或未使用自动暴露功能的情况。自动暴露会将流量路由到 EventListener Service 的 8080 端口;仅当未设置 servicePort,且 EventListener 未设置 TLS_CERT 和 TLS_KEY 环境变量时,该端口才是 Service 端口(设置这些环境变量后,监听器会提供 HTTPS,且 Service 没有 8080 端口)。如果对此 EventListener 使用自动暴露,请从下面的示例中移除 servicePort: 80。

配置示例

创建 Namespace(可选)

确保存在一个 Namespace,以便管理 EventListener 和其他权限;此处使用 tekton-webhooks 作为示例。在 Alauda Container Platform 上,如果 ALB 仅限于某些项目的命名空间,请按照前提条件 3 中的说明,在创建 Ingress 之前将其加入其中一个项目;添加项目标签需要更新 Namespace 对象的权限,通常需要集群管理员权限。创建 Namespace 需要创建 Namespace 对象的权限,通常需要集群管理员权限。

kubectl create namespace tekton-webhooks

创建 ClusterRole 和 ServiceAccount 并设置权限

  • 默认 ServiceAccount(triggers-default-sa):显式设置 spec.serviceAccountName: triggers-default-sa。如果省略该设置,EventListener 将使用 config-defaults-triggers ConfigMap 中的 default-service-account 值;除非另行配置,否则该值为 default。default ServiceAccount 没有 Triggers 权限。控制台的创建对话框会填入命名空间的默认 Triggers ServiceAccount,即标记为 triggers.tekton.dev/default-service-account 的 ServiceAccount(除非另行配置,否则为 triggers-default-sa)。系统会自动向 triggers-default-sa 授予 EventListener 在同一命名空间中处理触发器所需的命名空间范围权限。权限会自动绑定到 ServiceAccount 所在的命名空间,因此无需手动配置 Role 或 RoleBinding。

  • 具有集群权限的自定义 ServiceAccount:当配置 namespaceSelector 以监听来自多个命名空间的触发器(包括 '*',即所有命名空间)时,必须指定具有集群范围权限的自定义 ServiceAccount。triggers-default-sa ServiceAccount 仅具有命名空间范围权限,不具备跨命名空间访问资源所需的集群范围权限。

WARNING

namespaceSelector 必需:仅当使用 namespaceSelector 监听多个命名空间中的触发器时,才需要执行以下步骤。如果 EventListener 仅处理同一命名空间中的触发器,则可以跳过这些步骤,并设置 serviceAccountName: triggers-default-sa;该 ServiceAccount 会自动获得所需权限。

以下 YAML 用于 eventlistener-role.yaml。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eventlistener-role
rules:
- apiGroups: [""]
  resources: ["configmaps", "secrets", "serviceaccounts"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: [""]
  resources: ["services", "pods", "events"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: ["tekton.dev"]
  resources: ["pipelineruns", "taskruns"]
  verbs: ["create"]
- apiGroups: ["triggers.tekton.dev"]
  resources:
    - "clustertriggerbindings"
    - "triggerbindings"
    - "clusterinterceptors"
    - "interceptors"
    - "triggers"
    - "triggertemplates"
    - "eventlisteners"
  verbs:
    - "get"
    - "list"
    - "watch"
kubectl apply -f eventlistener-role.yaml

使用上述 ClusterRole 和 ServiceAccount 创建绑定。

kubectl -n tekton-webhooks create serviceaccount eventlistener
kubectl create clusterrolebinding tekton-webhooks:eventlistener:eventlistener-role --clusterrole=eventlistener-role --serviceaccount=tekton-webhooks:eventlistener

创建 ClusterRole 和 ClusterRoleBinding 需要集群管理员权限。ClusterRoleBinding 会向 eventlistener ServiceAccount 授予 eventlistener-role 在每个命名空间中的权限,包括对 Secrets 的 get、list 和 watch 权限,以及创建 PipelineRuns 和 TaskRuns 的权限。仅将此 ServiceAccount 用于服务多个命名空间的 EventListener。

创建 EventListener

将以下 YAML 保存为 eventlistener.yaml。

INFO

ServiceAccount 选择:

  • 如果只需要处理同一命名空间中的触发器,请设置 serviceAccountName: triggers-default-sa;该 ServiceAccount 会自动获得所需的命名空间范围权限。如果省略该设置,EventListener 将使用 config-defaults-triggers ConfigMap 中的 default-service-account 值;除非另行配置,否则该值为 default。default ServiceAccount 没有 Triggers 权限。
  • 由于此示例使用 namespaceSelector 和 '*' 监听所有命名空间中的触发器,因此需要具有集群范围权限的自定义 ServiceAccount。因此,此处指定了 serviceAccountName: "eventlistener"。
apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
  namespace: tekton-webhooks
  labels:
    el.tekton.dev/namespaces: all
    el.tekton.dev/size: small
spec:
  serviceAccountName: "eventlistener" # Required: Custom SA with cluster permissions needed for namespaceSelector
  # Listen to triggers from all namespaces
  namespaceSelector:
    matchNames:
    - '*'
  # Declare Kubernetes resource, default is Deployment
  resources:
    kubernetesResource:
      serviceType: ClusterIP # ClusterIP service type
      servicePort: 80  # Service port; the EventListener container listens on 8080
      replicas: 2 # Replicas
      spec: # Deployment spec
        template:
          metadata:
            labels:
              el.tekton.dev/namespaces: all
              el.tekton.dev/size: small
          spec:
            containers:
              - resources: # Start values from the Basic Structure sample
                  requests:
                    memory: "64Mi"
                    cpu: "250m"
                  limits:
                    memory: "128Mi"
                    cpu: "500m"
kubectl apply -f eventlistener.yaml

创建 Ingress 和 TLS Secrets

Info

需要将 <host> 设置为相应的域名和证书信息。

使用 <host> 的证书和密钥文件创建 TLS Secret:

kubectl create secret tls <tls-secret-name> --cert=<cert-file> --key=<key-file> -n tekton-webhooks
WARNING

暴露:此 Ingress 会发布一个服务所有命名空间触发器的 EventListener。仅在发送 Webhook 的网络上暴露它,优先使用 HTTPS,并要求监听器服务的每个触发器都进行 Webhook 身份验证;请参阅 Webhook Secret 身份验证。

将以下 Ingress 保存为 eventlistener-ingress.yaml:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: eventlistener-ingress
  namespace: tekton-webhooks  # Same namespace as the EventListener Service el-eventlistener
  # Add the annotations that your Ingress controller needs
spec:
  ingressClassName: <ingress-class>  # IngressClass of your Ingress controller; list them with kubectl get ingressclass
  tls:
  - hosts:
    - <host> # Domain name setting. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    secretName: <tls-secret-name> # Name of the secret containing TLS certificate, in the tekton-webhooks namespace
  rules:
  - host: <host> # Domain name setting. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: el-eventlistener 
            port:
              number: 80
kubectl apply -f eventlistener-ingress.yaml
WARNING

DNS 配置:使用域名配置 host 字段时,请确保:

  • DNS 记录已正确配置,可将域名解析到 Ingress controller 的 IP 地址
  • 对于本地测试,可以将域名添加到 /etc/hosts(Linux/Mac)或 C:\Windows\System32\drivers\etc\hosts(Windows)
  • 将发送 Webhook 的系统(GitHub、GitLab 等)必须能够解析该域名

验证域名可访问性

配置域名和 Ingress 后,请确保 Webhook 域名可访问:

# Test domain accessibility (replace <host> with your actual domain)
curl -kI https://<host>

# Or test the specific webhook endpoint
curl -kI https://<host>/triggers/<eventlistener-namespace>/<eventlistener-name>

curl -kI 会发送不带正文的 HEAD 请求。EventListener 返回带有 content-type: application/json 的 400 响应,表示 EventListener 拒绝了空正文,同时也表明域名已到达监听器。

-k 会跳过证书检查,因此这些命令不会显示 Ingress 提供的证书。请单独检查证书:

curl -sS -k -v -o /dev/null https://<host>/ 2>&1 | grep -E 'subject:|issuer:'

subject: 和 issuer: 行必须显示 <tls-secret-name> 中证书的信息。如果显示的是其他证书,例如 ALB 的默认证书,则说明 Ingress 未加载,或未使用该 Secret。

WARNING

重要:确保基于 LoadBalancer 的 Webhook 域名可从外部系统(例如 GitHub、GitLab 或其他 Webhook 发送方)访问。如果域名不可访问,Webhook 将失败。请检查:

  • DNS 记录配置正确且已完成传播
  • LoadBalancer 配置正确,并具有外部 IP/域名
  • 防火墙规则允许流量访问 LoadBalancer
  • TLS 证书有效(如果使用 HTTPS)

验证 Webhook 配置

可以使用以下 curl 测试配置是否正常。

curl -k -X POST -H 'Content-Type: application/json' -d '{"hello": "world"}' https://<host>/triggers/<eventlistener-namespace>/<eventlistener-name>

请求到达 EventListener 后,它会返回一行 JSON,例如:

{"eventListener":"<eventlistener-name>","namespace":"<eventlistener-namespace>","eventListenerUID":"<eventlistener-uid>","eventID":"<event-id>"}

最佳实践

  1. 资源限制:

    • 为 EventListener Pod 设置资源请求和限制。可以从基本结构示例中的值开始(请求 64Mi 内存和 250m CPU,限制 128Mi 和 500m),然后根据观察到的 EventListener Pod 的 CPU 和内存使用情况进行调整。
    • 根据实际负载调整副本数(replicas,如创建 EventListener中所示)。
  2. 安全性:

  3. 可用性:

  4. 监控:

常见问题

  1. 事件未触发 Pipeline

    • 检查拦截器配置。
    • 验证 Webhook 配置。
    • 查看核心拦截器日志,如Secret 身份验证故障排除中所述:在随附的 info 日志级别下,EventListener 日志不会显示拦截器拒绝信息。
  2. 权限问题

    • 确认 ServiceAccount 权限。
    • 如果使用默认的 triggers-default-sa ServiceAccount,请确认它存在于命名空间中,并且已自动授予所需权限。
    • 如果使用自定义 ServiceAccount,请检查 Role 和 RoleBinding 配置。
    • 验证命名空间访问权限。
    • 如果使用 namespaceSelector 跨命名空间监听,请确保使用具有集群范围权限的自定义 ServiceAccount。triggers-default-sa ServiceAccount 仅具有命名空间范围的权限。
  3. 性能问题

    • 调整资源限制。
    • 优化拦截器配置。
    • 考虑水平扩展。

参考链接