快速开始

本指南将帮助您通过创建一个简单的“Hello World”触发器场景来快速上手 Tekton Triggers，演示其基本功能。指南步骤如下：

配置自动 EventListener 暴露规则，实现 EventListener 的外部暴露
创建 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 暴露规则

INFO

关于自动暴露功能

这是 Alauda 平台增强功能（非标准 Tekton Triggers 功能），简化了 EventListener 的外部访问配置。

暴露 EventListener 的三种方式：

自动暴露（Alauda 增强） ⭐ 推荐用于生产环境
- 自动创建和管理 Ingress 资源
- 通过 TektonConfig 集中配置
- webhook URL 自动填充到 EventListener 状态中
- 适合生产环境中多个 EventListener 的统一管理
手动 Ingress（标准 Tekton 方式）
- 需要手动为每个 EventListener 创建 Ingress 资源
- 控制更细粒度，但维护成本较高
- 标准 Kubernetes 方式
端口转发或 NodePort（测试/开发） 🚀 最简单快速上手
- 无需配置 Ingress 或 DNS
- 适合本地测试和学习
- 若想快速开始，请参见跳转到简单测试配置

如果您是 Triggers 新手，可以跳过此步骤，直接进入简单测试配置使用端口转发快速开始，后续准备好生产部署时再回来配置自动暴露。

TIP

EventListener 自动暴露功能会根据您配置的导出规则自动创建 Ingress 资源，无需手动创建和管理 Ingress。您需要先配置这些规则，才能通过外部 URL 访问 EventListener。详细配置请参考配置 EventListener 自动暴露规则。

前提条件

在配置导出规则前，请确保具备以下条件：

LoadBalancer 或 Gateway 配置（推荐用于生产）：
- 生产环境建议使用 LoadBalancer 或 Gateway 来暴露 EventListener
- LoadBalancer/Gateway 应已配置并可访问
- 您应拥有用于 webhook 的外部域名或 IP 地址
Ingress 控制器（如果使用 Ingress）：
- 集群中应安装并运行 Ingress 控制器（如 NGINX、ALB 或 Traefik）
- 您应知道将使用的 IngressClass 名称
- 关于创建 Ingress 的更多信息，请参见 Creating Ingresses。
域名和证书（用于 HTTPS）：
- 使用 HTTPS 时，请确保已配置域名
- 准备好 TLS 证书（手动创建或通过 cert-manager）

INFO

重要说明：

自动暴露功能会根据导出规则自动创建 Ingress 资源，通常无需手动创建或修改 Ingress。
如果使用带自定义端口的 LoadBalancer，请确保在 externalHosts 字段中包含端口（例如 https://webhooks.example.com:8443）。
开发或测试环境也可以使用 NodePort 替代 Ingress/LoadBalancer，详情请参见NodePort 配置示例。

通过 TektonConfig 配置导出规则

创建或更新 TektonConfig 资源，配置导出规则。创建文件 tektonconfig.yaml：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      configMaps:
        trigger-wrapper-config:
          data:
            config: |
              export-rules:
                - name: demo-webhooks
                  host: webhooks.example.com  # 替换为您的域名，确保 DNS 解析配置正确（测试时可添加到 /etc/hosts）
                  ingressClass: nginx  # 替换为您的 ingress class
                  urlPathPrefix: /triggers
                  externalHosts:
                    - "https://webhooks.example.com"  # 替换为您的外部 URL（用户将复制此地址到 GitHub/GitLab webhook 设置）
                  namespaceSelector:
                    matchNames:
                      - "tekton-triggers-demo"  # 匹配您的演示命名空间

理解自动暴露机制

自动暴露功能的工作原理：

读取您在 TektonConfig 中配置的导出规则
自动为匹配规则的 EventListener 创建 Ingress 资源
将 webhook URL 填充到 EventListener 的 status.addresses 字段，方便 UI 展示
无需为每个 EventListener 手动创建和管理 Ingress

这种方式提供了集中管理 EventListener 暴露方式的能力，方便维护集群中 webhook URL 的统一规范。

选择 Ingress 配置方式

自动暴露功能支持两种方式配置 Ingress 以实现外部访问。请选择适合您环境的方式：

INFO

备选方案：NodePort 配置

如果没有 LoadBalancer 或 Ingress 控制器，或者想要更简单的开发/测试环境配置，可以使用 NodePort。详情请参见NodePort 配置示例。使用 NodePort 时无需自动暴露功能，您可以直接通过节点 IP 和 NodePort 访问 EventListener。

方式一：通用 Ingress 配置（推荐生产环境）

适用于大多数 Kubernetes 环境。您需要：

创建 IngressClass（如果尚未创建）：详情请参见 Creating Ingresses。
或使用 LoadBalancer Service 获取外部 IP 地址详情请参见 Configure a Load Balancer。
根据 Ingress 配置导出规则：
- 使用 IngressClass 时：将 ingressClass 设置为您的 IngressClass 名称（如 nginx）
- 使用 LoadBalancer 时：从 LoadBalancer 服务获取外部 IP/域名，配置 host 和 externalHosts

IngressClass 示例配置：

export-rules:
  - name: demo-webhooks
    host: webhooks.example.com  # 您的域名，确保 DNS 解析配置正确（测试时可添加到 /etc/hosts）
    ingressClass: nginx  # 您的 IngressClass 名称
    urlPathPrefix: /triggers
    externalHosts:
      - "https://webhooks.example.com"  # 外部可访问的 URL

WARNING

DNS 配置：配置 host 字段为域名时，请确保：

DNS 记录正确解析到您的 Ingress 控制器 IP
本地测试时可将域名添加到 /etc/hosts（Linux/Mac）或 C:\Windows\System32\drivers\etc\hosts（Windows）
域名必须能被发送 webhook 的系统（如 GitHub、GitLab）解析

方式二：ACP 业务集群快速配置

如果您使用 ACP（Alauda Container Platform）业务集群，可利用平台内置网关快速配置：

获取 ACP 平台访问地址（如 https://192.168.1.100）
获取集群名称（如 test）
配置导出规则：
- host 设为空（或使用通配符 *）
- externalHosts 设为：<ACP 平台访问地址>/clusters-rewrite/<集群名称>
- 最终 webhook URL 格式为：<externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>

ACP 示例配置：

export-rules:
  - name: demo-webhooks
    host: ""  # 为空或使用通配符 "*"
    ingressClass: nginx  # 使用默认 ingress class
    urlPathPrefix: /triggers
    externalHosts:
      - "https://192.168.1.100/clusters-rewrite/test"  # ACP 平台地址 + /clusters-rewrite/<cluster-name>。最终 webhook 示例：https://192.168.1.100/clusters-rewrite/test/triggers/tekton-triggers-demo/hello-listener
    namespaceSelector:
      matchNames:
        - "tekton-triggers-demo"

该配置下，webhook 地址为：

https://192.168.1.100/clusters-rewrite/test/triggers/tekton-triggers-demo/hello-listener

TIP

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。

WARNING

重要：请将示例中的占位符（如 webhooks.example.com、nginx 等）替换为您实际的域名、ingress class 和外部主机 URL。如果没有配置域名，可以将 host 设为空，并在 externalHosts 中配置实际可访问的 URL。

应用 TektonConfig

$ kubectl apply -f tektonconfig.yaml
tektonconfig.operator.tekton.dev/config created

验证配置

等待 Operator 同步配置后，验证：

$ kubectl get configmap trigger-wrapper-config -n tekton-pipelines -o yaml
apiVersion: v1
data:
  config: |
    export-rules:
      - name: demo-webhooks
        host: webhooks.example.com
        ...
kind: ConfigMap
metadata:
  name: trigger-wrapper-config
  namespace: tekton-pipelines

ConfigMap 中应包含您的导出规则配置。（注意：ConfigMap 名称 trigger-wrapper-config 是内部技术名称，无需记忆，配置通过 TektonConfig 管理即可。）

第 2 步：创建示例项目

创建命名空间

$ kubectl create namespace tekton-triggers-demo
namespace/tekton-triggers-demo created

TIP

关于 EventListener 的 ServiceAccount

本快速开始示例使用的是 默认的 ServiceAccount，该账户由 Tekton Triggers 系统 自动创建，名称为 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 的场景：

需要跨多个命名空间创建资源（跨命名空间触发器）
需要超出默认权限范围的额外权限
详情请参见设置 EventListener中自定义 ServiceAccount 配置

第 3 步：创建 Hello World TaskRun

创建 Task

创建文件 hello-task.yaml：

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: hello-task
  namespace: tekton-triggers-demo
spec:
  params:
    - name: message
      description: Message to print
      type: string
      default: "Hello World!"
  steps:
    - name: echo
      image: alpine
      script: |
        echo "$(params.message)"

创建 Trigger Template

创建文件 trigger-template.yaml：

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: hello-template
  namespace: tekton-triggers-demo
spec:
  params:
    - name: message
      description: Message to print
      default: "Hello World!"
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: TaskRun
      metadata:
        generateName: hello-run-
        namespace: tekton-triggers-demo
      spec:
        taskRef:
          name: hello-task
        params:
          - name: message
            value: $(tt.params.message)

创建 Trigger Binding

创建文件 trigger-binding.yaml：

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: hello-binding
  namespace: tekton-triggers-demo
spec:
  params:
    - name: message
      value: $(body.message)

创建 Event Listener

创建文件 event-listener.yaml：

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: hello-listener
  namespace: tekton-triggers-demo
spec:
  # 运行以下命令获取同命名空间触发器可用的 ServiceAccount
  # $ kubectl get sa -n ${YOUR_NS} -l triggers.tekton.dev/default-service-account -o jsonpath='{.items[0].metadata.name}'
  serviceAccountName: triggers-default-sa  # 或设置为 <your service account> 使用自定义 ServiceAccount
  triggers:
    - name: hello-trigger
      bindings:
        - ref: hello-binding
      template:
        ref: hello-template

INFO

ServiceAccount 说明：本示例使用的是 Tekton Triggers 系统 自动创建的默认 ServiceAccount（通过设置 serviceAccountName 为 triggers-default-sa）。该账户拥有在同一命名空间内创建 TaskRuns/PipelineRuns 的权限。由于所有资源均在同一命名空间内，这已足够使用。自动暴露功能会基于第 1 步配置的导出规则自动为该 EventListener 创建 Ingress。

应用配置

应用所有创建的资源：

$ kubectl apply -f hello-task.yaml
task.tekton.dev/hello-task created

$ kubectl apply -f trigger-template.yaml
triggertemplate.triggers.tekton.dev/hello-template created

$ kubectl apply -f trigger-binding.yaml
triggerbinding.triggers.tekton.dev/hello-binding created

$ kubectl apply -f event-listener.yaml
eventlistener.triggers.tekton.dev/hello-listener created

备选方案：简单测试配置

如果跳过了第 1 步（自动暴露配置），想快速测试，可以使用 端口转发 或 NodePort 方式访问 EventListener，无需配置 Ingress 或 DNS。

方案 A：使用端口转发（最简单）

等待 EventListener 就绪

$ kubectl wait --for=condition=Ready eventlistener/hello-listener -n tekton-triggers-demo --timeout=60s
eventlistener.triggers.tekton.dev/hello-listener condition met

本地端口转发到 EventListener

$ kubectl port-forward -n tekton-triggers-demo svc/el-hello-listener 8080:8080
Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080

保持该终端窗口打开。此时 EventListener 可通过 http://localhost:8080 访问。

通过端口转发发送测试请求

新开终端执行：

$ curl -v -H 'Content-Type: application/json' -d '{"message":"Hello, Tekton!"}' http://localhost:8080
* Connected to localhost (127.0.0.1) port 8080
> POST / HTTP/1.1
> Host: localhost:8080
...
< HTTP/1.1 201 Created
{"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}

查看结果

# 查看创建的 TaskRun
$ kubectl get taskrun -n tekton-triggers-demo
NAME              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
hello-run-xxxxx   True        Succeeded   1m          50s

# 查看 TaskRun 日志
$ kubectl logs -l triggers.tekton.dev/eventlistener=hello-listener -n tekton-triggers-demo
Hello, Tekton!

方案 B：使用 NodePort

适用于无需 Ingress，从集群外部机器访问 EventListener 的场景：

将 EventListener 服务修改为 NodePort 类型

$ kubectl patch svc el-hello-listener -n tekton-triggers-demo -p '{"spec":{"type":"NodePort"}}'
service/el-hello-listener patched

获取 NodePort 端口号

$ export NODE_PORT=$(kubectl get svc el-hello-listener -n tekton-triggers-demo -o jsonpath='{.spec.ports[0].nodePort}')
$ export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="ExternalIP")].address}')

# 如果 NODE_IP 为空，使用 InternalIP
$ if [ -z "$NODE_IP" ]; then
  export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
fi

$ echo "EventListener 可通过以下地址访问：http://$NODE_IP:$NODE_PORT"
EventListener 可通过以下地址访问：http://192.168.1.100:32567

通过 NodePort 发送测试请求

$ curl -v -H 'Content-Type: application/json' -d '{"message":"Hello, Tekton!"}' http://$NODE_IP:$NODE_PORT
* Connected to 192.168.1.100 (192.168.1.100) port 32567
> POST / HTTP/1.1
...
< HTTP/1.1 201 Created
{"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}

TIP

各方法适用场景：

端口转发：本地测试、开发、学习
NodePort：从其他机器测试、开发集群
自动暴露（Ingress）：生产部署、外部 webhook（GitHub、GitLab 等）

第 4 步：获取 webhook 地址并测试（使用自动暴露）

等待 EventListener 就绪

# 等待 Pod 就绪
$ kubectl get pods -n tekton-triggers-demo
NAME                                 READY   STATUS    RESTARTS   AGE
el-hello-listener-xxxxxxxxxx-xxxxx   1/1     Running   0          30s

# 等待 EventListener 就绪
$ kubectl wait --for=condition=Ready eventlistener/hello-listener -n tekton-triggers-demo --timeout=60s
eventlistener.triggers.tekton.dev/hello-listener condition met

获取自动生成的 webhook 地址

自动暴露功能会根据第 1 步配置的导出规则自动生成外部 webhook 地址，填充在 EventListener 的 status.addresses 字段：

# 获取第一个 webhook 地址
$ export EL_URL=$(kubectl get el hello-listener -n tekton-triggers-demo -o jsonpath='{.status.addresses[0].url}')

# 或查看所有可用地址
$ kubectl get el hello-listener -n tekton-triggers-demo -o jsonpath='{.status.addresses[*].url}' | tr ' ' '\n'
https://webhooks.example.com/triggers/tekton-triggers-demo/hello-listener
https://backup.webhooks.example.com/triggers/tekton-triggers-demo/hello-listener

TIP

地址格式：webhook 地址遵循模式：<externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>

例如：https://webhooks.example.com/triggers/tekton-triggers-demo/hello-listener

如果 status.addresses 为空，请检查：

您配置的导出规则是否匹配 EventListener 所在命名空间
自动暴露控制器是否运行并已处理该 EventListener
查看控制器日志：kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller

WARNING

网络访问：确保您的外部主机 URL 可从测试位置访问。如果在集群内测试，可能需要使用端口转发或访问内部服务地址。

验证 webhook 域名可访问性

发送测试请求前，先验证 webhook 域名是否可访问：

# 测试 webhook URL 是否可访问
# 将 URL 替换为您从 status.addresses 获取的实际地址
curl -I $EL_URL

# 或使用简单的 GET 请求测试（部分 webhook 端点可能不支持 GET，但可用于验证连通性）
curl -v $EL_URL

WARNING

重要：确保基于 LoadBalancer/Gateway 的 webhook 域名可被外部系统访问。如果您在 GitHub、GitLab 等外部系统配置 webhook，必须能访问该 URL。请检查：

DNS 记录配置正确
LoadBalancer/Gateway 配置正确且可访问
防火墙规则允许入站流量
TLS 证书有效（使用 HTTPS 时）

向 webhook 发送测试请求

$ curl -v -H 'Content-Type: application/json' -d '{"message":"Hello, Tekton!"}' $EL_URL
* Connected to webhooks.example.com (xx.xx.xx.xx) port 443
> POST /triggers/tekton-triggers-demo/hello-listener HTTP/1.1
> Host: webhooks.example.com
...
< HTTP/1.1 201 Created
{"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}

查看结果

# 查看创建的 TaskRun
$ kubectl get taskrun -n tekton-triggers-demo
NAME              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
hello-run-xxxxx   True        Succeeded   1m          50s

# 查看特定 TaskRun 的日志
$ kubectl logs -l eventlistener=hello-listener -n tekton-triggers-demo
Hello, Tekton!

清理资源

测试完成后，您可以删除创建的资源：

$ kubectl delete namespace tekton-triggers-demo
namespace "tekton-triggers-demo" deleted

后续步骤

您已成功创建并测试了一个基础的 Tekton Triggers 示例，接下来可以：

探索 Tekton Triggers 概念
学习如何使用设置 EventListeners 进行常见配置
配置 EventListener 自动暴露规则以实现高级暴露场景
设置并使用 Gitlab 事件触发流水线

常见问题

EventListener Pod 启动失败
- 检查默认 ServiceAccount 是否具备足够的命名空间权限
- 确认 EventListener 资源配置正确
- 查看 EventListener Pod 日志：kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
Webhook 地址（status.addresses）为空
- 确认您配置的导出规则是否匹配 EventListener 所在命名空间
- 检查自动暴露控制器是否运行：kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller
- 查看控制器日志，排查匹配或配置错误
- 确认 namespaceSelector.matchNames 中的命名空间与 EventListener 命名空间一致
触发器无响应
- 确认 webhook URL 可访问（检查 status.addresses）
- 检查请求格式是否正确
- 查看 EventListener Pod 日志：kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
- 确认 Ingress 配置正确：kubectl get ingress -n tekton-triggers-demo
TaskRun 未创建
- 确认 TriggerTemplate 配置正确
- 检查 TriggerBinding 中的参数映射
- 查看 EventListener Pod 的错误日志

#快速开始

#目录

#前提条件

#第 1 步：配置自动 EventListener 暴露规则

#前提条件

#通过 TektonConfig 配置导出规则

#理解自动暴露机制

#选择 Ingress 配置方式

#方式一：通用 Ingress 配置（推荐生产环境）

#方式二：ACP 业务集群快速配置

#应用 TektonConfig

#验证配置

#第 2 步：创建示例项目

#创建命名空间

#第 3 步：创建 Hello World TaskRun

#创建 Task

#创建 Trigger Template

#创建 Trigger Binding

#创建 Event Listener

#应用配置

#备选方案：简单测试配置

#方案 A：使用端口转发（最简单）

#等待 EventListener 就绪

#本地端口转发到 EventListener

#通过端口转发发送测试请求

#查看结果

#方案 B：使用 NodePort

#将 EventListener 服务修改为 NodePort 类型

#获取 NodePort 端口号

#通过 NodePort 发送测试请求

#第 4 步：获取 webhook 地址并测试（使用自动暴露）

#等待 EventListener 就绪

#获取自动生成的 webhook 地址

#验证 webhook 域名可访问性

#向 webhook 发送测试请求

#查看结果

#清理资源

#后续步骤

#常见问题

快速开始

目录

前提条件

第 1 步：配置自动 EventListener 暴露规则

前提条件

通过 TektonConfig 配置导出规则

理解自动暴露机制

选择 Ingress 配置方式

方式一：通用 Ingress 配置（推荐生产环境）

方式二：ACP 业务集群快速配置

应用 TektonConfig

验证配置

第 2 步：创建示例项目

创建命名空间

第 3 步：创建 Hello World TaskRun

创建 Task

创建 Trigger Template

创建 Trigger Binding

创建 Event Listener

应用配置

备选方案：简单测试配置

方案 A：使用端口转发（最简单）

等待 EventListener 就绪

本地端口转发到 EventListener

通过端口转发发送测试请求

查看结果

方案 B：使用 NodePort

将 EventListener 服务修改为 NodePort 类型

获取 NodePort 端口号

通过 NodePort 发送测试请求

第 4 步：获取 webhook 地址并测试（使用自动暴露）

等待 EventListener 就绪

获取自动生成的 webhook 地址

验证 webhook 域名可访问性

向 webhook 发送测试请求

查看结果

清理资源

后续步骤

常见问题