#配置 EventListener

#本文档将帮助你完成的内容

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

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

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

#概述

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

#主要特性

EventListener 具有以下主要特性：

• 事件监听：提供一个 HTTP 端点，用于接收来自外部系统的 Webhook 事件
• 事件过滤：使用 interceptors 验证并过滤接收到的事件
• 资源创建：根据 trigger 定义自动创建 Kubernetes 资源
• 可扩展性：支持自定义 interceptors 和多种事件来源
• 安全性：内置多种安全机制，例如 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 将自动使用所在 namespace 中的 triggers-default-sa ServiceAccount。该 ServiceAccount 会自动获得 EventListener 在同一 namespace 内处理 triggers 所需的 namespace 级权限。这些权限会自动绑定到该 ServiceAccount 所在的 namespace。
   • 自定义 ServiceAccount：当你需要跨多个 namespace 处理 triggers（例如配置了 namespaceSelector）时，必须指定一个具有 cluster 级权限的自定义 ServiceAccount。请确保所指定的 ServiceAccount 已配置相应权限（参见下方的 权限指南）。
2. Interceptor 验证：使用 CEL interceptors 进行事件验证。
3. TLS：支持配置 HTTPS 证书。

#权限指南

#默认 ServiceAccount 与自定义 ServiceAccount

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

• 具有 Cluster 权限的自定义 ServiceAccount：当你配置 namespaceSelector 以监听多个 namespace 的 triggers（包括用于所有 namespace 的 '*'）时，必须指定一个具有 cluster 级权限的自定义 ServiceAccount。triggers-default-sa ServiceAccount 仅具有 namespace 级权限，不具备跨 namespace 访问资源所需的 cluster 级权限。

#所需权限

为了正确触发 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 Trigger 配置场景

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

#1. Namespace 级 EventListener

Namespace 级 EventListener 通过在 EventListener spec 中显式配置 triggers 字段，将其绑定到同一 namespace 内的特定 triggers。这是最简单的场景，适用于单 namespace 部署。

使用场景与建议：

• 使用场景：

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

• 推荐用于：

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

配置示例：

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 来绑定多个指定 namespace 中的 triggers。这适用于管理一组相关 namespace 中的 triggers（例如一个项目或团队）。

使用场景与建议：

• 使用场景：

  • 多个相关项目或 namespace 需要共享同一个 EventListener
  • 在项目组或部门层面进行统一事件处理
  • 需要在多个 namespace 之间共享资源，但不希望覆盖整个集群
  • 有一定的性能隔离要求，但可以接受项目组内资源共享

• 推荐用于：

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

配置示例：

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

#3. 全局级 EventListener

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

使用场景与建议：

• 使用场景：

  • 集群范围内统一的事件处理和管理
  • 用户对性能隔离没有严格要求，可以接受资源共享
  • 一次配置后即可让所有用户开箱即用，无需在每个 namespace 中分别配置
  • 用户不需要深入了解 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 配置示例

#前提条件

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

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

2. 安全性：

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

3. 可用性：

   • 通过 LoadBalancer 或 Ingress 暴露服务。
   • 配置合适的健康检查。
   • 实现高可用部署。

4. 监控：

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

#常见问题

1. 事件未触发 Pipeline

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

2. 权限问题

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

3. 性能问题

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

#参考链接

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