简体中文

设置事件监听器

TIP

要深入理解事件监听器的概念、架构和原理，请参考深入理解事件监听器文档。

概述

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

主要特性

事件监听器具有以下主要特性：

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

配置说明

基本结构

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
spec:
  serviceAccountName: tekton-triggers-sa  # 可选，用于指定 ServiceAccount
  resources:
    kubernetesResource:
      serviceType: NodePort  # 服务类型
      servicePort: 80       # 服务端口
      spec:
        template:
          spec:
            containers:
              - resources:    # 资源限制
                  requests:
                    memory: "64Mi"
                    cpu: "250m"
                  limits:
                    memory: "128Mi"
                    cpu: "500m"
  triggers:                  # 触发器配置
    - name: trigger-1       # 触发器名称
      interceptors:         # 拦截器配置
        - ref:
            name: "cel"
          params:
            - name: "filter"
              value: "header.match('X-GitHub-Event', 'pull_request')"
      bindings:            # 触发器绑定
        - ref: pipeline-binding
      template:            # 触发器模板
        ref: pipeline-template

主要字段描述

spec.resources.kubernetesResource

用于配置事件监听器的 Kubernetes 资源：

serviceType: 服务类型（NodePort/ClusterIP/LoadBalancer）
servicePort: 服务端口
spec: Pod 模板配置

spec.triggers

定义一组触发器配置：

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

安全配置

事件监听器支持多种安全配置：

ServiceAccount：通过 spec.serviceAccountName 指定运行权限。确保指定的 ServiceAccount 配置了相应的权限。
拦截器验证：使用 CEL 拦截器进行事件验证。
TLS：支持配置 HTTPS 证书。

权限指南

为了正确触发管道和任务，事件监听器使用的 ServiceAccount 需要以下权限：

权限	资源	描述
get, list, watch	configmaps	读取 ConfigMaps
get, list, watch	secrets	读取 Secrets
get, list, watch	serviceaccounts	读取 ServiceAccounts
create, get, list, watch, patch, update	deployments	管理 Deployments
create, get, list, watch, patch, update	services	管理 Services
create, get, list, watch, patch, update	pods	管理 Pods
create, get, list, watch, patch, update	events	管理 Events
create	pipelineruns	创建 PipelineRuns
create	taskruns	创建 TaskRuns
get, list, watch	clustertriggerbindings	读取 ClusterTriggerBindings
get, list, watch	triggerbindings	读取 TriggerBindings
get, list, watch	clusterinterceptors	读取 ClusterInterceptors
get, list, watch	interceptors	读取 Interceptors
get, list, watch	triggers	读取 Triggers
get, list, watch	triggertemplates	读取 TriggerTemplates
get, list, watch	eventlisteners	读取 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"]

用户指南

部署事件监听器需要根据环境的规模和实际网络状况进行规划，以下是如何根据规划不同配置的说明：

规模

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

规模	触发器数量	资源设置
小规模	2（触发器）* 100（命名空间）* 10（管道）= 2,000 触发器/集群	中等，两个以上副本
中规模	2（触发器）* 1,000（命名空间）* 10（管道）= 20,000 触发器/集群	中等，两个以上副本，按命名空间部署不同的事件监听器

网络配置

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

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

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

前提条件

域名配置正确，相应的证书已到位。
已部署并正确配置 ALB。

配置示例

创建命名空间（可选）

确保有一个命名空间以便于管理事件监听器及其他权限；这里以 tekton-webhooks 为例。

kubectl create namespace tekton-webhooks

创建事件监听器

将以下 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 的触发器
  namespaceSelector:
    matchNames:
    - '*'
  # 声明 Kubernetes 资源，默认为 Deployment
  resources:
    kubernetesResource:
      serviceType: ClusterIP # ClusterIP 服务类型
      servicePort: 80  # 服务端口（容器端口）
      replicas: 2 # 副本数
      spec: # Deployment 规格
        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 秘密

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 类进行更改
  tls:
  - hosts:
    - <host> # 域名设置
    secretName: <tls secret> # 包含 TLS 证书的秘密名称
  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"
}

最佳实践

资源限制：
- 为事件监听器 Pods 设置适当的资源请求和限制。
- 根据实际负载调整副本数量。
安全性：
- 使用 HTTPS 和 Webhook 秘密。
- 配置最低权限的 ServiceAccount。
- 使用拦截器验证所有传入的事件。
可用性：
- 通过 LoadBalancer 或 Ingress 暴露服务。
- 配置适当的健康检查。
- 实施高可用部署。
监控：
- 监控事件监听器日志。
- 设置适当的警报机制。
- 跟踪事件处理性能。

常见问题

事件未触发管道
- 检查拦截器配置。
- 验证 Webhook 配置。
- 查看事件监听器日志。
权限问题
- 确认 ServiceAccount 权限。
- 检查 Role 和 RoleBinding。
- 验证命名空间访问权限。
性能问题
- 调整资源限制。
- 优化拦截器配置。
- 考虑横向扩展。

参考链接

本页概览

核心概念

实用指南

问题处理

概念

核心概念

概念

核心概念

Kubernetes APIs

Operator

管道

Triggers

高级 API

Results

设置事件监听器

目录

概述

主要特性

配置说明

基本结构

主要字段描述

spec.resources.kubernetesResource

spec.triggers

安全配置

权限指南

用户指南

规模

网络配置

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

前提条件

配置示例

创建命名空间（可选）

创建事件监听器

创建 ClusterRole

创建 ServiceAccount 并设置权限

创建 Ingress 和 TLS 秘密

验证 Webhook 配置

最佳实践

常见问题

参考链接

Operator

管道

Triggers

Results

#设置事件监听器

#目录

#概述

#主要特性

#配置说明

#基本结构

#主要字段描述

#spec.resources.kubernetesResource

#spec.triggers

#安全配置

#权限指南

#用户指南

#规模

#网络配置

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

#前提条件

#配置示例

#创建命名空间（可选）

#创建事件监听器

#创建 ClusterRole

#创建 ServiceAccount 并设置权限

#创建 Ingress 和 TLS 秘密

#验证 Webhook 配置

#最佳实践

#常见问题

#参考链接

设置事件监听器

目录

概述

主要特性

配置说明

基本结构

主要字段描述

spec.resources.kubernetesResource

spec.triggers

安全配置

权限指南

用户指南

规模

网络配置

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

前提条件

配置示例

创建命名空间（可选）

创建事件监听器

创建 ClusterRole

创建 ServiceAccount 并设置权限

创建 Ingress 和 TLS 秘密

验证 Webhook 配置

最佳实践

常见问题

参考链接