配置 EventListener 自动暴露规则

本文档可帮助您完成的内容

本文档帮助您通过自动暴露功能配置 EventListener 的自动外部暴露。您将了解:

  • 如何配置导出规则,通过 Ingress 自动暴露 EventListener
  • 如何设置会显示在 UI 中的 webhook URL
  • 如何为不同的 namespace 或环境配置不同的暴露策略
  • 如何验证 EventListener 是否已正确暴露

何时使用:当您希望系统自动为 EventListener 创建 Ingress 资源,从而无需手动创建和管理 Ingress 资源时,请使用此功能。这在生产环境中特别有用,因为您需要一致的 webhook URL 模式。

前提条件:您应具有集群管理员权限以配置 TektonConfig 资源,并且应对 Kubernetes Ingress 和网络概念有基本了解。

功能概述

自动暴露控制器(内部名称为 trigger-wrapper)会读取 Tekton 系统 namespace 中的 trigger-wrapper-config ConfigMap(默认值:tekton-pipelines)。该 ConfigMap 中定义的 export-rules 决定哪些 EventListener 应该对外暴露(Service、Ingress 等),并使用生成的端点填充 EventListener/Trigger 状态。

INFO

技术说明:内部组件名称是 trigger-wrapper,但您无需记住它。您只需要通过 TektonConfig 配置导出规则,系统会自动处理其余部分。

配置入口

在 Alauda Tekton 中,建议通过 TektonConfig 自定义资源来管理此配置。将规则定义嵌入到 spec.pipeline.options.configMaps.trigger-wrapper-config.data.config 下,例如:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      configMaps:
        trigger-wrapper-config:
          data:
            config: |
              export-rules:
                - name: test-webhooks
                  host: webhooks.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
                  ingressClass: nginx
                  urlPathPrefix: /triggers
                  externalHosts:
                    - "https://webhooks.example.com"
                    - "https://backup.webhooks.example.com"
                  namespaceSelector:
                    matchNames:
                      - "*"

Operator 会将此 spec 同步到 Tekton 系统 namespace(默认:tekton-pipelines)中的 trigger-wrapper-config ConfigMap。更新后,自动暴露控制器会刷新其缓存,并根据新规则协调资源。

INFO

注意:ConfigMap 名称 trigger-wrapper-config 是内部技术名称。您只需像上面所示通过 TektonConfig 管理配置,而无需直接与该 ConfigMap 交互。

字段参考

export-rules 中的每一项都代表一种发布策略。重要字段如下:

  • name – 规则名称,也用于生成 Service/Ingress 名称。

  • ingressClass(可选)– 要使用的 Ingress controller,例如 nginx、traefik。

  • host(可选)– Ingress 匹配的主机名。留空则接受所有 host。重要:配置域名时,请确保 DNS 解析已正确配置(或在本地测试时将其添加到 /etc/hosts)。该域名必须能从发送 webhook 的系统中解析。

  • externalHosts(可选)– 作用:定义将显示在 UI 中、并填充到 EventListener 的 status.addresses 字段里的 webhook URL。

    可以将其理解为:外部系统(如 GitHub、GitLab)将用来向您的 EventListener 发送 webhook 的“公网地址”。

    工作方式:

    • 控制器会将每个 externalHosts URL 与生成的路径组合:${externalHost}/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>
    • 例如:externalHosts: ["https://webhooks.example.com"] + urlPathPrefix: /triggers → 最终 URL:https://webhooks.example.com/triggers/my-namespace/my-listener
    • 这些 URL 会显示在 EventListener 的 status.addresses 字段中,便于直接复制到 GitHub/GitLab 的 webhook 配置里

    常见场景:

    场景externalHosts 中填写什么示例
    标准 HTTPS 域名您的公网域名,带 https://"https://webhooks.example.com"
    具有自定义端口的 LoadBalancer域名/IP 加端口号"https://webhooks.example.com:8443"
    多个访问入口备用 URL 数组["https://primary.com", "https://backup.com"]
    基于 IP 的访问(无域名)使用 IP 地址的 HTTP 地址"http://192.168.1.100"(但请将 host 字段留空)
    ACP 平台平台 URL + 集群路径"https://192.168.1.100/clusters-rewrite/test"

    如果填写错误会怎样?

    • ✅ Ingress 仍然可以正常工作(此字段不影响 Ingress 创建)
    • ❌ 用户会在 UI 中看到错误的 webhook URL
    • ❌ 将 status.addresses 中的 URL 复制到 GitHub/GitLab 会失败
    • 🔧 修复方式:更新 TektonConfig 中的 externalHosts 值,控制器会刷新 EventListener 状态

    与 host 字段的关键区别:

    字段作用由谁使用示例
    hostIngress 路由规则(匹配 HTTP Host header)Kubernetes Ingresswebhooks.example.com(仅域名,不含协议)
    externalHosts面向用户的 webhook URL,用于 UI 展示EventListener status.addresseshttps://webhooks.example.com(包含协议的完整 URL)

    经验法则:

    • 如果您可以通过 https://webhooks.example.com:8443/triggers/ns/el 访问 webhook,那么填写:externalHosts: ["https://webhooks.example.com:8443"]
    • 控制器会自动追加路径

    重要说明:

    • 始终包含协议(http:// 或 https://)
    • 如果 LoadBalancer 使用非标准端口,请包含自定义端口
    • 不要在 urlPathPrefix 中包含路径(例如 /triggers)——控制器会自动将其追加到 externalHosts 的末尾
    • 如果不确定,请先留空并检查实际可访问的 URL,然后再更新配置
  • urlPathPrefix(可选)– 路径前缀;默认值为 /triggers。Ingress 中渲染的最终路径为 ${urlPathPrefix}/${eventlistener-namespace}/${eventlistener-name}。请始终以 / 开头,并避免以斜杠结尾。

  • namespaceSelector.matchNames(可选)– 此规则允许的 namespace。使用 "*" 可匹配所有 namespace。

  • labelSelector(可选)– 用于筛选 EventListener 的 Kubernetes LabelSelector。

  • tls(可选)– Ingress 的 TLS 配置。每个条目指定 hosts(主机名列表)和 secretName(包含证书的 TLS Secret 名称)。

  • annotations(可选)– 为 Ingress 添加附加注解。适用于 cert-manager、nginx 特定配置等。由控制器管理的注解(例如 nginx.ingress.kubernetes.io/rewrite-target)会与用户提供的注解合并。

当前 namespace 匹配仅支持 matchNames。如果您需要基于标签的 namespace 选择,请显式列出这些 namespace。

导出规则到 Ingress 资源的字段映射

下表展示了导出规则字段如何映射到生成的 Ingress 资源:

导出规则字段Ingress 资源字段说明
namemetadata.nameIngress 资源名称设置为规则名称
ingressClassspec.ingressClassName指定应由哪个 Ingress controller 处理此 Ingress
hostspec.rules[].hostIngress 规则的主机名。如果为空或为 "*",则匹配所有 host。注意: 不支持将 IP 地址作为 host 值。如果使用 IP,请将 host 留空,或配置一个可解析到该 IP 的域名。
urlPathPrefixspec.rules[].http.paths[].path与 namespace 和 EventListener 名称结合,形成路径:${urlPathPrefix}/${namespace}/${eventlistener-name}
tlsspec.tlsHTTPS 的 TLS 配置。每个条目映射到 spec.tls[].hosts 和 spec.tls[].secretName
annotationsmetadata.annotations用户提供的注解会与控制器管理的注解合并
namespaceSelector不适用用于筛选 EventListener,不直接映射到 Ingress
labelSelector不适用用于筛选 EventListener,不直接映射到 Ingress
externalHosts不适用用于填充 EventListener 的 status.addresses,不直接映射到 Ingress

映射示例:

给定以下导出规则:

export-rules:
  - name: test-webhooks
    host: webhooks.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    ingressClass: nginx
    urlPathPrefix: /triggers
    tls:
      - hosts:
          - webhooks.example.com
        secretName: webhooks-tls-secret
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
WARNING

DNS 配置:在 host 字段中使用域名时,请确保已配置 DNS 记录,将域名解析到您的 Ingress controller IP。对于本地测试,您可以在 /etc/hosts(Linux/Mac)或 C:\Windows\System32\drivers\etc\hosts(Windows)中添加条目。

生成的 Ingress 将具有:

  • metadata.name:test-webhooks
  • spec.ingressClassName:nginx
  • spec.rules[0].host:webhooks.example.com
  • spec.rules[0].http.paths[].path:/triggers/${namespace}/${eventlistener-name}(适用于每个匹配的 EventListener)
  • spec.tls[0].hosts:["webhooks.example.com"]
  • spec.tls[0].secretName:webhooks-tls-secret
  • metadata.annotations:包含 cert-manager.io/cluster-issuer 和控制器管理的注解

请求流转图

externalHosts 告诉外部客户端应调用哪个 URL。Ingress 仍然会通过 host 和 ${urlPathPrefix}/${namespace}/${eventlistener} 匹配请求,而后端 Service 接收到的路径就是该路径。

配置示例

示例 1:带自定义前缀的通配 host

export-rules:
  - name: wildcard-host
    urlPathPrefix: /hooks/default
    ingressClass: nginx
    namespaceSelector:
      matchNames:
        - cicd

结果:Ingress 将暴露 /hooks/default/${namespace}/${eventlistener}。由于 host 为空,任何 hostname 都会被接受——这非常适合外部网关分配公网域名的场景。

示例 2:共享 hostname 和前缀

export-rules:
  - name: all-listeners
    host: webhooks.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    urlPathPrefix: /triggers
    ingressClass: nginx
    namespaceSelector:
      matchNames:
        - "*"

结果:每个 EventListener 都会以 https://webhooks.example.com/triggers/${namespace}/${eventlistener} 的形式对外可见;后端接收到的路径保持一致。

示例 3:按环境划分的规则

export-rules:
  - name: staging-gitlab
    host: gitlab-staging.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    urlPathPrefix: /staging/gitlab
    namespaceSelector:
      matchNames:
        - staging-tools
    labelSelector:
      matchLabels:
        webhook-type: gitlab

  - name: prod-github
    host: github-prod.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    urlPathPrefix: /prod/github
    ingressClass: traefik
    namespaceSelector:
      matchNames:
        - prod-tools
    labelSelector:
      matchLabels:
        webhook-type: github

结果:

  • GitLab webhooks:https://gitlab-staging.example.com/staging/gitlab/${namespace}/${eventlistener}
  • GitHub webhooks:https://github-prod.example.com/prod/github/${namespace}/${eventlistener}

示例 4:团队范围发布,使用默认前缀

export-rules:
  - name: team-a
    urlPathPrefix: /triggers
    namespaceSelector:
      matchNames:
        - team-a

结果:只有 team-a 中的 EventListener 会被暴露,路径为 /triggers/team-a/${eventlistener}。

示例 5:多个外部端点并调整前缀

export-rules:
  - name: multi-endpoints
    host: webhook.internal.local  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    urlPathPrefix: /internal/hooks
    externalHosts:
      - https://webhooks.example.com/hooks/
      - https://backup.example.com/api/hooks
    namespaceSelector:
      matchNames:
        - ci-tools

结果:

  • Ingress 会在内部提供 webhook.internal.local/internal/hooks/${namespace}/${eventlistener}。
  • 对外您可以发布 https://webhooks.example.com/hooks/internal/hooks/${namespace}/${eventlistener} 和 https://backup.example.com/api/hooks/internal/hooks/${namespace}/${eventlistener}。
  • 后端 Service 始终接收 /internal/hooks/${namespace}/${eventlistener}。

示例 6:配置 TLS/HTTPS

选项 A:使用预先创建的 Secret 手动配置 TLS

  1. 创建一个包含证书的 TLS Secret:

    kubectl create secret tls webhooks-tls-secret \
      --cert=path/to/cert.pem \
      --key=path/to/key.pem \
      -n tekton-pipelines
  2. 使用 TLS 配置您的导出规则:

    export-rules:
      - name: secure-webhooks
        host: webhooks.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
        urlPathPrefix: /triggers
        ingressClass: nginx
        tls:
          - hosts:
              - webhooks.example.com
            secretName: webhooks-tls-secret
        namespaceSelector:
          matchNames:
            - "*"

控制器会自动使用指定的 Secret 为 Ingress 配置 TLS。

选项 B:使用 cert-manager 自动管理证书

使用 cert-manager 注解配置您的导出规则:

export-rules:
  - name: cert-manager-webhooks
    host: webhooks.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    urlPathPrefix: /triggers
    ingressClass: nginx
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      # Optional: additional nginx SSL settings
      nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"
    namespaceSelector:
      matchNames:
        - "*"

cert-manager 将自动执行以下操作:

  • 创建 Certificate 资源
  • 从 Let's Encrypt(或您配置的颁发者)获取证书
  • 创建 TLS Secret
  • 更新带有 TLS 配置的 Ingress

选项 C:同时使用 TLS 和注解

您可以将手动 TLS 配置与附加注解结合使用:

export-rules:
  - name: custom-tls-with-annotations
    host: webhooks.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    urlPathPrefix: /triggers
    ingressClass: nginx
    tls:
      - hosts:
          - webhooks.example.com
        secretName: custom-tls-secret
    annotations:
      nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"
      nginx.ingress.kubernetes.io/ssl-ciphers: "HIGH:!aNULL:!MD5"
    namespaceSelector:
      matchNames:
        - "*"

注意: 当同时配置 tls 和 cert-manager 注解时,tls 配置优先生效。若要自动管理证书,请仅使用 cert-manager 注解,而不要配置 tls。

配置工作流

  1. 编辑 TektonConfig 资源(请参见配置入口)。
  2. 应用更改:kubectl apply -f tektonconfig.yaml。
  3. 等待 Operator 传播 ConfigMap;随后自动暴露控制器会自动协调新资源。

验证与故障排查

验证 ConfigMap 内容

检查 ConfigMap 是否包含预期配置:

kubectl get configmap trigger-wrapper-config -n tekton-pipelines -o yaml

预期输出(正常):

apiVersion: v1
kind: ConfigMap
metadata:
  name: trigger-wrapper-config
  namespace: tekton-pipelines
data:
  config: |
    export-rules:
      - name: test-webhooks
        host: webhooks.example.com  # Ensure DNS resolution is configured (or add to /etc/hosts for testing)
        ingressClass: nginx
        urlPathPrefix: /triggers
        externalHosts:
          - "https://webhooks.example.com"
          - "https://backup.webhooks.example.com"
        namespaceSelector:
          matchNames:
            - "*"

检查项:

  • ConfigMap 存在,并且包含 config 键
  • export-rules 数组与您的 TektonConfig 规格一致
  • YAML 语法有效(没有解析错误)

验证 Ingress 对象

检查是否已为匹配的 EventListener 创建 Ingress 资源:

# Replace <namespace> with the namespace where your EventListener is deployed
# For example, if your EventListener is in the 'tekton-triggers-demo' namespace:
kubectl get ingress -n tekton-triggers-demo

重要:命令中的 <namespace> 应替换为您的 EventListener 所在的 namespace,而不是系统 namespace(tekton-pipelines)。自动暴露功能会在与 EventListener 相同的 namespace 中创建 Ingress 资源。

预期输出(正常):

NAME                              CLASS   HOSTS                    ADDRESS   PORTS   AGE
el-<eventlistener-name>           nginx   webhooks.example.com     ...        80      5m

检查项:

  • 已为匹配导出规则的 EventListener 创建 Ingress 对象
  • HOSTS 字段与导出规则中指定的 host 匹配
  • Ingress 已分配 ADDRESS(可能需要几分钟)
  • 如果没有出现 Ingress,请验证 namespace 是否与 matchNames 匹配,以及 EventListener 标签是否与 labelSelector 匹配

检查 EventListener 地址

验证 EventListener 状态是否包含生成的 webhook 地址:

# Replace <el-name> with your EventListener name and <namespace> with the namespace where it's deployed
# For example, if your EventListener is named 'hello-listener' in the 'tekton-triggers-demo' namespace:
kubectl get eventlistener hello-listener -n tekton-triggers-demo \
  -o jsonpath='{.status.addresses}' | jq

预期输出(正常):

[
  {
    "url": "https://webhooks.example.com/triggers/<namespace>/<el-name>"
  },
  {
    "url": "https://backup.webhooks.example.com/triggers/<namespace>/<el-name>"
  }
]

检查项:

  • addresses 数组包含与 externalHosts 配置匹配的 URL
  • URL 遵循以下模式:<externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>
  • 如果 addresses 为空或缺失,EventListener 可能没有匹配到任何导出规则

检查 Trigger 注解

检查存储在 Trigger 注解中的导出元数据:

# Replace <trigger-name> with your Trigger name and <namespace> with the namespace where it's deployed
# For example, if your Trigger is named 'my-trigger' in the 'tekton-triggers-demo' namespace:
kubectl get trigger my-trigger -n tekton-triggers-demo \
  -o jsonpath='{.metadata.annotations.triggers\.tekton\.dev/eventlistener-info}' | jq

预期输出(正常):

[
  {
    "name": "my-eventlistener",
    "namespace": "my-namespace",
    "endpoints": [
      "https://webhooks.example.com/triggers/my-namespace/my-eventlistener",
      "https://backup.webhooks.example.com/triggers/my-namespace/my-eventlistener"
    ],
    "relevance": {
      "score": 1000,
      "namespaceScore": 1000,
      "labelScore": 1000,
      "namespaceSelector": {
        "matchNames": ["my-namespace"]
      },
      "matchType": "direct"
    }
  }
]

检查项:

  • 注解包含一个 EventListener 信息数组
  • 每个条目都包含 name、namespace、endpoints 和 relevance 字段
  • endpoints 数组与 EventListener 的 status.addresses 一致
  • relevance.score 表示 EventListener 与 Trigger 的匹配程度(越高越好)
  • 如果注解缺失,Trigger 可能没有找到任何匹配的 EventListener

故障排查提示

  • 如果某条规则未生效:

    • 验证该 namespace 是否已列在 matchNames 中(或使用 "*" 匹配所有 namespace)
    • 检查 EventListener 标签是否满足 labelSelector 要求
    • 确保 EventListener 处于 Ready 状态
  • 标签选择器配置错误:

    • 会在控制器日志中表现为解析错误
    • 检查控制器日志:kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller
  • 删除规则:

    • 会级联删除生成的资源(Ingress、Service 等)
    • 将 export-rules 设置为空数组会禁用所有外部暴露
    • 当没有规则匹配时,EventListener 的 status.addresses 会被清空
  • 使用 IP 地址而不是域名:

    • 问题:Kubernetes Ingress 资源不支持将 IP 地址作为 host 值。如果您在 host 中配置 IP 地址(例如 host: 192.168.1.100),Ingress 将无法创建或无法正常工作。

    • 解决方案 1:将 host 留空或设置为 "*",以接受所有 host。Ingress 将不论 host header 为何都能匹配请求:

      export-rules:
        - name: ip-based-webhooks
          host: ""  # or omit the host field entirely
          urlPathPrefix: /triggers
          externalHosts:
            - "http://192.168.1.100"  # Use IP in externalHosts for client reference
          namespaceSelector:
            matchNames:
              - "*"
    • 解决方案 2:配置一个解析到您 IP 地址的域名,然后在 host 字段中使用该域名:

      1. 配置 DNS 解析:添加一条指向该 IP 的 A 记录(例如,webhooks.example.com → 192.168.1.100)

      2. 使用域名配置导出规则:

        export-rules:
          - name: domain-webhooks
            host: webhooks.example.com  # Domain that resolves to your IP. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
            urlPathPrefix: /triggers
            externalHosts:
              - "http://192.168.1.100"  # Or use the domain: "http://webhooks.example.com"
            namespaceSelector:
              matchNames:
                - "*"
    • 注意:externalHosts 可以包含 IP 地址或 URL,因为它仅用于填充 EventListener 的 status.addresses,不会影响 Ingress 创建。不过,Ingress 本身在 host 字段中必须使用有效的 hostname(或者留空)。

通过使用 TektonConfig 管理 ConfigMap,您可以灵活控制 Tekton EventListener 面向外部系统的暴露方式。请在更新期间留意控制器日志,以确认协调是否成功完成。