快速开始
本指南将通过创建一个简单的“Hello World”触发器场景,帮助你开始使用 Tekton Triggers,并演示其基本功能。本指南包含以下步骤:
- 配置自动
EventListener暴露规则,以便将EventListeners暴露到外部 - 创建
EventListener及相关资源 - 从
EventListener状态中获取自动生成的 webhook 地址
目录
前提条件步骤 1:配置 EventListener 自动暴露规则前提条件步骤 2:创建示例项目步骤 3:创建 Hello World TaskRun替代方案:简单测试设置选项 A:使用端口转发(最简单)选项 B:使用 NodePort步骤 4:获取 Webhook 地址并进行测试(使用自动暴露)下一步常见问题前提条件
-
环境要求
Kubernetes版本 1.21 或更高- 已安装
Tekton Operator - 确保已通过 Operator 安装并准备好
Tekton Triggers
-
所需工具
kubectl命令行工具curl(用于测试触发器)
-
权限
- 需要集群管理员权限(用于配置
EventListener自动暴露规则) - 需要命名空间管理员权限(用于创建
EventListener资源)
- 需要集群管理员权限(用于配置
步骤 1:配置 EventListener 自动暴露规则
关于自动暴露功能
这是 Alauda 平台增强功能(不是标准 Tekton Triggers 的一部分),用于简化 EventListener 外部访问配置。
暴露 EventListener 的三种方式:
-
自动暴露(Alauda 增强功能) ⭐ 推荐用于生产环境
- 自动创建和管理
Ingress资源 - 通过
TektonConfig进行集中式配置 - webhook URL 自动填充到
EventListener状态中 - 最适合包含多个
EventListeners的生产环境
- 自动创建和管理
-
手动 Ingress(标准 Tekton 方法)
- 为每个
EventListener手动创建Ingress资源 - 控制力更强,但需要更多维护工作
- 标准 Kubernetes 方法
- 为每个
-
Port-Forward 或 NodePort(测试/开发) 🚀 最容易上手
- 无需
Ingress或 DNS 配置 - 非常适合本地测试和学习
- 如果希望快速开始,请参阅跳转到简单测试设置
- 无需
如果你刚开始使用 Triggers,可以跳过此步骤,直接跳转到简单测试设置部分,通过 port-forward 开始。准备好进行生产部署后,再回来配置自动暴露。
EventListener 自动暴露功能会根据你配置的导出规则,为符合条件的 EventListeners 自动创建 Ingress 资源。这样无需手动创建和管理 Ingress 资源。你需要先配置这些规则,以便通过外部 URL 访问 EventListeners。有关详细配置说明,请参阅配置 EventListener 自动暴露规则。
前提条件
在配置导出规则之前,请确保已满足以下前提条件:
-
LoadBalancer 或 Gateway 配置(推荐用于生产环境):
- 对于生产环境,建议使用
LoadBalancer或Gateway来暴露EventListeners - 应配置并确保可访问
LoadBalancer/Gateway - 你应拥有将用于 webhook 的外部域名或 IP 地址
- 对于生产环境,建议使用
-
Ingress Controller(如果使用 Ingress):
- 集群中应已安装并运行
Ingresscontroller(例如NGINX、ALB或Traefik) - 你应知道将使用的
IngressClass名称 - 有关创建 Ingress 的更多信息,请参阅 创建 Ingress。
- 集群中应已安装并运行
-
域名和证书(用于 HTTPS):
- 如果使用 HTTPS,请确保已配置域名
- 应准备好 TLS 证书(手动创建或通过
cert-manager创建)
重要说明:
- 自动暴露功能会根据导出规则自动为你创建
Ingress资源。通常无需手动创建或修改Ingress资源。 - 如果使用带自定义端口的
LoadBalancer,请确保在externalHosts字段中包含该端口(例如https://webhooks.example.com:8443)。 - 对于开发或测试环境,也可以使用
NodePort代替Ingress/LoadBalancer。有关详细信息,请参阅 NodePort 配置示例。
通过 TektonConfig 配置导出规则
创建或更新 TektonConfig 资源以配置导出规则。创建文件 tektonconfig.yaml:
了解自动暴露
自动暴露功能的工作方式如下:
- 读取你在
TektonConfig中配置的导出规则 - 自动为符合规则的
EventListeners创建Ingress资源 - 将 webhook URL 填充到
EventListener的status.addresses字段中,以便在 UI 中显示 - 无需为每个
EventListener手动创建和管理Ingress资源
这种方法提供了集中管理 EventListeners 暴露方式的途径,更易于在集群中维护一致的 webhook URL 模式。
选择 Ingress 配置方法
自动暴露功能支持两种配置 Ingress 以从外部暴露 EventListener 的方法。请选择最适合你环境的方法:
替代方案:NodePort 配置
如果没有 LoadBalancer 或 Ingress controller,或者希望在开发/测试环境中使用更简单的设置,也可以使用 NodePort。有关详细信息,请参阅 NodePort 配置示例。使用 NodePort 时不需要自动暴露功能,因为你可以直接通过节点 IP 和 NodePort 访问 EventListener。
方法 1:通用 Ingress 配置(推荐用于生产环境)
此方法适用于大多数 Kubernetes 环境。你需要:
-
创建 IngressClass(如果尚未创建): 有关更多信息,请参阅 创建 Ingress。
-
或者使用 LoadBalancer Service 获取外部 IP 地址 有关更多信息,请参阅 配置负载均衡器。
-
根据 Ingress 设置配置导出规则:
- 如果使用 IngressClass:将
ingressClass设置为你的 IngressClass 名称(例如nginx) - 如果使用 LoadBalancer:从 LoadBalancer service 获取外部 IP/域名,并相应配置
host和externalHosts
- 如果使用 IngressClass:将
IngressClass 配置示例:
DNS 配置:在使用域名配置 host 字段时,请确保:
- DNS 记录已正确配置,可将域名解析到 Ingress controller 的 IP 地址
- 对于本地测试,可以将域名添加到
/etc/hosts(Linux/Mac)或C:\Windows\System32\drivers\etc\hosts(Windows) - 将发送 webhook 的系统(GitHub、GitLab 等)必须能够解析该域名
方法 2:ACP 业务集群快速开始
如果使用 ACP(Alauda Container Platform)业务集群,可以利用平台内置的 gateway 快速完成设置:
- 获取 ACP 平台访问地址(例如
https://192.168.1.100) - 获取集群名称(例如
test) - 按如下方式配置导出规则:
- 将
host设置为空(或使用通配符*) - 将
externalHosts设置为:<ACP Platform Access Address>/clusters-rewrite/<Cluster Name> - 最终 webhook URL 将为:
<externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>
- 将
ACP 配置示例:
使用此配置后,webhook 地址将为:
ACP 配置公式:
- ACP 平台 URL:
https://192.168.1.100 - 集群名称:
test - URL 路径前缀:
/triggers(可配置) - 外部主机:
https://192.168.1.100/clusters-rewrite/test - 最终 webhook URL:
https://192.168.1.100/clusters-rewrite/test/triggers/<eventlistener-namespace>/<eventlistener-name>
示例:如果 ACP 平台地址为 https://192.168.1.100,集群名称为 test,且 urlPathPrefix 为 /triggers,则访问地址为 https://192.168.1.100/clusters-rewrite/test/triggers。
重要:请将占位值(webhooks.example.com、nginx 等)替换为实际的域名、Ingress class 和外部主机 URL。如果尚未配置域名,可以使用空的 host 字段,并将 externalHosts 配置为实际可访问的 URL。
应用 TektonConfig
验证配置
等待片刻,让 Operator 同步配置,然后进行验证:
ConfigMap 应包含你的导出规则配置。(注意:ConfigMap 名称 trigger-wrapper-config 是内部技术名称;你无需记住它,因为你可以通过 TektonConfig 管理配置。)
步骤 2:创建示例项目
创建命名空间
关于 EventListener 的 ServiceAccount
在此快速开始中,我们将使用由 Tekton Triggers 系统自动创建的默认 ServiceAccount。此 ServiceAccount 名为 triggers-default-sa,并具有命名空间范围内的权限。
工作原理:
- 安装
Tekton Triggers后,它会在每个命名空间中自动创建一个默认的ServiceAccount - 运行
kubectl get sa -n tekton-triggers-demo -l triggers.tekton.dev/default-service-account即可查找它 - 此
ServiceAccount具有在同一命名空间内创建TaskRuns和PipelineRuns的权限 - 无需手动配置——只需通过名称引用它:
triggers-default-sa
需要自定义 ServiceAccount 的情况:
- 需要在多个命名空间中创建资源(跨命名空间触发器)
- 需要超出默认范围的其他权限
- 有关自定义
ServiceAccount配置,请参阅 设置 EventListener
步骤 3:创建 Hello World TaskRun
创建 Task
创建文件 hello-task.yaml:
创建 Trigger Template
创建文件 trigger-template.yaml:
创建 Trigger Binding
创建文件 trigger-binding.yaml:
创建 EventListener
创建文件 event-listener.yaml:
ServiceAccount 注意事项:我们使用自动创建的默认 ServiceAccount(将 serviceAccountName 设置为 triggers-default-sa)。此 ServiceAccount 由 Tekton Triggers 系统创建,并具有在同一命名空间内创建 TaskRuns/PipelineRuns 的权限。由于所有资源都位于同一命名空间中,这对于本示例来说已经足够。根据步骤 1 中配置的导出规则,自动暴露功能会为此 EventListener 自动创建一个 Ingress。
应用配置
应用所有已创建的资源:
替代方案:简单测试设置
如果您跳过了步骤 1(自动暴露配置)并希望快速进行测试,可以使用 端口转发 或 NodePort 访问 EventListener,无需任何 Ingress 或 DNS 设置。
选项 A:使用端口转发(最简单)
等待 EventListener 就绪
将本地端口转发到 EventListener
保持此终端处于打开状态。现在可以通过 http://localhost:8080 访问 EventListener。
通过端口转发发送测试请求
打开一个新终端并运行:
查看结果
选项 B:使用 NodePort
如果无需 Ingress,希望从本地计算机外部访问 EventListener:
将 EventListener Service 修补为 NodePort
Triggers controller 管理 el-hello-listener Service,并会还原对其进行的直接编辑,因此请改为在 EventListener 上设置 Service 类型:
获取 NodePort
通过 NodePort 发送测试请求
各方法的适用场景:
- 端口转发:本地测试、开发、学习
- NodePort:从其他计算机进行测试、开发集群
- 自动暴露(Ingress):生产部署、外部 webhook(GitHub、GitLab 等)
步骤 4:获取 Webhook 地址并进行测试(使用自动暴露)
等待 EventListener 就绪
获取自动生成的 Webhook 地址
自动暴露功能会根据步骤 1 中配置的导出规则,自动生成外部 webhook 地址。这些地址会填充到 EventListener 的 status.addresses 字段中:
地址格式:Webhook 地址遵循以下模式:<externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>
例如:https://webhooks.example.com/triggers/tekton-triggers-demo/hello-listener
如果 status.addresses 为空,请检查:
- 您配置的导出规则是否匹配
EventListener的命名空间 - 自动暴露 controller 是否正在运行并已处理
EventListener - 查看 controller 日志:
kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller
网络访问:确保外部主机 URL 可从您进行测试的位置访问。如果您在集群内进行测试,可能需要使用端口转发,或改为访问内部 Service 地址。
验证 Webhook 域名是否可访问
发送测试请求前,请验证您的 webhook 域名是否可访问:
重要:确保基于 LoadBalancer/Gateway 的 webhook 域名可从外部系统访问。如果您在 GitHub、GitLab 或其他外部系统中配置 webhook,这些系统必须能够访问此 URL。请检查:
- DNS 记录配置是否正确
- LoadBalancer/Gateway 是否已正确配置并可访问
- 防火墙规则是否允许入站流量
- TLS 证书是否有效(如果使用 HTTPS)
向 Webhook 发送测试请求
查看结果
清理资源
测试完成后,可以删除已创建的资源:
下一步
现在,你已成功创建并测试了一个基本的 Tekton Triggers 示例,可以:
- 探索 Tekton Triggers 的相关概念
- 了解如何使用 设置 EventListener 获取常见的设置说明
- 配置 EventListener 自动暴露规则 以支持高级暴露场景
- 设置并使用 Gitlab 事件 来触发流水线
常见问题
-
EventListener Pod 启动失败
- 检查默认的
ServiceAccount是否具有足够的命名空间范围权限 - 验证
EventListener资源是否已正确配置 - 查看
EventListenerPod 日志:kubectl logs -n tekton-triggers-demo -l eventlistener=hello-listener
- 检查默认的
-
Webhook 地址(status.addresses)为空
- 验证配置的导出规则是否与
EventListener的命名空间匹配 - 检查自动暴露控制器是否正在运行:
kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller - 查看控制器日志,确认是否存在匹配或配置错误
- 确保
namespaceSelector.matchNames中的命名空间与EventListener命名空间匹配
- 验证配置的导出规则是否与
-
Trigger 未响应
- 验证 Webhook URL 是否可访问(检查
status.addresses) - 检查请求格式是否正确
- 查看
EventListenerPod 日志:kubectl logs -n tekton-triggers-demo -l eventlistener=hello-listener - 验证共享的
Ingress是否已正确配置(该资源会在 Tekton 系统命名空间中创建,并以导出规则命名,而不是按 EventListener 分别创建):kubectl get ingress -n tekton-pipelines
- 验证 Webhook URL 是否可访问(检查
-
未创建 TaskRun
- 确认
TriggerTemplate配置是否正确 - 检查
TriggerBinding中的参数映射 - 查看
EventListenerPod 的错误日志
- 确认