快速开始

本指南将通过创建一个简单的“Hello World”触发场景，帮助你开始使用 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
- 确保 Tekton Triggers 已通过 Operator 安装并处于就绪状态
所需工具
- kubectl 命令行工具
- curl（用于测试触发器）
权限
- 需要 集群管理员权限（用于配置 EventListener 自动暴露规则）
- 需要 命名空间管理员权限（用于创建 EventListener 资源）

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

INFO

关于自动暴露功能

这是一个 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 快速开始。等你准备好进行生产部署时，再回来配置自动暴露。

TIP

EventListener 自动暴露功能会根据你配置的暴露规则，自动为你的 EventListeners 创建 Ingress 资源。这样就不需要手动创建和管理 Ingress 资源了。你需要先配置这些规则，才能通过外部 URL 访问 EventListeners。详细配置说明请参见配置 EventListener 自动暴露规则。

前提条件

在配置暴露规则之前，请确保已具备以下条件：

LoadBalancer 或 Gateway 配置（推荐用于生产环境）：
- 对于生产环境，建议使用 LoadBalancer 或 Gateway 来暴露 EventListeners
- LoadBalancer/Gateway 应已配置并可访问
- 你应已具备用于 webhook 的外部域名或 IP 地址
Ingress Controller（如果使用 Ingress）：
- 集群中应已安装并运行 Ingress controller（例如 NGINX、ALB 或 Traefik）
- 你应知道将要使用的 IngressClass 名称
- 有关创建 Ingress 的更多信息，请参见创建 Ingress。
域名和证书（用于 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 中配置的暴露规则
自动为符合规则的 EventListeners 创建 Ingress 资源
将 webhook URL 填充到 EventListener 的 status.addresses 字段中，便于在 UI 中展示
无需再为每个 EventListener 手动创建和管理 Ingress 资源

这种方式提供了一种集中式的管理方式，用于控制 EventListeners 的暴露方式，使你更容易在整个集群中维护一致的 webhook URL 模式。

选择 Ingress 配置方式

自动暴露功能支持两种配置 Ingress 以将 EventListeners 暴露到外部的方式。请选择最适合你环境的方式：

INFO

替代方案：NodePort 配置

如果你没有 LoadBalancer 或 Ingress controller，或者希望在开发/测试中使用更简单的设置，也可以改用 NodePort。详情请参见NodePort 配置示例。使用 NodePort 时不需要自动暴露功能，因为你将通过节点 IP 和 NodePort 直接访问 EventListener。

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

此方式适用于大多数 Kubernetes 环境。你需要：

创建 IngressClass（如果尚不存在）：更多信息请参见创建 Ingress。
或者使用 LoadBalancer Service 获取外部 IP 地址更多信息请参见配置 Load Balancer。
根据你的 Ingress 设置配置暴露规则：
- 如果使用 IngressClass：将 ingressClass 设置为你的 IngressClass 名称（例如 nginx）
- 如果使用 LoadBalancer：从 LoadBalancer service 获取外部 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 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 的示例配置：

export-rules:
  - name: demo-webhooks
    host: ""  # 为空，或使用通配符 "*"
    ingressClass: nginx  # 使用默认 ingress class
    urlPathPrefix: /triggers
    externalHosts:
      - "https://192.168.1.100/clusters-rewrite/test"  # ACP 平台 URL + /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 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。

WARNING

重要：请将占位值（webhooks.example.com、nginx 等）替换为你的实际域名、ingress class 和 external host 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 系统 自动创建。这个 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：

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 在同一命名空间内的 triggers 中生效
  # $ 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 说明：我们使用的是 自动创建 的默认 ServiceAccount（通过将 serviceAccountName 设置为 triggers-default-sa）。这个 ServiceAccount 由 Tekton Triggers 系统创建，并具有在同一命名空间内创建 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 步（自动暴露配置）并希望快速测试，可以使用 port-forward 或 NodePort 在无需 Ingress 或 DNS 配置的情况下访问 EventListener。

选项 A：使用 Port-Forward（最简单）

等待 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

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

通过 Port-Forward 发送测试请求

打开一个新的终端并运行：

$ 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 Service 修补为 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 accessible at: http://$NODE_IP:$NODE_PORT"
EventListener accessible at: 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

何时使用哪种方式：

Port-forward：本地测试、开发、学习
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 字段中：

# 从 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

网络访问：请确保你用于测试的外部 host URL 可以被访问。如果你是在集群内测试，可能需要改用 port-forward 或访问内部 service 地址。

验证 Webhook 域名可访问性

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

# 测试 webhook URL 是否可访问
# 将 URL 替换为你从 status.addresses 获取的实际 webhook 地址
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 events 来触发 pipeline

常见问题

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 命名空间一致
Trigger 没有响应
- 验证 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 配置方式

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

#方式 2：ACP 商业集群快速开始

#应用 TektonConfig

#验证配置

#步骤 2：创建示例项目

#创建命名空间

#步骤 3：创建 Hello World TaskRun

#创建 Task

#创建 Trigger Template

#创建 Trigger Binding

#创建 Event Listener

#应用配置

#替代方案：简单测试设置

#选项 A：使用 Port-Forward（最简单）

#等待 EventListener 就绪

#将本地端口转发到 EventListener

#通过 Port-Forward 发送测试请求

#查看结果

#选项 B：使用 NodePort

#将 EventListener Service 修补为 NodePort

#获取 NodePort

#通过 NodePort 发送测试请求

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

#等待 EventListener 就绪

#获取自动生成的 Webhook 地址

#验证 Webhook 域名可访问性

#向 Webhook 发送测试请求

#查看结果

#清理资源

#下一步

#常见问题

快速开始

目录

前提条件

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

前提条件

通过 TektonConfig 配置暴露规则

了解自动暴露

选择 Ingress 配置方式

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

方式 2：ACP 商业集群快速开始

应用 TektonConfig

验证配置

步骤 2：创建示例项目

创建命名空间

步骤 3：创建 Hello World TaskRun

创建 Task

创建 Trigger Template

创建 Trigger Binding

创建 Event Listener

应用配置

替代方案：简单测试设置

选项 A：使用 Port-Forward（最简单）

等待 EventListener 就绪

将本地端口转发到 EventListener

通过 Port-Forward 发送测试请求

查看结果

选项 B：使用 NodePort

将 EventListener Service 修补为 NodePort

获取 NodePort

通过 NodePort 发送测试请求

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

等待 EventListener 就绪

获取自动生成的 Webhook 地址

验证 Webhook 域名可访问性

向 Webhook 发送测试请求

查看结果

清理资源

下一步

常见问题