#配置 EventListener

#本文可帮助你完成的内容

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

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

前提条件：你应当对 Tekton Pipelines 和 Kubernetes 概念有基本了解。如果你是首次接触 EventListener 概念，建议先阅读 深入理解 EventListener 文档。

#概述

EventListener 是 Tekton Triggers 中的核心资源，负责接收和处理外部事件（如 Webhook）。当外部系统触发事件时，EventListener 会根据已配置的 trigger 创建 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

定义一组 trigger 配置：

• name：Trigger 名称
• interceptors：Interceptor 配置列表
• bindings：Trigger binding 配置
• template：Trigger 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 和 task，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 Trigger 配置场景

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

#1. 命名空间级 EventListener

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

适用场景和建议：

• 适用场景：

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

• 推荐用于：

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

配置示例：

spec:
  # serviceAccountName is optional, defaults to 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  # 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

对比表：

#规模

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

#网络配置

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

#NodePort 配置示例

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

#前提条件

• 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. 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"

# 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}'

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

# 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
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）
   • 外部系统应能够访问该 LoadBalancer，以便发送 webhook
   • 有关配置 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

# 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 -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 Pod 设置合适的资源 requests 和 limits。
   • 根据实际负载调整副本数。

2. 安全性：

   • 使用 HTTPS 和 Webhook Secret。
   • 配置最小权限的 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