配置 EventListener

TIP

如需深入了解 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: tekton-triggers-sa  # 可选,用于指定 ServiceAccount
  resources:
    kubernetesResource:
      serviceType: NodePort  # Service 类型
      servicePort: 80       # Service 端口
      spec:
        template:
          spec:
            containers:
              - resources:    # 资源限制
                  requests:
                    memory: "64Mi"
                    cpu: "250m"
                  limits:
                    memory: "128Mi"
                    cpu: "500m"
  triggers:                  # Trigger 配置
    - name: trigger-1       # Trigger 名称
      interceptors:         # Interceptor 配置
        - ref:
            name: "cel"
          params:
            - name: "filter"
              value: "header.match('X-GitHub-Event', 'pull_request')"
      bindings:            # Trigger 绑定
        - ref: pipeline-binding
      template:            # Trigger 模板
        ref: pipeline-template

主要字段说明

spec.resources.kubernetesResource

用于配置 EventListener 的 Kubernetes 资源:

  • serviceType:Service 类型(NodePort/虚拟 IP/负载均衡器)
  • servicePort:Service 端口
  • spec:Pod 模板配置

spec.triggers

定义一组 trigger 配置:

  • name:Trigger 名称
  • interceptors:Interceptor 配置列表
  • bindings:Trigger 绑定配置
  • template:Trigger 模板配置

安全配置

EventListener 支持多种安全配置:

  1. ServiceAccount:通过 spec.serviceAccountName 指定运行权限。请确保所指定的 ServiceAccount 已配置相应权限。
  2. Interceptor 验证:使用 CEL interceptor 进行事件验证。
  3. TLS:支持配置 HTTPS 证书。

权限指南

为了正确触发 Pipeline 和 Task,EventListener 使用的 ServiceAccount 需要以下权限:

权限资源描述
get, list, watchconfigmaps读取 ConfigMaps
get, list, watchsecrets读取 Secrets
get, list, watchserviceaccounts读取 ServiceAccounts
create, get, list, watch, patch, updatedeployments管理 Deployments
create, get, list, watch, patch, updateservices管理 Services
create, get, list, watch, patch, updatepods管理 Pods
create, get, list, watch, patch, updateevents管理 Events
createpipelineruns创建 PipelineRuns
createtaskruns创建 TaskRuns
get, list, watchclustertriggerbindings读取 ClusterTriggerBindings
get, list, watchtriggerbindings读取 TriggerBindings
get, list, watchclusterinterceptors读取 ClusterInterceptors
get, list, watchinterceptors读取 Interceptors
get, list, watchtriggers读取 Triggers
get, list, watchtriggertemplates读取 TriggerTemplates
get, list, watcheventlisteners读取 EventListeners

可参考的 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 需要根据规模和环境中的实际网络情况进行规划,下面说明如何根据规划进行不同配置:

规模

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

规模Trigger 数量资源设置
小规模2 (triggers) * 100 (namespaces) * 10 (pipelines) = 2,000 triggers/cluster中等配置,两个以上副本
中规模2 (triggers) * 1,000 (namespaces) * 10 (pipelines) = 20,000 triggers/cluster中等配置,两个以上副本,按 Namespace 部署不同的 EventListener

网络配置

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

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

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

前提条件

  1. 已正确配置域名,并已准备好相应证书。
  2. ALB 已部署并正确配置。

配置示例

创建 Namespace(可选)

请确保存在一个便于管理 EventListener 和其他权限的 Namespace;这里以 tekton-webhooks 为例。

kubectl create namespace tekton-webhooks

创建 EventListener

将以下 YAML 保存为 eventlistener.yaml。

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" # 自定义 SA
  # 监听来自所有 NS 的 triggers
  namespaceSelector:
    matchNames:
    - '*'
  # 声明 Kubernetes 资源,默认是 Deployment
  resources:
    kubernetesResource:
      serviceType: ClusterIP # ClusterIP Service 类型
      servicePort: 80  # Service 端口(container port)
      replicas: 2 # 副本数
      spec: # Deployment spec
        template:
          metadata:
            labels:
              el.tekton.dev/namespaces: all
              el.tekton.dev/size: small
          spec: {}
kubectl apply -f eventlistener.yaml

创建 ClusterRole

以下 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

创建 ServiceAccount 并设置权限

使用上面的 ClusterRole 和 ServiceAccount 创建绑定。

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

创建 Ingress 和 TLS Secret

Info

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: eventlistener-ingress
  annotations:
    ### 注意:ALB 不需要设置 ingressClassName
    ## kubernetes.io/ingress.class: "nginx" ## 请根据 ingress class 的变化进行调整,并记得添加相应的 ingress 注解。
    ### 以下配置应根据需求进行自定义:
    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:
  ### 注意:ALB 不需要设置 ingressClassName
  ## ingressClassName: alb ## 请根据需要的 ingress class 进行调整
  tls:
  - hosts:
    - <host> # 域名设置
    secretName: <tls secret> # 包含 TLS 证书的 secret 名称
  rules:
  - host: <host> # 域名设置
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: el-eventlistener 
            port:
              number: 80

验证 Webhook 配置

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

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

## 以下为预期返回格式:
$> {
  "eventListener": "eventlistener",
  "namespace": "tekton-webhooks",
  "eventListenerUID": "8a7edab2-b426-453a-9f92-xxxxxx",
  "eventID": "aefd3b5b-2b19-4a14-b411-xxxxxxx"
}

最佳实践

  1. 资源限制:

    • 为 EventListener Pods 设置适当的资源请求和限制。
    • 根据实际负载调整副本数。
  2. 安全性:

    • 使用 HTTPS 和 Webhook Secret。
    • 配置最小权限的 ServiceAccount。
    • 使用 interceptor 验证所有传入事件。
  3. 可用性:

    • 使用 LoadBalancer 或 Ingress 暴露 Service。
    • 配置合适的健康检查。
    • 实现高可用部署。
  4. 监控:

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

常见问题

  1. 事件未触发 Pipeline

    • 检查 interceptor 配置。
    • 验证 Webhook 配置。
    • 查看 EventListener 日志。
  2. 权限问题

    • 确认 ServiceAccount 权限。
    • 检查 Role 和 RoleBinding。
    • 验证 Namespace 访问权限。
  3. 性能问题

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

参考链接