#配置 EventListener

#本文档的用途

本文档帮助你配置和部署 EventListener，用于接收来自外部系统（如 GitHub、GitLab 或自定义 Webhook）的 webhook 事件，并自动触发 Tekton pipelines。你将了解：

• 如何创建并配置 EventListener 资源
• 如何将 EventListener 暴露给外部系统（使用 Ingress、LoadBalancer 或 NodePort）
• 如何配置权限和安全设置
• 如何根据你的环境选择合适的部署策略

前提条件：你应当具备 Tekton Pipelines 和 Kubernetes 概念的基础知识。如果你是第一次接触 EventListener 概念，我们建议你先阅读 EventListener 深入理解 文档。

#概述

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

#主要特性

EventListener 具有以下主要特性：

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

#配置说明

#基本结构

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
spec:
  serviceAccountName: triggers-default-sa
  resources:
    kubernetesResource:
      serviceType: NodePort  # Service type
      servicePort: 80       # Service port
      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 端口
• spec：Pod 模板配置

#spec.triggers

定义一组触发器配置：

• name：触发器名称
• interceptors：interceptor 配置列表
• bindings：触发器 binding 配置
• template：触发器 template 配置

#安全配置

EventListener 支持多种安全配置：

1. ServiceAccount：
   • 默认 ServiceAccount（triggers-default-sa）：如果未指定 spec.serviceAccountName，EventListener 会自动使用命名空间中的 triggers-default-sa ServiceAccount。该 ServiceAccount 会自动获得 EventListener 在同一命名空间内处理 trigger 所需的命名空间级权限。这些权限会自动绑定到该 ServiceAccount 所在的命名空间。
   • 自定义 ServiceAccount：当你需要跨多个命名空间处理 trigger（例如配置了 namespaceSelector）时，必须指定具有集群级权限的自定义 ServiceAccount。请确保所指定的 ServiceAccount 已配置相应权限（请参见下方的 权限指南）。
2. Interceptor 验证：使用 CEL interceptor 进行事件验证。
3. TLS：支持配置 HTTPS 证书。

#权限指南

#默认 ServiceAccount 与自定义 ServiceAccount

• 默认 ServiceAccount（triggers-default-sa）：当未指定 spec.serviceAccountName 时，EventListener 会自动使用命名空间中的 triggers-default-sa ServiceAccount。该 ServiceAccount 会自动获得 EventListener 在同一命名空间内处理 trigger 所需的命名空间级权限。这些权限会自动绑定到该 ServiceAccount 所在的命名空间，因此你无需手动配置 Role 或 RoleBinding。

• 具有集群权限的自定义 ServiceAccount：当你配置 namespaceSelector 以监听多个命名空间中的 trigger（包括使用 '*' 监听所有命名空间）时，必须指定一个具有集群级权限的自定义 ServiceAccount。triggers-default-sa ServiceAccount 仅具有命名空间级权限，不具备跨命名空间访问资源所需的集群级权限。

#所需权限

为了正确触发 pipeline 和 tasks，EventListener 使用的 ServiceAccount 需要以下权限：

可引用的 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 触发器配置场景

EventListener 支持三种不同的 trigger 配置场景，每种都适用于不同的使用场景：

#1. 命名空间级 EventListener

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

使用场景与建议：

• 使用场景：

  • 单个项目或团队的独立部署与管理
  • 需要明确的资源隔离和权限控制
  • 团队对 EventListener 配置有深入了解，并需要对每个 trigger 进行精细化控制
  • 不同命名空间需要不同的 EventListener 配置或资源限制
  • 对性能和故障隔离有较高要求

• 推荐用于：

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

配置示例：

spec:
  # serviceAccountName 是可选的，默认为 triggers-default-sa
  triggers:
    - name: trigger-1
      bindings:
        - ref: gitlab-push
          kind: ClusterTriggerBinding
      template:
        ref: pipeline-template
    - name: trigger-2
      bindings:
        - ref: github-pullrequest
          kind: ClusterTriggerBinding
      template:
        ref: pipeline-template

#2. 项目级 EventListener

项目级 EventListener 使用 namespaceSelector 绑定多个指定命名空间中的 trigger。这适用于管理一组相关命名空间中的 trigger（例如某个项目或团队）。

使用场景与建议：

• 使用场景：

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

• 推荐用于：

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

配置示例：

spec:
  serviceAccountName: eventlistener  # 具有集群权限的自定义 SA
  namespaceSelector:
    matchNames:
      - project-a
      - project-b
      - project-c

#3. 全局级 EventListener

全局级 EventListener 使用带通配符（'*'）的 namespaceSelector 来绑定集群中所有命名空间中的 trigger。这适用于整个集群的集中式事件处理。

使用场景与建议：

• 使用场景：

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

• 推荐用于：

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

配置示例：

spec:
  serviceAccountName: eventlistener  # 具有集群权限的自定义 SA
  namespaceSelector:
    matchNames:
      - '*'  # 所有命名空间的通配符

对比表：

#规模

在不同的规划场景下，可以使用不同的配置来满足各种需求。

#网络配置

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

#NodePort 配置示例

NodePort 适用于开发、测试，或者没有配置 LoadBalancer 或 Ingress controller 的环境。该方式会在集群中每个节点的高位端口（30000-32767）上暴露 EventListener 服务。

#前提条件

• Kubernetes 集群中的节点可被外部系统访问
• 你至少知道一个节点的外部 IP 地址
• 防火墙规则应允许流量访问 NodePort 范围（30000-32767）

#配置示例

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: el-demo
  namespace: tekton-triggers-demo
spec:
  # serviceAccountName is optional, defaults to triggers-default-sa
  serviceAccountName: triggers-default-sa
  resources:
    kubernetesResource:
      serviceType: NodePort  # Use NodePort service type
      servicePort: 80        # Container port
  triggers:
    - name: hello-trigger
      bindings:
        - ref: hello-binding
      template:
        ref: hello-template

kubectl apply -f eventlistener-nodeport.yaml

# 1. 获取分配给 EventListener Service 的 NodePort
# 将 'el-el-demo' 替换为你的实际 Service 名称（格式：el-<eventlistener-name>）
# 将 'tekton-triggers-demo' 替换为你的命名空间
export NODEPORT=$(kubectl get svc el-el-demo -n tekton-triggers-demo -o jsonpath='{.spec.ports[0].nodePort}')
echo "NodePort: $NODEPORT"

# 2. 获取一个节点的外部 IP 地址
# 这里获取第一个节点的外部 IP；如果节点不能直接访问，也可以使用内部 IP
export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="ExternalIP")].address}')

# 如果没有 ExternalIP，尝试 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. 构造 webhook URL
export WEBHOOK_URL="http://${NODE_IP}:${NODEPORT}"
echo "Webhook URL: $WEBHOOK_URL"

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

# 获取所有节点外部 IP
kubectl get nodes -o jsonpath='{range .items[*]}{.status.addresses[?(@.type=="ExternalIP")].address}{"\n"}{end}'

# 如果没有外部 IP，也可以获取内部 IP
kubectl get nodes -o jsonpath='{range .items[*]}{.status.addresses[?(@.type=="InternalIP")].address}{"\n"}{end}'

# 测试 webhook 端点
curl -v -X POST -H 'Content-Type: application/json' \
  -d '{"message":"Hello from NodePort!"}' \
  $WEBHOOK_URL

# 检查 EventListener 是否就绪
kubectl get eventlistener el-demo -n tekton-triggers-demo

# 检查 Service
kubectl get svc el-el-demo -n tekton-triggers-demo

# 查看 EventListener Pod 日志
kubectl logs -n tekton-triggers-demo -l app=el-el-demo

#NodePort 重要说明

• 安全性：NodePort 使用 HTTP（而不是 HTTPS），因此不适用于对安全性要求高的生产环境
• 可访问性：节点 IP 必须能够被将要发送 webhook 的外部系统访问到
• 高可用性：如果某个节点宕机，你需要改用其他节点的 IP。可以考虑在多个节点前面放置负载均衡器
• 端口范围：NodePort 使用 30000-32767 范围内的端口。请确保防火墙允许这些端口的流量
• 多节点：你可以使用任意节点的 IP 地址，因为 NodePort 在所有节点上都可用

#何时使用 NodePort

• 开发和测试：用于本地开发或测试的快速搭建
• 内部网络：当 webhook 发送方与集群节点位于同一内部网络时
• 没有可用的 LoadBalancer：当你的集群没有 LoadBalancer Service 或 Ingress controller 时
• 成本考虑：当你希望避免 LoadBalancer 成本时

#从 NodePort 迁移到 Ingress

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

1. 更新 EventListener Service 类型：在 EventListener spec 中将 serviceType 从 NodePort 改为 ClusterIP
2. 配置自动暴露（推荐）：使用 自动暴露功能 自动创建 Ingress 资源
3. 或者手动创建 Ingress：按下面示例手动创建 Ingress 资源

下面的示例展示了如何为生产环境使用 Ingress 配置 EventListener。

#小规模 + HTTPS + ALB Ingress 配置示例

#前提条件

在使用 Ingress 配置 EventListener 之前，请确保满足以下前提条件：

1. LoadBalancer/Gateway 配置：

   • 集群中应已部署并配置 LoadBalancer 或 Gateway（例如 ALB）
   • 外部系统（将发送 webhook 的系统）应能够访问该 LoadBalancer
   • 有关配置 Load Balancer 的更多信息，请参阅 配置 Load Balancer。

2. 域名和证书设置：

   • 域名配置正确，并指向你的 LoadBalancer
   • 已准备好 TLS 证书（可以手动创建，也可以通过 cert-manager 创建）
   • DNS 记录已正确配置

3. Ingress controller：

   • 已部署并正确配置 Ingress controller（本示例中为 ALB）
   • Ingress controller 已准备好处理 Ingress 资源
   • 有关创建 Ingress 的更多信息，请参阅 创建 Ingress。

#配置示例

kubectl create namespace tekton-webhooks

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

kubectl -n tekton-webhooks create serviceaccount eventlistener
kubectl create clusterrolebinding tekton-webhooks:eventlistener:eventlistener-role --clusterrole=eventlistener-role --serviceaccount=tekton-webhooks: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 (container port)
      replicas: 2 # Replicas
      spec: # Deployment spec
        template:
          metadata:
            labels:
              el.tekton.dev/namespaces: all
              el.tekton.dev/size: small
          spec: {}

kubectl apply -f eventlistener.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: eventlistener-ingress
  annotations:
    ### Note ALB does not require setting ingressClassName
    ## kubernetes.io/ingress.class: "nginx" ## Follow changes to the ingress class, and remember to add corresponding ingress annotations.
    ### The following configuration should be customized based on requirements:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}, {"HTTP":80}]'
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
spec:
  ### Note ALB does not require setting ingressClassName
  ## ingressClassName: alb ## Change according to the required ingress class
  tls:
  - hosts:
    - <host> # Domain name setting. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    secretName: <tls secret> # Name of the secret containing TLS certificate
  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

# 测试域名可访问性（将 <host> 替换为你的实际域名）
curl -kI https://<host>

# 或测试特定的 webhook 端点
curl -kI https://<host>/triggers/<eventlistener-namespace>/<eventlistener-name>

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

## The following is the expected return format:
$> {
  "eventListener": "eventlistener",
  "namespace": "tekton-webhooks",
  "eventListenerUID": "8a7edab2-b426-453a-9f92-xxxxxx",
  "eventID": "aefd3b5b-2b19-4a14-b411-xxxxxxx"
}

#最佳实践

1. 资源限制：

   • 为 EventListener Pods 设置合适的资源请求和限制。
   • 根据实际负载调整副本数。

2. 安全性：

   • 使用 HTTPS 和 Webhook Secrets。
   • 配置最小权限的 ServiceAccount。
   • 使用 interceptor 验证所有传入事件。

3. 可用性：

   • 使用 LoadBalancer 或 Ingress 暴露服务。
   • 配置适当的健康检查。
   • 实施高可用部署。

4. 监控：

   • 监控 EventListener 日志。
   • 设置适当的告警机制。
   • 跟踪事件处理性能。

#常见问题

1. 事件未触发 pipeline

   • 检查 interceptor 配置。
   • 验证 Webhook 配置。
   • 查看 EventListener 日志。

2. 权限问题

   • 确认 ServiceAccount 权限。
   • 如果使用默认的 triggers-default-sa ServiceAccount，请验证它是否存在于该命名空间中，并且已自动获得所需权限。
   • 如果使用自定义 ServiceAccount，请检查 Role 和 RoleBinding 配置。
   • 验证命名空间访问权限。
   • 如果使用 namespaceSelector 跨命名空间监听，请确保使用的是具有集群级权限的自定义 ServiceAccount。triggers-default-sa ServiceAccount 仅具有命名空间级权限。

3. 性能问题

   • 调整资源限制。
   • 优化 interceptor 配置。
   • 考虑水平扩缩容。

#参考链接

• Tekton Triggers 官方文档
• EventListener API 参考
• Tekton Trigger 示例
• EventListener 深入理解