快速开始

本指南将通过创建一个简单的“Hello World”触发器场景,帮助你开始使用 Tekton Triggers,并演示其基本功能。本指南包含以下步骤:

  1. 配置自动 EventListener 暴露规则,以便将 EventListeners 暴露到外部
  2. 创建 EventListener 及相关资源
  3. 从 EventListener 状态中获取自动生成的 webhook 地址

前提条件

  1. 环境要求

    • Kubernetes 版本 1.21 或更高
    • 已安装 Tekton Operator
    • 确保已通过 Operator 安装并准备好 Tekton Triggers
  2. 所需工具

    • kubectl 命令行工具
    • curl(用于测试触发器)
  3. 权限

    • 需要集群管理员权限(用于配置 EventListener 自动暴露规则)
    • 需要命名空间管理员权限(用于创建 EventListener 资源)

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

INFO

关于自动暴露功能

这是 Alauda 平台增强功能(不是标准 Tekton Triggers 的一部分),用于简化 EventListener 外部访问配置。

暴露 EventListener 的三种方式:

  1. 自动暴露(Alauda 增强功能) ⭐ 推荐用于生产环境

    • 自动创建和管理 Ingress 资源
    • 通过 TektonConfig 进行集中式配置
    • webhook URL 自动填充到 EventListener 状态中
    • 最适合包含多个 EventListeners 的生产环境
  2. 手动 Ingress(标准 Tekton 方法)

    • 为每个 EventListener 手动创建 Ingress 资源
    • 控制力更强,但需要更多维护工作
    • 标准 Kubernetes 方法
  3. Port-Forward 或 NodePort(测试/开发) 🚀 最容易上手

如果你刚开始使用 Triggers,可以跳过此步骤,直接跳转到简单测试设置部分,通过 port-forward 开始。准备好进行生产部署后,再回来配置自动暴露。

TIP

EventListener 自动暴露功能会根据你配置的导出规则,为符合条件的 EventListeners 自动创建 Ingress 资源。这样无需手动创建和管理 Ingress 资源。你需要先配置这些规则,以便通过外部 URL 访问 EventListeners。有关详细配置说明,请参阅配置 EventListener 自动暴露规则。

前提条件

在配置导出规则之前,请确保已满足以下前提条件:

  1. LoadBalancer 或 Gateway 配置(推荐用于生产环境):

    • 对于生产环境,建议使用 LoadBalancer 或 Gateway 来暴露 EventListeners
    • 应配置并确保可访问 LoadBalancer/Gateway
    • 你应拥有将用于 webhook 的外部域名或 IP 地址
  2. Ingress Controller(如果使用 Ingress):

    • 集群中应已安装并运行 Ingress controller(例如 NGINX、ALB 或 Traefik)
    • 你应知道将使用的 IngressClass 名称
    • 有关创建 Ingress 的更多信息,请参阅 创建 Ingress。
  3. 域名和证书(用于 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  # Replace with your domain. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
                  ingressClass: nginx  # Replace with your ingress class
                  urlPathPrefix: /triggers
                  externalHosts:
                    - "https://webhooks.example.com"  # Replace with your external URL (this is what users will copy to GitHub/GitLab webhook settings)
                  namespaceSelector:
                    matchNames:
                      - "tekton-triggers-demo"  # Match your demo namespace

了解自动暴露

自动暴露功能的工作方式如下:

  1. 读取你在 TektonConfig 中配置的导出规则
  2. 自动为符合规则的 EventListeners 创建 Ingress 资源
  3. 将 webhook URL 填充到 EventListener 的 status.addresses 字段中,以便在 UI 中显示
  4. 无需为每个 EventListener 手动创建和管理 Ingress 资源

这种方法提供了集中管理 EventListeners 暴露方式的途径,更易于在集群中维护一致的 webhook URL 模式。

选择 Ingress 配置方法

自动暴露功能支持两种配置 Ingress 以从外部暴露 EventListener 的方法。请选择最适合你环境的方法:

INFO

替代方案:NodePort 配置

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

方法 1:通用 Ingress 配置(推荐用于生产环境)

此方法适用于大多数 Kubernetes 环境。你需要:

  1. 创建 IngressClass(如果尚未创建): 有关更多信息,请参阅 创建 Ingress。

  2. 或者使用 LoadBalancer Service 获取外部 IP 地址 有关更多信息,请参阅 配置负载均衡器。

  3. 根据 Ingress 设置配置导出规则:

    • 如果使用 IngressClass:将 ingressClass 设置为你的 IngressClass 名称(例如 nginx)
    • 如果使用 LoadBalancer:从 LoadBalancer service 获取外部 IP/域名,并相应配置 host 和 externalHosts

IngressClass 配置示例:

export-rules:
  - name: demo-webhooks
    host: webhooks.example.com  # Your domain name. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    ingressClass: nginx  # Your IngressClass name
    urlPathPrefix: /triggers
    externalHosts:
      - "https://webhooks.example.com"  # External accessible 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)业务集群,可以利用平台内置的 gateway 快速完成设置:

  1. 获取 ACP 平台访问地址(例如 https://192.168.1.100)
  2. 获取集群名称(例如 test)
  3. 按如下方式配置导出规则:
    • 将 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: ""  # Empty or use wildcard "*"
    ingressClass: nginx  # Use default ingress class
    urlPathPrefix: /triggers
    externalHosts:
      - "https://192.168.1.100/clusters-rewrite/test"  # ACP Platform URL + /clusters-rewrite/<cluster-name>. Final 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

在此快速开始中,我们将使用由 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:

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  # In air-gapped environments, replace with an image from your internal registry
      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)

创建 EventListener

创建文件 event-listener.yaml:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: hello-listener
  namespace: tekton-triggers-demo
spec:
  # Run the following order to get ServiceAccount works for triggers within the same namespace
  # $ kubectl get sa -n ${YOUR_NS} -l triggers.tekton.dev/default-service-account -o jsonpath='{.items[0].metadata.name}'
  serviceAccountName: triggers-default-sa  # Or set to <your service account> to use a custom 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(自动暴露配置)并希望快速进行测试,可以使用 端口转发 或 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

保持此终端处于打开状态。现在可以通过 http://localhost:8080 访问 EventListener。

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

打开一个新终端并运行:

$ 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 202 Accepted
{"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}

查看结果

# View the created TaskRun
$ kubectl get taskrun -n tekton-triggers-demo
NAME              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
hello-run-xxxxx   True        Succeeded   1m          50s

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

选项 B:使用 NodePort

如果无需 Ingress,希望从本地计算机外部访问 EventListener:

将 EventListener Service 修补为 NodePort

Triggers controller 管理 el-hello-listener Service,并会还原对其进行的直接编辑,因此请改为在 EventListener 上设置 Service 类型:

$ kubectl patch eventlistener hello-listener -n tekton-triggers-demo --type merge -p '{"spec":{"resources":{"kubernetesResource":{"serviceType":"NodePort"}}}}'
eventlistener.triggers.tekton.dev/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}')

# If NODE_IP is empty, use 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 202 Accepted
{"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}
TIP

各方法的适用场景:

  • 端口转发:本地测试、开发、学习
  • NodePort:从其他计算机进行测试、开发集群
  • 自动暴露(Ingress):生产部署、外部 webhook(GitHub、GitLab 等)

步骤 4:获取 Webhook 地址并进行测试(使用自动暴露)

等待 EventListener 就绪

# Wait for the Pod to be ready
$ kubectl get pods -n tekton-triggers-demo
NAME                                 READY   STATUS    RESTARTS   AGE
el-hello-listener-xxxxxxxxxx-xxxxx   1/1     Running   0          30s

# Wait for EventListener to be ready
$ 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 字段中:

# Get the first webhook address from status.addresses
$ export EL_URL=$(kubectl get el hello-listener -n tekton-triggers-demo -o jsonpath='{.status.addresses[0].url}')

# Or view all available addresses
$ 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 的命名空间
  • 自动暴露 controller 是否正在运行并已处理 EventListener
  • 查看 controller 日志:kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller
WARNING

网络访问:确保外部主机 URL 可从您进行测试的位置访问。如果您在集群内进行测试,可能需要使用端口转发,或改为访问内部 Service 地址。

验证 Webhook 域名是否可访问

发送测试请求前,请验证您的 webhook 域名是否可访问:

# Test if the webhook URL is accessible
# Replace the URL with your actual webhook address from status.addresses
curl -I $EL_URL

# Or test with a simple GET request (some webhook endpoints may not support GET, but this helps verify connectivity)
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 202 Accepted
{"eventListener":"hello-listener","namespace":"tekton-triggers-demo","eventID":"..."}

查看结果

# View the created TaskRun
$ kubectl get taskrun -n tekton-triggers-demo
NAME              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
hello-run-xxxxx   True        Succeeded   1m          50s

# View logs of the specific TaskRun (replace hello-run-xxxxx with the name shown above)
$ kubectl logs -l tekton.dev/taskRun=hello-run-xxxxx -n tekton-triggers-demo
Hello, Tekton!

清理资源

测试完成后,可以删除已创建的资源:

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

下一步

现在,你已成功创建并测试了一个基本的 Tekton Triggers 示例,可以:

  1. 探索 Tekton Triggers 的相关概念
  2. 了解如何使用 设置 EventListener 获取常见的设置说明
  3. 配置 EventListener 自动暴露规则 以支持高级暴露场景
  4. 设置并使用 Gitlab 事件 来触发流水线

常见问题

  1. EventListener Pod 启动失败

    • 检查默认的 ServiceAccount 是否具有足够的命名空间范围权限
    • 验证 EventListener 资源是否已正确配置
    • 查看 EventListener Pod 日志:kubectl logs -n tekton-triggers-demo -l eventlistener=hello-listener
  2. Webhook 地址(status.addresses)为空

    • 验证配置的导出规则是否与 EventListener 的命名空间匹配
    • 检查自动暴露控制器是否正在运行:kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller
    • 查看控制器日志,确认是否存在匹配或配置错误
    • 确保 namespaceSelector.matchNames 中的命名空间与 EventListener 命名空间匹配
  3. Trigger 未响应

    • 验证 Webhook URL 是否可访问(检查 status.addresses)
    • 检查请求格式是否正确
    • 查看 EventListener Pod 日志:kubectl logs -n tekton-triggers-demo -l eventlistener=hello-listener
    • 验证共享的 Ingress 是否已正确配置(该资源会在 Tekton 系统命名空间中创建,并以导出规则命名,而不是按 EventListener 分别创建):kubectl get ingress -n tekton-pipelines
  4. 未创建 TaskRun

    • 确认 TriggerTemplate 配置是否正确
    • 检查 TriggerBinding 中的参数映射
    • 查看 EventListener Pod 的错误日志