快速开始
本指南将通过创建一个简单的 “Hello World” trigger 场景帮助你快速上手 Tekton Triggers,以演示其基本功能。本指南按以下步骤进行:
- 配置
EventListener自动暴露规则,将EventListeners暴露到外部 - 创建
EventListener及相关资源 - 从
EventListener状态中获取自动生成的 webhook 地址
目录
前提条件步骤 1:配置 EventListener 自动暴露规则前提条件步骤 2:创建示例项目步骤 3:创建 Hello World TaskRun替代方案:简单测试设置选项 A:使用 Port-Forward(最简单)选项 B:使用 NodePort步骤 4:获取 Webhook 地址并测试(使用自动暴露)后续步骤常见问题前提条件
-
环境要求
Kubernetes版本 1.21 或更高- 已安装
Tekton Operator - 确保通过 Operator 已安装并就绪的
Tekton Triggers
-
所需工具
kubectl命令行工具curl(用于测试 trigger)
-
权限
- 需要 集群管理员权限(用于配置
EventListener自动暴露规则) - 需要 命名空间管理员权限(用于创建
EventListener资源)
- 需要 集群管理员权限(用于配置
步骤 1:配置 EventListener 自动暴露规则
关于自动暴露功能
这是一个 Alauda 平台增强功能(不属于标准 Tekton Triggers),用于简化 EventListener 的外部访问配置。
暴露 EventListener 的三种方式:
-
自动暴露(Alauda 增强) ⭐ 推荐用于生产环境
- 自动创建并管理
Ingress资源 - 通过
TektonConfig进行集中配置 - webhook URL 会自动填充到
EventListener状态中 - 最适合拥有多个
EventListener的生产环境
- 自动创建并管理
-
手动 Ingress(标准 Tekton 方式)
- 你需要为每个
EventListener手动创建Ingress资源 - 控制更灵活,但维护成本更高
- 标准 Kubernetes 方式
- 你需要为每个
-
Port-Forward 或 NodePort(测试/开发) 🚀 最容易上手
- 无需
Ingress或 DNS 配置 - 非常适合本地测试和学习
- 如果你想快速开始,请参阅 跳转到简单测试设置
- 无需
如果你是第一次使用 Triggers,可以跳过此步骤,直接前往 简单测试设置 章节,通过 port-forward 开始使用。等你准备好进行生产部署时,再回来配置自动暴露。
EventListener 自动暴露功能会根据你配置的导出规则自动为你的 EventListeners 创建 Ingress 资源。这消除了手动创建和管理 Ingress 资源的需要。你需要先配置这些规则,这样 EventListeners 才能通过外部 URL 访问。有关详细配置说明,请参阅 配置 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资源 - 使用可在 UI 中展示的 webhook URL 填充
EventListener的status.addresses字段 - 无需再为每个
EventListener手动创建和管理Ingress资源
这种方式提供了一种集中式的管理机制,用于控制 EventListeners 的暴露方式,从而更容易在整个集群中维护一致的 webhook URL 模式。
选择 Ingress 配置方式
自动暴露功能支持两种配置 Ingress 以将 EventListeners 暴露到外部的方式。请选择最适合你环境的方法:
替代方案: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)业务集群,可以利用平台内置网关快速完成配置:
- 获取你的 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 Path Prefix:
/triggers(可配置) - External Host:
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 和 external host URL。如果你没有配置域名,可以将 host 字段留空,并使用实际可访问的 URL 配置 externalHosts。
应用 TektonConfig
验证配置
等待几分钟让 Operator 同步配置,然后进行验证:
ConfigMap 中应包含你的导出规则配置。(注意:ConfigMap 名称 trigger-wrapper-config 是内部技术名称;你无需记住它,因为你是通过 TektonConfig 来管理配置的。)
步骤 2:创建示例项目
创建命名空间
关于 EventListener 的 ServiceAccount
在本快速开始中,我们将使用 默认 ServiceAccount,它由 Tekton Triggers 系统 自动创建。这个 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:
- 如果你需要在多个命名空间中创建资源(跨命名空间 triggers)
- 如果你需要默认范围之外的额外权限
- 有关自定义
ServiceAccount的配置,请参阅 Setup EventListener
步骤 3:创建 Hello World TaskRun
创建 Task
创建文件 hello-task.yaml:
创建 Trigger Template
创建文件 trigger-template.yaml:
创建 Trigger Binding
创建文件 trigger-binding.yaml:
创建 Event Listener
创建文件 event-listener.yaml:
ServiceAccount 说明:我们使用的是 自动创建 的默认 ServiceAccount(通过将 serviceAccountName 设置为 triggers-default-sa)。该 ServiceAccount 由 Tekton Triggers 系统创建,并拥有在同一命名空间内创建 TaskRuns/PipelineRuns 的权限。由于本示例中的所有资源都位于同一命名空间,这已经足够。自动暴露功能会根据第 1 步中配置的导出规则自动为该 EventListener 创建一个 Ingress。
应用配置
应用所有已创建的资源:
替代方案:简单测试设置
如果你跳过了第 1 步(自动暴露配置)并且想快速测试,可以使用 port-forward 或 NodePort 来访问 EventListener,无需任何 Ingress 或 DNS 设置。
选项 A:使用 Port-Forward(最简单)
等待 EventListener 就绪
将本地端口转发到 EventListener
保持这个终端窗口打开。现在可以通过 http://localhost:8080 访问 EventListener。
通过 Port-Forward 发送测试请求
打开一个新的终端并运行:
查看结果
选项 B:使用 NodePort
用于在没有 Ingress 的情况下,从本地机器外部访问 EventListener:
将 EventListener Service 补丁为 NodePort
获取 NodePort
通过 NodePort 发送测试请求
何时使用各个方式:
- Port-forward:本地测试、开发、学习
- 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
网络访问:请确保你测试时所使用的外部 host URL 是可访问的。如果你在集群内部进行测试,可能需要使用 port-forward 或直接访问内部 service 地址。
验证 Webhook 域名可访问性
在发送测试请求之前,请先验证 webhook 域名是否可访问:
重要:请确保基于 LoadBalancer/Gateway 配置的 webhook 域名可被外部系统访问。如果你正在在 GitHub、GitLab 或其他外部系统中配置 webhook,它们必须能够访问该 URL。请检查:
- DNS 记录是否已正确配置
- LoadBalancer/Gateway 是否已正确配置并可访问
- 防火墙规则是否允许入站流量
- TLS 证书是否有效(如果使用 HTTPS)
向 Webhook 发送测试请求
查看结果
清理资源
测试完成后,你可以删除已创建的资源:
后续步骤
现在你已经成功创建并测试了一个基本的 Tekton Triggers 示例,可以继续:
- 学习 Tekton Triggers 的概念
- 了解如何使用 Setup EventListeners 进行常见的设置说明
- 配置 EventListener 自动暴露规则 以应对更高级的暴露场景
- 配置并使用 Gitlab events 来触发 pipelines
常见问题
-
EventListener Pod 启动失败
- 检查默认
ServiceAccount是否具有足够的命名空间范围权限 - 验证
EventListener资源是否配置正确 - 查看
EventListenerPod 日志:kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
- 检查默认
-
Webhook 地址(status.addresses)为空
- 验证你配置的导出规则是否与
EventListener的命名空间匹配 - 检查自动暴露 controller 是否正在运行:
kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller - 查看 controller 日志,确认是否存在匹配或配置错误
- 确保
namespaceSelector.matchNames中的命名空间与EventListener命名空间一致
- 验证你配置的导出规则是否与
-
Trigger 没有响应
- 验证 webhook URL 是否可访问(检查
status.addresses) - 检查请求格式是否正确
- 查看
EventListenerPod 日志:kubectl logs -n tekton-triggers-demo -l app=el-hello-listener - 验证
Ingress是否配置正确:kubectl get ingress -n tekton-triggers-demo
- 验证 webhook URL 是否可访问(检查
-
未创建 TaskRun
- 确认
TriggerTemplate配置是否正确 - 检查
TriggerBinding中的参数映射 - 查看
EventListenerPod 的错误日志
- 确认