设置 EventListener
目录
本文档帮助您完成的操作概述主要功能配置说明基本结构主要字段说明spec.resources.kubernetesResourcespec.triggers安全配置权限指南默认 ServiceAccount 与自定义 ServiceAccount所需权限用户指南EventListener Trigger 配置场景1. 命名空间级 EventListener2. 项目级 EventListener3. 全局级 EventListener规模网络配置NodePort 配置示例前提条件配置示例NodePort 重要说明何时使用 NodePort从 NodePort 迁移到 Ingress小规模 + HTTPS + Ingress 配置示例前提条件配置示例最佳实践常见问题参考链接本文档帮助您完成的操作
本文档将帮助您配置和部署 EventListener,以接收来自外部系统(例如 GitHub、GitLab 或自定义 Webhook)的 Webhook 事件,并自动触发 Tekton pipeline。您将学习:
- 如何创建和配置 EventListener 资源
- 如何向外部系统公开 EventListener(使用 Ingress、LoadBalancer 或 NodePort)
- 如何配置权限和安全设置
- 如何根据您的环境选择合适的部署策略
前提条件:您应具备 Tekton Pipelines 和 Kubernetes 基础知识。如果您不熟悉 EventListener 概念,建议先阅读深入了解 EventListener文档。
如需深入了解 EventListener 的概念、架构和原理,请参阅深入了解 EventListener文档。
概述
EventListener 是 Tekton Triggers 中的核心资源,负责接收和处理外部事件(例如 Webhook)。当外部系统触发事件时,EventListener 会根据配置的触发器创建 Kubernetes 资源(例如 PipelineRun)。
主要功能
EventListener 具有以下主要功能:
- 事件监听:提供 HTTP 端点,用于接收来自外部系统的 Webhook 事件
- 事件过滤:使用拦截器验证和过滤接收到的事件
- 资源创建:根据触发器定义自动创建 Kubernetes 资源
- 可扩展性:支持自定义拦截器和各种事件源
- 安全性:内置多种安全机制,例如 Webhook 验证
配置说明
基本结构
主要字段说明
spec.resources.kubernetesResource
用于配置 EventListener 的 Kubernetes 资源:
serviceType:Service 类型(NodePort/ClusterIP/LoadBalancer)servicePort:Service 端口(与serviceType: NodePort一起使用时,也用作节点端口,因此必须处于 30000-32767 范围内)spec:Pod 模板配置
spec.triggers
定义一组触发器配置:
name:触发器名称interceptors:拦截器配置列表bindings:触发器绑定配置template:触发器模板配置
安全配置
EventListener 支持多种安全配置:
- ServiceAccount:
- 默认 ServiceAccount(
triggers-default-sa):显式设置spec.serviceAccountName: triggers-default-sa。如果省略该字段,EventListener 将使用config-defaults-triggersConfigMap 的default-service-account值;如果未配置,该值为default。defaultServiceAccount 没有 Triggers 权限。控制台的创建对话框会填入命名空间的默认 Triggers ServiceAccount,即标记为triggers.tekton.dev/default-service-account的 ServiceAccount(如果未配置,则为triggers-default-sa)。系统会自动向triggers-default-sa授予 EventListener 在同一命名空间内处理触发器所需的命名空间范围权限。这些权限会自动绑定到 ServiceAccount 所在的命名空间。 - 自定义 ServiceAccount:当您需要跨多个命名空间处理触发器时(例如配置了
namespaceSelector),必须指定具有集群范围权限的自定义 ServiceAccount。请确保指定的 ServiceAccount 已配置相应权限(请参阅下方的权限指南)。
- 默认 ServiceAccount(
- 拦截器验证:使用 CEL 拦截器验证事件。
- TLS:支持配置 HTTPS 证书。
权限指南
默认 ServiceAccount 与自定义 ServiceAccount
-
默认 ServiceAccount(
triggers-default-sa):显式设置spec.serviceAccountName: triggers-default-sa。如果省略该字段,EventListener 将使用config-defaults-triggersConfigMap 的default-service-account值;如果未配置,该值为default。defaultServiceAccount 没有 Triggers 权限。控制台的创建对话框会填入命名空间的默认 Triggers ServiceAccount,即标记为triggers.tekton.dev/default-service-account的 ServiceAccount(如果未配置,则为triggers-default-sa)。系统会自动向triggers-default-sa授予 EventListener 在同一命名空间内处理触发器所需的命名空间范围权限。这些权限会自动绑定到 ServiceAccount 所在的命名空间,因此您无需手动配置 Role 或 RoleBinding。 -
具有集群权限的自定义 ServiceAccount:当您配置
namespaceSelector以监听来自多个命名空间的触发器(包括所有命名空间的'*')时,必须指定具有集群范围权限的自定义 ServiceAccount。triggers-default-saServiceAccount 仅具有命名空间范围权限,没有访问跨命名空间资源所需的集群范围权限。
所需权限
为了正确触发 pipeline 和 task,EventListener 使用的 ServiceAccount 需要具备以下权限:
可参考的 ClusterRole:
用户指南
EventListener 的部署需要根据环境的规模和实际网络情况进行规划,下面介绍如何根据规划进行不同配置:
EventListener Trigger 配置场景
EventListener 支持三种不同的 Trigger 配置场景,每种场景适用于不同的使用情形:
1. 命名空间级 EventListener
命名空间级 EventListener 通过在 EventListener spec 中显式配置 triggers 字段,绑定同一命名空间中的指定 Trigger。这是最简单的场景,适用于单命名空间部署。
使用场景和建议:
-
使用场景:
- 为单个项目或团队进行独立部署和管理
- 需要明确的资源隔离和权限控制
- 团队深入了解 EventListener 配置,并需要对每个 Trigger 进行细粒度控制
- 不同命名空间需要不同的 EventListener 配置或资源限制
- 对性能和故障隔离有较高要求
-
建议用于:
- 有经验的 DevOps 团队或需要高度自定义的场景
- 不同项目需要不同的 EventListener 配置、资源配额或安全策略时
- 要求租户之间完全隔离的多租户环境
- 不同命名空间需要不同的副本数、资源限制或网络策略时
配置示例:
2. 项目级 EventListener
项目级 EventListener 使用 namespaceSelector,绑定多个指定命名空间中的 Trigger。适用于管理一组相关命名空间(例如项目或团队)中的 Trigger。
使用场景和建议:
-
使用场景:
- 多个相关项目或命名空间需要共享同一个 EventListener
- 在项目组或部门级别统一处理事件
- 需要在多个命名空间之间共享资源,但不覆盖整个集群
- 有一定的性能隔离要求,但可以接受项目组内部的资源共享
-
建议用于:
- 需要在多个相关命名空间之间统一管理 Trigger 的中型团队或项目组
- 多个项目使用相似配置和资源要求,从而降低运维成本时
- 需要集中管理一组相关项目的 Webhook 事件时
- 对 EventListener 有一定了解,能够配置和管理跨命名空间权限的团队
配置示例:
3. 全局级 EventListener
全局级 EventListener 使用 namespaceSelector 和通配符('*'),绑定集群中所有命名空间的 Trigger。适用于整个集群的集中式事件处理。
使用场景和建议:
-
使用场景:
- 集群范围内统一处理和管理事件
- 用户对性能隔离没有严格要求,可以接受资源共享
- 一次配置即可让所有用户开箱即用,无需在每个命名空间中单独配置
- 用户不需要深入了解 EventListener,由平台统一管理
- 事件量相对可控的中小型集群
-
建议用于:
- 由平台管理员统一配置和管理的平台场景
- 集群规模较小,且所有用户都需要使用相同 EventListener 配置时
- 简化用户操作流程,降低学习成本和配置复杂度
- 统一监控和故障排查的集中式运维管理
- 注意:在大型集群或高并发场景中,应考虑性能影响和故障隔离
配置示例:
对比表:
规模
在不同的规划场景中,可以使用不同的配置来满足不同的要求。
网络配置
根据环境的优先级和可用网络资源,可以选择不同的网络配置。
选择合适的网络配置
- 生产环境:使用带 HTTPS 的 LoadBalancer 或 Ingress,以确保安全性和可靠性
- 开发/测试环境:NodePort 已足够,且更易于设置
- 自动管理:如果希望系统自动创建 Ingress 资源,请使用通过
TektonConfig配置的自动暴露功能 - 手动控制:如果更倾向于手动控制 Ingress 资源,请按照下面示例手动创建
Triggers 为 EventListener 创建的 Service 有两个端口,与其 serviceType 无关:事件端口和 metrics 端口 9000(http-metrics)。因此,NodePort 或 LoadBalancer Service 会将两个端口都发布到集群外部。只有事件端口需要能够从 Git provider 访问:请使用负载均衡器、防火墙或 NetworkPolicy 限制 metrics 端口的访问,或者使用 Ingress 或自动暴露功能,这些功能会将流量路由到事件端口。
NodePort 配置示例
NodePort 适用于开发、测试,或未配置 LoadBalancer 或 Ingress controller 的环境。此方法会在集群中的每个节点上通过高位端口(30000-32767)暴露 EventListener Service。
前提条件
- 完成 快速入门中的第 2 步和第 3 步,并保留资源(跳过其中的“清理资源”步骤):此示例使用其中创建的
tekton-triggers-demo命名空间、hello-bindingTriggerBinding 和hello-templateTriggerTemplate - 具有可从外部系统访问的节点的 Kubernetes 集群
- 至少知道一个节点的外部 IP 地址
- 防火墙规则应允许流量访问 EventListener 事件端口对应的 NodePort,该端口位于 NodePort 范围(30000-32767)内;请参阅网络配置
- 运行命令的机器上需要有
curlCLI,用于在测试 NodePort Webhook中发送测试请求
配置示例
使用 NodePort Service 创建 EventListener
将以下 YAML 保存为 eventlistener-nodeport.yaml:
获取 NodePort Webhook 地址
创建 EventListener 后,需要获取 NodePort 和节点 IP,以构造 Webhook URL。kubectl get nodes 命令需要对集群范围的 nodes 资源具有读取权限,通常需要集群管理员权限;否则,NODE_IP 将保持为空:
替代方法:获取所有节点 IP 和 NodePort
Webhook URL 格式为:http://<node-ip>:<nodeport>
测试 NodePort Webhook
curl -v 输出会显示 < HTTP/1.1 202 Accepted,后跟一行 JSON:
快速入门中的 hello-template 随后会创建名为 hello-run-<suffix> 的 TaskRun。其日志包含 Hello from NodePort!:
验证 EventListener 状态
不再需要 NodePort 测试时,请删除 EventListener:
NodePort 重要说明
- 安全性:NodePort 使用 HTTP(而非 HTTPS),因此不适用于安全性要求较高的生产环境
- 可访问性:节点 IP 必须能够被发送 Webhook 的外部系统访问
- 高可用性:如果某个节点宕机,需要使用其他节点的 IP。请考虑在多个节点前配置负载均衡器
- 端口范围:NodePort 使用 30000-32767 范围内的端口。请确保防火墙允许流量访问事件端口对应的 NodePort(请参阅网络配置)
- 多个节点:可以使用任意节点的 IP 地址,因为所有节点上都可以访问该 NodePort
何时使用 NodePort
- 开发和测试:快速设置本地开发或测试环境
- 内部网络:Webhook 发送方与集群节点位于同一内部网络时
- 没有可用的 LoadBalancer:集群没有 LoadBalancer Service 或 Ingress controller 时
- 成本考虑:希望避免 LoadBalancer 成本时
生产环境建议:对于生产环境,强烈建议使用带 HTTPS 的 LoadBalancer 或 Ingress,而不是 NodePort,因为 NodePort 缺少加密和基于域名的适当路由功能。
从 NodePort 迁移到 Ingress
如果最初使用 NodePort 进行测试,现在希望迁移到使用 Ingress 的生产环境:
- 更新 EventListener Service 类型:在 EventListener spec 中,将
serviceType从NodePort修改为ClusterIP - 配置自动暴露(推荐):使用自动暴露功能自动创建 Ingress 资源
- 或手动创建 Ingress:按照下面的示例手动创建 Ingress 资源。将 Ingress 后端指向 EventListener 的 Service,即
el-<eventlistener-name>,并使用其 Service 端口:当未设置servicePort时为8080。从 Secret 设置TLS_CERT和TLS_KEY环境变量的 EventListener 会提供 HTTPS 服务;当未设置servicePort时,使用 Service 端口8443。下面的 Ingress 示例没有设置 HTTPS 后端,因此不适用于此类 listener。该示例在端口80上使用el-eventlistener,因为其 EventListener 设置了servicePort: 80
下面的示例展示了如何为生产环境设置带 Ingress 的 EventListener。
小规模 + HTTPS + Ingress 配置示例
前提条件
在配置带 Ingress 的 EventListener 之前,请确保满足以下前提条件:
-
LoadBalancer/Gateway 配置:
- 集群中应已部署并配置 LoadBalancer 或 Gateway(例如 ALB)
- LoadBalancer 应可被发送 Webhook 的外部系统访问
- 有关配置 Load Balancer 的更多信息,请参阅 Configure a Load Balancer。
-
域名和证书设置:
- 域名已正确配置,并指向 LoadBalancer
- TLS 证书已准备就绪(可以手动创建,也可以通过 cert-manager 和无需互联网访问即可工作的 issuer 创建,例如 CA issuer)
- DNS 记录已正确配置
-
Ingress Controller:
- 已正确部署和配置 Ingress controller(例如平台 ALB)。在下面的 Ingress 示例中,将
<ingress-class>设置为该 controller 的 IngressClass(kubectl get ingressclass会列出这些 IngressClass) - Ingress controller 已准备好处理 Ingress 资源
- 有关创建 Ingress 的更多信息,请参阅 Creating Ingresses。
- 在 Alauda Container Platform 上,可以将 ALB 限制为某些项目的命名空间。如果 ALB 以这种方式受到限制,则 EventListener 命名空间必须属于其中一个项目(在控制台中创建,或使用
kubectl label namespace tekton-webhooks cpaas.io/project=<project>添加标签),然后才能创建 Ingress。否则,Ingress 不会获得地址,对<host>的请求会到达 ALB 的默认服务器,而不是 EventListener。添加标签需要更新 Namespace 对象的权限,通常需要集群管理员权限。如果在 Ingress 已存在后添加标签,请删除 Ingress 并重新创建,然后检查kubectl get ingress eventlistener-ingress -n tekton-webhooks是否显示ADDRESS。
- 已正确部署和配置 Ingress controller(例如平台 ALB)。在下面的 Ingress 示例中,将
注意:如果使用自动暴露功能(通过 TektonConfig 配置),通常无需手动创建 Ingress 资源。系统会根据导出规则自动创建这些资源。本示例展示了手动创建 Ingress 的方式,适用于希望手动控制或未使用自动暴露功能的情况。自动暴露会将流量路由到 EventListener Service 的 8080 端口;仅当未设置 servicePort,且 EventListener 未设置 TLS_CERT 和 TLS_KEY 环境变量时,该端口才是 Service 端口(设置这些环境变量后,监听器会提供 HTTPS,且 Service 没有 8080 端口)。如果对此 EventListener 使用自动暴露,请从下面的示例中移除 servicePort: 80。
配置示例
创建 Namespace(可选)
确保存在一个 Namespace,以便管理 EventListener 和其他权限;此处使用 tekton-webhooks 作为示例。在 Alauda Container Platform 上,如果 ALB 仅限于某些项目的命名空间,请按照前提条件 3 中的说明,在创建 Ingress 之前将其加入其中一个项目;添加项目标签需要更新 Namespace 对象的权限,通常需要集群管理员权限。创建 Namespace 需要创建 Namespace 对象的权限,通常需要集群管理员权限。
创建 ClusterRole 和 ServiceAccount 并设置权限
-
默认 ServiceAccount(
triggers-default-sa):显式设置spec.serviceAccountName: triggers-default-sa。如果省略该设置,EventListener 将使用config-defaults-triggersConfigMap 中的default-service-account值;除非另行配置,否则该值为default。defaultServiceAccount 没有 Triggers 权限。控制台的创建对话框会填入命名空间的默认 Triggers ServiceAccount,即标记为triggers.tekton.dev/default-service-account的 ServiceAccount(除非另行配置,否则为triggers-default-sa)。系统会自动向triggers-default-sa授予 EventListener 在同一命名空间中处理触发器所需的命名空间范围权限。权限会自动绑定到 ServiceAccount 所在的命名空间,因此无需手动配置 Role 或 RoleBinding。 -
具有集群权限的自定义 ServiceAccount:当配置
namespaceSelector以监听来自多个命名空间的触发器(包括'*',即所有命名空间)时,必须指定具有集群范围权限的自定义 ServiceAccount。triggers-default-saServiceAccount 仅具有命名空间范围权限,不具备跨命名空间访问资源所需的集群范围权限。
namespaceSelector 必需:仅当使用 namespaceSelector 监听多个命名空间中的触发器时,才需要执行以下步骤。如果 EventListener 仅处理同一命名空间中的触发器,则可以跳过这些步骤,并设置 serviceAccountName: triggers-default-sa;该 ServiceAccount 会自动获得所需权限。
以下 YAML 用于 eventlistener-role.yaml。
使用上述 ClusterRole 和 ServiceAccount 创建绑定。
创建 ClusterRole 和 ClusterRoleBinding 需要集群管理员权限。ClusterRoleBinding 会向 eventlistener ServiceAccount 授予 eventlistener-role 在每个命名空间中的权限,包括对 Secrets 的 get、list 和 watch 权限,以及创建 PipelineRuns 和 TaskRuns 的权限。仅将此 ServiceAccount 用于服务多个命名空间的 EventListener。
创建 EventListener
将以下 YAML 保存为 eventlistener.yaml。
ServiceAccount 选择:
- 如果只需要处理同一命名空间中的触发器,请设置
serviceAccountName: triggers-default-sa;该 ServiceAccount 会自动获得所需的命名空间范围权限。如果省略该设置,EventListener 将使用config-defaults-triggersConfigMap 中的default-service-account值;除非另行配置,否则该值为default。defaultServiceAccount 没有 Triggers 权限。 - 由于此示例使用
namespaceSelector和'*'监听所有命名空间中的触发器,因此需要具有集群范围权限的自定义 ServiceAccount。因此,此处指定了serviceAccountName: "eventlistener"。
创建 Ingress 和 TLS Secrets
需要将 <host> 设置为相应的域名和证书信息。
使用 <host> 的证书和密钥文件创建 TLS Secret:
暴露:此 Ingress 会发布一个服务所有命名空间触发器的 EventListener。仅在发送 Webhook 的网络上暴露它,优先使用 HTTPS,并要求监听器服务的每个触发器都进行 Webhook 身份验证;请参阅 Webhook Secret 身份验证。
将以下 Ingress 保存为 eventlistener-ingress.yaml:
DNS 配置:使用域名配置 host 字段时,请确保:
- DNS 记录已正确配置,可将域名解析到 Ingress controller 的 IP 地址
- 对于本地测试,可以将域名添加到
/etc/hosts(Linux/Mac)或C:\Windows\System32\drivers\etc\hosts(Windows) - 将发送 Webhook 的系统(GitHub、GitLab 等)必须能够解析该域名
验证域名可访问性
配置域名和 Ingress 后,请确保 Webhook 域名可访问:
curl -kI 会发送不带正文的 HEAD 请求。EventListener 返回带有 content-type: application/json 的 400 响应,表示 EventListener 拒绝了空正文,同时也表明域名已到达监听器。
-k 会跳过证书检查,因此这些命令不会显示 Ingress 提供的证书。请单独检查证书:
subject: 和 issuer: 行必须显示 <tls-secret-name> 中证书的信息。如果显示的是其他证书,例如 ALB 的默认证书,则说明 Ingress 未加载,或未使用该 Secret。
重要:确保基于 LoadBalancer 的 Webhook 域名可从外部系统(例如 GitHub、GitLab 或其他 Webhook 发送方)访问。如果域名不可访问,Webhook 将失败。请检查:
- DNS 记录配置正确且已完成传播
- LoadBalancer 配置正确,并具有外部 IP/域名
- 防火墙规则允许流量访问 LoadBalancer
- TLS 证书有效(如果使用 HTTPS)
验证 Webhook 配置
可以使用以下 curl 测试配置是否正常。
请求到达 EventListener 后,它会返回一行 JSON,例如:
最佳实践
-
资源限制:
- 为 EventListener Pod 设置资源请求和限制。可以从基本结构示例中的值开始(请求
64Mi内存和250mCPU,限制128Mi和500m),然后根据观察到的 EventListener Pod 的 CPU 和内存使用情况进行调整。 - 根据实际负载调整副本数(
replicas,如创建 EventListener中所示)。
- 为 EventListener Pod 设置资源请求和限制。可以从基本结构示例中的值开始(请求
-
安全性:
- 使用 HTTPS 和 Webhook Secret:请参阅创建 Ingress 和 TLS Secret、验证域名可访问性中的证书检查,以及Webhook Secret 身份验证。
- 配置具有最小权限的 ServiceAccount。
- 使用拦截器验证所有传入事件,如Webhook Secret 身份验证中所述。
-
可用性:
- 使用 LoadBalancer 或 Ingress 暴露服务;请参阅网络配置和配置 EventListener 自动暴露规则。
- 实施高可用部署,例如在创建 EventListener中使用
replicas: 2。
-
监控:
- 监控 EventListener 日志,如验证 EventListener 状态中所示。
- 使用Tekton 组件的指标收集中所述的 EventListener sink 指标跟踪事件处理性能。
常见问题
-
事件未触发 Pipeline
- 检查拦截器配置。
- 验证 Webhook 配置。
- 查看核心拦截器日志,如Secret 身份验证故障排除中所述:在随附的
info日志级别下,EventListener 日志不会显示拦截器拒绝信息。
-
权限问题
- 确认 ServiceAccount 权限。
- 如果使用默认的
triggers-default-saServiceAccount,请确认它存在于命名空间中,并且已自动授予所需权限。 - 如果使用自定义 ServiceAccount,请检查 Role 和 RoleBinding 配置。
- 验证命名空间访问权限。
- 如果使用
namespaceSelector跨命名空间监听,请确保使用具有集群范围权限的自定义 ServiceAccount。triggers-default-saServiceAccount 仅具有命名空间范围的权限。
-
性能问题
- 调整资源限制。
- 优化拦截器配置。
- 考虑水平扩展。