配置 EventListener 自动暴露规则

本文档可帮助您完成的操作

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

  • 如何配置导出规则,通过 Ingress 或 Gateway API (HTTPRoute) 自动暴露 EventListener
  • 如何设置将在 UI 中显示的 webhook URL
  • 如何为不同的命名空间或环境配置不同的暴露策略
  • 如何验证 EventListener 是否已正确暴露

使用时机:当您希望系统自动为 EventListener 创建 Ingress 资源,从而无需手动创建和管理 Ingress 资源时,可以使用此功能。这对于需要保持 webhook URL 模式一致的生产环境尤其有用。

前提条件:您应具有配置 TektonConfig 资源所需的集群管理员权限,并且应基本了解 Kubernetes Ingress 和网络概念。两个验证命令会将其输出通过管道传递给 jq CLI。

功能概览

自动暴露控制器(内部名称为 trigger-wrapper,运行于 tektoncd-enhancement-controller Deployment 中)会读取 Tekton 系统命名空间(默认:tekton-pipelines)中的 trigger-wrapper-config ConfigMap。该 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 系统命名空间(默认:tekton-pipelines)中的 trigger-wrapper-config ConfigMap。更新后,自动暴露控制器会刷新其缓存,并根据新规则协调资源。

INFO

注意:ConfigMap 名称 trigger-wrapper-config 是内部技术名称。您应按照上文所示,通过 TektonConfig 管理配置,无需直接操作 ConfigMap。

字段参考

export-rules 中的每个条目代表一种发布策略。重要字段包括:

  • name – 规则名称,也用于生成 Service/Ingress 名称。 避免名称冲突:共享 Ingress 名称是将规则名称规范化为有效的 DNS-1123 子域名后得到的结果(转换为小写,将 [a-z0-9-] 之外的字符替换为 -,并将连续的 - 合并)。此规范化过程是有损的,因此仅在此类字符上存在差异的规则名称会解析为同一个 Ingress,并相互覆盖——例如,a_b、a.b 和 A-B 最终都会变为 a-b。 请为每条规则指定一个本身就是不同的有效 DNS-1123 子域名的名称(小写字母、数字和 -);不要依赖 _、. 或字母大小写来区分两条规则。

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

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

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

    可以将其理解为:外部系统(如 GitHub、GitLab)向 EventListener 发送 Webhook 时使用的“公共地址”。

    工作方式:

    • 控制器将每个 externalHosts URL 与生成的路径组合:${externalHost}/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>
    • 例如:包含单个条目 https://webhooks.example.com 的 externalHosts 列表,加上 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://webhooks.example.com" 和 "https://backup.webhooks.example.com"
    基于 IP 的访问(无域名)使用 IP 地址的 HTTP"http://192.0.2.10"(但将 host 字段留空)
    ACP 平台平台 URL + 集群路径"https://192.0.2.10/clusters-rewrite/test"

    如果填写错误会怎样?

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

    与 host 字段的主要区别:

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

    经验法则:

    • 如果可以通过 https://webhooks.example.com:8443/triggers/ns/el 访问 Webhook,则将 https://webhooks.example.com:8443 添加到 externalHosts
    • 控制器会自动追加路径

    重要说明:

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

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

  • namespaceSelector.matchLabels(可选)– 命名空间标签;该规则适用于标签匹配的命名空间中的 EventListener。

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

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

  • annotations(可选)– Ingress 的其他注解。适用于 cert-manager、nginx 特定设置等。仅应用您提供的注解;控制器不再注入任何控制器特定的注解(例如 nginx.ingress.kubernetes.io/rewrite-target)。生成的 Ingress 路径使用 pathType: Exact,且不进行重写,因此不依赖 nginx。其后端是 ExternalName Service,因此 Ingress 控制器必须能够路由到 ExternalName Service。

  • type(可选)– 暴露资源:Ingress(默认)或 HTTPRoute(Gateway API)。为空时,为保持向后兼容,默认为 Ingress。请参阅 Gateway API(HTTPRoute)模式。

  • gateway(可选)– 使用 type: HTTPRoute 时必需。引用 HTTPRoute 所附加到的父 Gateway:name(必需)、namespace(默认为 Tekton 系统命名空间),以及可选的 sectionName 和 port。

使用 matchNames 按名称选择命名空间(所有命名空间使用 "*"),或使用 matchLabels 按命名空间标签选择;包含 matchLabels 的规则适用于标签与其匹配的命名空间。

字段到 Ingress 资源的映射

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

导出规则字段Ingress 资源字段描述
namemetadata.nameIngress 资源名称设置为规则名称,并规范化为 DNS-1123 子域名(请参阅上文的 name)
ingressClassspec.ingressClassName指定应处理此 Ingress 的 Ingress 控制器
hostspec.rules[].hostIngress 规则的主机名。为空或为 "*" 时,匹配所有主机。注意:不支持将 IP 地址用作主机值。如果使用 IP,请将 host 留空,或配置一个解析到该 IP 的域名。
urlPathPrefixspec.rules[].http.paths[].path(使用 pathType: Exact)与命名空间和 EventListener 名称组合以形成确切路径:${urlPathPrefix}/${namespace}/${eventlistener-name}
tlsspec.tls用于 HTTPS 的 TLS 配置。每个条目映射到 spec.tls[].hosts 和 spec.tls[].secretName
annotationsmetadata.annotations仅应用您提供的注解;不会注入控制器管理的注解
namespaceSelectorN/A用于筛选 EventListener,不直接映射到 Ingress
labelSelectorN/A用于筛选 EventListener,不直接映射到 Ingress
externalHostsN/A用于填充 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: "<cluster-issuer>"
WARNING

DNS 配置:在 host 字段中使用域名时,请确保 DNS 记录已配置为将该域名解析到 Ingress 控制器的 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(控制器不会添加自己的注解)

如 选项 B 中所述,将 <cluster-issuer> 替换为集群中 cert-manager ClusterIssuer 的名称。

请求流程图

externalHosts 会告知外部客户端应调用哪个 URL。Ingress 根据 host 和确切路径 ${urlPathPrefix}/${namespace}/${eventlistener} 匹配请求,并将请求转发到 Tekton 系统命名空间中的 ExternalName Service,该 Service 会解析到 EventListener sink Service。由于 sink 接受任何路径,后端会接收到未经更改的完整路径(不会进行重写)。

配置示例

示例 1:使用自定义前缀的通配符主机

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

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

示例 2:共享主机名和前缀

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 Webhook:https://gitlab-staging.example.com/staging/gitlab/${namespace}/${eventlistener}
  • GitHub Webhook: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=<cert-file> \
      --key=<key-file> \
      -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 注解配置导出规则,并添加一个 tls 条目,用于指定证书的 Secret:

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
    tls:
      - hosts:
          - webhooks.example.com
        secretName: webhooks-tls
    annotations:
      cert-manager.io/cluster-issuer: "<cluster-issuer>"
      # Optional: additional nginx SSL settings
      nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"
    namespaceSelector:
      matchNames:
        - "*"

控制器会将 tls 复制到 Ingress 的 spec.tls。然后,cert-manager 会为 tls 中的 secretName 创建 Certificate,并从注解中指定的 issuer 请求证书。如果没有 tls,生成的 Ingress 将没有 spec.tls,cert-manager 也不会创建 Certificate。

将 <cluster-issuer> 替换为集群中 cert-manager ClusterIssuer 的名称。该 issuer 必须能够在没有互联网访问的情况下工作,例如使用自己的证书颁发机构进行签名的 CA issuer。使用公共 ACME 服务器(例如 Let's Encrypt)的 ACME issuer 无法从隔离集群访问该服务器,因此证书永远不会签发。

选项 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 才会执行操作:它会为其中列出的 secretName 创建 Certificate。如果没有 tls,cert-manager 注解不会生成证书。

Gateway API(HTTPRoute)模式

除了 Ingress 之外,还可以通过设置 type: HTTPRoute,使导出规则通过 Gateway API 暴露 EventListener。 对于没有 Ingress controller(或没有可用的 ingressClass)但运行 Envoy Gateway 等 Gateway 实现的集群,建议使用此模式。 现有的 Ingress 行为不变,Gateway 模式也会继续填充 status.addresses,确保 UI 和 Git webhook 注册正常工作。

前提条件:

  • 已安装 Gateway API CRD 和 Gateway 实现(例如 Envoy Gateway)。controller 仅在启动时检查 HTTPRoute v1 和 ReferenceGrant v1beta1。如果此时未提供这些资源,controller 将保持 Ingress-only 模式,并在 type: HTTPRoute 规则所选择的 EventListener 上记录警告事件 GatewayAPIUnavailable;如果 CRD 是在 controller 启动后安装的,也会发生这种情况。安装 CRD 后,重启 controller,例如删除其 Pod: kubectl delete pod -n tekton-pipelines -l app=tektoncd-enhancement-controller。
  • 已存在父级 Gateway。其 listener allowedRoutes.namespaces 必须允许 Tekton 系统命名空间(默认为 tekton-pipelines),因为生成的 HTTPRoute 会在该命名空间中创建。controller 不会修改 Gateway;它只读取 HTTPRoute 的 Accepted 和 ResolvedRefs 条件。
  • 在此模式下,必须设置 externalHosts ——它是 status.addresses 的来源。

示例:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      configMaps:
        trigger-wrapper-config:
          data:
            config: |
              export-rules:
                - name: gateway-webhooks
                  type: HTTPRoute
                  host: webhooks.example.com
                  urlPathPrefix: /triggers
                  externalHosts:
                    - "https://webhooks.example.com"
                  gateway:
                    name: eg
                    namespace: envoy-gateway-system
                  namespaceSelector:
                    matchNames:
                      - "*"

controller 创建的资源:

  • 在系统命名空间中,每个匹配的 EventListener 对应一个 HTTPRoute,其中包含一个 path.type: Exact 匹配项(${urlPathPrefix}/${namespace}/${eventlistener})、一个指向你的 Gateway 的 parentRefs 条目,以及一个跨命名空间的 backendRefs 条目,该条目直接指向 EventListener sink Service(el-<name>,端口 8080)。不使用 URLRewrite filter ——sink 接受完整路径。仅当 EventListener 未设置其他 servicePort,也未设置 TLS_CERT 和 TLS_KEY 环境变量时,Service 才仅具有端口 8080;设置 TLS 变量后,listener 会提供 HTTPS。
  • 在 EventListener 所在的命名空间中,每个 EventListener 对应一个 ReferenceGrant,通过 to.name 将范围限制为该单个 sink Service,使系统命名空间中的 HTTPRoute 可以跨命名空间边界引用它(最小权限)。

模式特定的字段行为:ingressClass、tls 和 annotations 仅适用于 Ingress 模式,在 type: HTTPRoute 时会被忽略。对于 Gateway 模式下的 HTTPS,请改为在 Gateway listener 上终止 TLS ——请参阅下方的 Gateway API 模式下的 HTTPS。

验证:

# HTTPRoutes are created in the system namespace, named per (EventListener, rule).
kubectl get httproute -n tekton-pipelines

# ReferenceGrants are created in each EventListener's namespace.
kubectl get referencegrant -n <eventlistener-namespace>

只有当 HTTPRoute 已被其 Gateway 标记为 Accepted 且已 ResolvedRefs 时,才会发布 status.addresses(以及 Trigger 注解端点)。如果没有显示地址,请检查 kubectl get httproute <name> -n tekton-pipelines -o yaml 中的 status.parents[].conditions ——Accepted: False 或 ResolvedRefs: False 条件通常表示 Gateway listener 不允许系统命名空间,或 sink Service 不可访问。

Gateway API 模式下的 HTTPS

在 Gateway API 中,TLS 在 Gateway listener 上终止,而不是在 HTTPRoute 上终止——trigger-wrapper 在此模式下不会管理证书(tls 字段仅适用于 Ingress 模式)。要通过 HTTPS 提供 EventListener,请将导出规则附加到具有 HTTPS listener 的 Gateway,其 tls.certificateRefs 指向你的证书 Secret,并通过 gateway.sectionName(或 gateway.port)将规则固定到该 listener。

1. 具有 HTTPS listener 的 Gateway(由平台 / 集群管理员管理):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
  namespace: envoy-gateway-system
spec:
  gatewayClassName: eg
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: webhooks.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: webhooks-tls
      allowedRoutes:
        namespaces:
          from: All

证书 Secret(上面的 webhooks-tls,其中包含 tls.crt / tls.key) 和 Gateway 由集群/平台管理。allowedRoutes.namespaces.from 必须允许 Tekton 系统命名空间,因为生成的 HTTPRoute 会在该命名空间中创建。

2. 通过 gateway.sectionName 将导出规则固定到该 HTTPS listener:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      configMaps:
        trigger-wrapper-config:
          data:
            config: |
              export-rules:
                - name: gateway-webhooks-https
                  type: HTTPRoute
                  host: webhooks.example.com
                  urlPathPrefix: /triggers
                  externalHosts:
                    - "https://webhooks.example.com"
                  gateway:
                    name: eg
                    namespace: envoy-gateway-system
                    sectionName: https
                  namespaceSelector:
                    matchNames:
                      - "*"

注意:

  • 将规则的 host 设置为 listener 的 hostname,使 HTTPRoute 的 hostname 与 TLS SNI 匹配,并在 externalHosts 中使用 https:// scheme,使发布的 status.addresses 声明使用 HTTPS。
  • gateway.sectionName 将 HTTPRoute 固定到命名 listener;当 listener 通过端口区分时,改用 gateway.port(或同时使用二者)。 同时省略二者时,Gateway 可以将路由附加到任何兼容的 listener。
  • trigger-wrapper 仅创建 HTTPRoute(及其 ReferenceGrant);它 不会创建或修改 Gateway、listener 或证书 Secret。

配置工作流

  1. 按照配置入口中所示的格式编写变更,并将其保存为 tektonconfig.yaml。规则是一个 config 字符串,因此该文件会替换所有现有 规则:将 TektonConfig 当前包含的每条规则都复制到其中。
  2. 将该文件合并到现有的 TektonConfig 中: kubectl patch tektonconfig config --type merge --patch-file tektonconfig.yaml。 不要对仅包含部分 TektonConfig 的文件使用 kubectl apply -f: kubectl apply 会将该文件存储在 kubectl.kubernetes.io/last-applied-configuration annotation 中,而之后对另一个部分文件执行 kubectl apply -f 时,会删除前一个文件设置但后一个文件未包含的字段。如果后一个文件省略这些规则,Operator 会将它们重置为随附的空列表,并删除每个已公开 EventListener 的 Ingress 或 HTTPRoute。
  3. 等待 Operator 传播 ConfigMap;随后,自动公开 controller 会自动协调新资源。

推荐设置

启用时机。当 EventListener 原本都需要手动编写 Ingress,Git 或 registry webhook 才能访问它们时,应启用自动公开。TektonConfig 中的导出规则会应用于规则的 namespaceSelector 和 labelSelector 所选中的每个 listener,因此每个选中的 listener 都会采用其规则中的 host、path pattern 和 TLS 设置,并且 status.addresses 中的地址会遵循一种可预测的格式。

推荐值。仅通过 TektonConfig 管理规则(请参阅 配置入口)。从单个共享规则开始,设置一个独特且有效的 DNS-1123 name、一个 host、默认的 urlPathPrefix: /triggers、externalHosts 中的 https:// URL,并通过 tls 配置 TLS(hosts 和 secretName)。Secret 可以预先在 Tekton 系统命名空间中创建,也可以在同时设置 cert-manager 的 annotations 时,通过针对该 secretName 的 Certificate 使用 cert-manager 进行管理,同时使用无需互联网访问即可工作的 issuer,例如 CA issuer。在多个团队共享的集群中,应使用 opt-in label 选择命名空间:为其中 listener 可以公开的每个命名空间添加 label(例如 kubectl label namespace <namespace> expose-webhooks=true),并将 namespaceSelector.matchLabels 设置为该 label,如下面的示例所示,这样团队的 listener 只有在其命名空间带有该 label 后才会公开。 为命名空间添加 label 需要对 Namespace 对象具有权限,通常需要集群管理员权限。自动 公开 controller 不会响应命名空间 label 的变更:添加或删除 label 后,需要等到该命名空间中的 EventListener 下一次协调时才会生效。要立即应用变更,请修改这些 EventListener 中每个对象的 metadata,例如使用 kubectl annotate eventlistener <name> -n <namespace> <key>=<value> --overwrite, 或修改规则。仅在每个命名空间都属于同一团队的集群中,使用只有一个条目的 namespaceSelector.matchNames '*';它会公开每个命名空间中的 listener。将 ingressClass 设置为集群 Ingress controller 的 IngressClass(kubectl get ingressclass 会列出这些 IngressClass);示例中将其设置为 <ingress-class>。仅当环境或 provider 需要使用不同 host 时,才使用 namespaceSelector 和 labelSelector 添加更多规则,如 配置示例中的示例 3 所示。在没有可用 Ingress controller 的集群中,使用 type: HTTPRoute 和 gateway,并在 Gateway listener 上终止 TLS,如 Gateway API(HTTPRoute)模式中所述。

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      configMaps:
        trigger-wrapper-config:
          data:
            config: |
              export-rules:
                - name: secure-webhooks
                  host: webhooks.example.com
                  ingressClass: <ingress-class>
                  urlPathPrefix: /triggers
                  externalHosts:
                    - "https://webhooks.example.com"
                  tls:
                    - hosts:
                        - webhooks.example.com
                      secretName: webhooks-tls-secret
                  namespaceSelector:
                    matchLabels:
                      expose-webhooks: "true"

前提条件。具有编辑 TektonConfig 的集群管理员权限。需要安装与 ingressClass 匹配的 Ingress controller;或者,在 HTTPRoute 模式下,需要安装 Gateway API CRD,并且这些 CRD 必须在自动公开 controller 启动之前安装,或在安装后重启 controller(请参阅 Gateway API(HTTPRoute)模式)。此外,在该模式下还需要 Gateway 实现,以及一个父 Gateway,其 listener 允许来自 Tekton 系统命名空间的路由(Tekton 系统命名空间的默认值为 tekton-pipelines)。为 host 创建一条 DNS 记录,使其能够从发送 webhook 的系统解析,并在 Tekton 系统命名空间中创建 tls 中命名的 TLS Secret(或者使用无需互联网访问即可工作的 cert-manager issuer,例如 CA issuer,并同时配置该 tls 条目)。公开功能仅负责路由请求;请按照 Webhook Secret 身份验证中的说明,在每个 listener 上对请求进行身份验证。

要确认规则是否生效,请使用 验证和故障排除中的检查方法。要撤销某条规则,请合并一个不包含该规则的文件,如 配置工作流中所述;故障排除提示中的删除规则部分列出了会被删除的内容,以及可能遗留的共享 Ingress。

验证和故障排除

验证 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 对象

检查是否为匹配的公开规则创建了 Ingress 资源:

# The shared Ingress is created in the Tekton system namespace (default:
# tekton-pipelines), NOT in the EventListener's namespace, and it is named
# after the export rule (not after the EventListener).
kubectl get ingress -n tekton-pipelines

重要:系统命名空间中每条公开规则都会创建一个共享 Ingress。其名称为规则的 name,并且对于每个匹配的 EventListener(${urlPathPrefix}/${namespace}/${eventlistener}),都包含一个 pathType: Exact 路径。EventListener 自身的命名空间中不会创建按 EventListener 划分的 Ingress。在 Alauda Container Platform 上,如果 ALB 仅限于某些项目的命名空间,则只有在该 ALB 服务系统命名空间所属的项目时,它才会服务此 Ingress;Operator 会为该项目添加标签 cpaas.io/project=cpaas-system。否则,Ingress 不会获得 ADDRESS。

预期输出(正常):

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

检查内容:

  • 对于至少匹配一个 EventListener 的每条公开规则,都存在一个共享 Ingress
  • HOSTS 字段与公开规则中指定的 host 匹配(空值或 * 表示所有 host)
  • Ingress 已分配 ADDRESS(可能需要几分钟)
  • 检查 kubectl get ingress <rule-name> -n tekton-pipelines -o yaml,确认每个匹配的 EventListener 都有一个 pathType: Exact 路径
  • 如果没有出现 Ingress,请验证命名空间是否与规则的 namespaceSelector 匹配(对于按名称选择的规则为 matchNames,对于按 label 选择的规则为 matchLabels),并确认 EventListener label 与 labelSelector 匹配

检查 EventListener 地址

验证 EventListener 状态是否包含生成的 webhook 地址。将 <el-name> 替换为您的 EventListener 名称,并将 <namespace> 替换为其部署所在的命名空间:

kubectl get eventlistener <el-name> -n <namespace> \
  -o jsonpath='{.status.addresses}' | jq .

预期输出(正常):

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

检查内容:

  • addresses 数组包含与您的 externalHosts 配置匹配的 URL
  • URL 遵循以下模式:<externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name>
  • 如果 addresses 为空或缺失,可能的原因包括:
    • EventListener 不匹配任何公开规则
    • 匹配的规则没有 externalHosts(地址仅根据 externalHosts 构建)
    • 匹配的规则使用 type: HTTPRoute,且其路由尚未同时被其 Gateway 标记为 Accepted 并标记为 ResolvedRefs(只有在这两个条件均为 True 时才会发布地址)
    • 匹配的规则使用 Ingress 模式,但其 ExternalName Service 或共享 Ingress 无法创建或更新(controller 日志会显示 Failed to process export rule;host 中的 IP 地址就是其中一个原因,请参阅故障排除提示中的使用 IP 地址而非域名)
    • 配置无法加载(controller 日志会显示 Failed to load config,请参阅故障排除提示中的label 选择器配置错误)。此时 controller 不会发布新地址,并保留之前发布的地址

检查 Trigger 注解

检查存储在 Trigger 注解中的公开元数据。将 <trigger-name> 替换为您的 Trigger 名称,并将 <namespace> 替换为其部署所在的命名空间:

kubectl get trigger <trigger-name> -n <namespace> \
  -o jsonpath='{.metadata.annotations.triggers\.tekton\.dev/eventlistener-info}' | jq .

预期输出(正常):对于 tekton-triggers-demo 命名空间中的 Trigger my-trigger,同一命名空间中的 EventListener my-eventlistener 通过 triggerRef 引用该 Trigger(直接匹配):

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

检查内容:

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

故障排除提示

  • 如果规则未生效:

    • 验证命名空间是否列在 matchNames 中(或使用 "*" 表示所有命名空间);对于按 label 选择的规则,验证命名空间 label 是否与 matchLabels 匹配
    • 检查 EventListener label 是否满足 labelSelector 要求
    • 检查是否有规则包含无效的 labelSelector(请参阅下一项):一个无效选择器会阻止所有规则生效
  • label 选择器配置错误:

    • 无法解析的 labelSelector 会使 controller 拒绝整个配置,而不仅仅是该规则。controller 会保留现有的 Ingress、HTTPRoute 和 EventListener 地址,在修复选择器之前不会应用任何规则变更
    • controller 日志会显示带有错误 invalid config: export rule[<index>] (<rule-name>): invalid labelSelector: ... 的 Failed to load config。读取这些日志需要对 tekton-pipelines 中 Pod 日志的读取权限,通常需要集群管理员权限。使用 -l 时,kubectl logs 只会打印最后 10 行,除非设置了 --tail;要读取完整日志,请使用:kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller --tail=-1 | grep 'Failed to load config'
  • 删除规则(或切换其 type):

    • 当配置变更协调 EventListener 时,删除该规则生成的资源(Ingress + ExternalName Service,或 HTTPRoute + ReferenceGrant)
    • 如果删除规则或切换其 type 时不存在 EventListener,该规则的共享 Ingress 会被保留。其后端 ExternalName Service 已被删除,因此对其路径的请求会返回 503 或 500。请手动删除该 Ingress:它位于 Tekton 系统命名空间中(默认值为 tekton-pipelines),名称以规则命名,并按照上文对 name 的说明进行规范化,例如 kubectl delete ingress -n tekton-pipelines <export-rule-name>。在至少存在一个 EventListener 时删除规则可以避免此问题
    • 在 Ingress 和 HTTPRoute 之间切换规则时,会清理旧模式的资源并创建新模式的资源
    • 将 export-rules 设置为空数组会禁用所有外部公开
    • 当没有规则匹配时,EventListener status.addresses 将被清除
  • 使用 IP 地址而非域名:

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

    • 解决方案 1:将 host 留空,或将其设置为 "*" 以接受所有 host。无论 host header 是什么,Ingress 都会匹配请求:

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

      1. 设置 DNS 解析:添加一条 A 记录,将您的域名指向该 IP 地址(例如,webhooks.example.com → 192.0.2.10)

      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.0.2.10"  # Or use the domain: "http://webhooks.example.com"
            namespaceSelector:
              matchNames:
                - "*"
    • 注意:externalHosts 可以包含 IP 地址或 URL,因为它仅用于填充 EventListener status.addresses,不会影响 Ingress 创建。但是,Ingress 本身必须在 host 字段中使用有效的 hostname(或留空)。

通过 TektonConfig 维护 ConfigMap,您可以灵活控制 Tekton EventListener 如何向外部系统公开。在更新期间,请关注 controller 日志,以确认协调已成功完成。