配置 EventListener 自动暴露规则

本文档可帮助你完成什么

本文档帮助你通过自动暴露功能配置 EventListeners 的自动对外暴露。你将了解：

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

使用场景：当你希望系统为 EventListeners 自动创建 Ingress 资源，避免手动创建和管理 Ingress 资源时，使用此功能。这在需要统一 webhook URL 模式的生产环境中特别有用。

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

功能概览

自动暴露控制器（内部名称为 trigger-wrapper）会读取 Tekton 系统 namespace（默认：tekton-pipelines）中的 trigger-wrapper-config ConfigMap。该 ConfigMap 中定义的 export-rules 决定哪些 EventListeners 应该对外暴露（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 匹配的主机名。留空则接受所有主机。重要：当配置域名时，请确保 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 字段的关键区别：

字段	作用	使用方	示例
`host`	Ingress 路由规则（匹配 HTTP Host header）	Kubernetes Ingress	`webhooks.example.com`（仅域名，无协议）
`externalHosts`	用于 UI 展示的用户可见 webhook URL	EventListener status.addresses	`https://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（可选）– 用于筛选 EventListeners 的 Kubernetes LabelSelector。
tls（可选）– Ingress 的 TLS 配置。每一项指定 hosts（主机名列表）和 secretName（包含证书的 TLS Secret 名称）。
annotations（可选）– 额外的 Ingress 注解。适用于 cert-manager、nginx 特定设置等。由控制器管理的注解（例如 nginx.ingress.kubernetes.io/rewrite-target）会与用户提供的注解合并。

目前 namespace 匹配仅支持 matchNames。如果你需要基于 label 选择 namespace，请显式枚举这些 namespace。

到 Ingress 资源的字段映射

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

导出规则字段	Ingress 资源字段	说明
`name`	`metadata.name`	Ingress 资源名称设置为规则名称
`ingressClass`	`spec.ingressClassName`	指定应由哪个 Ingress controller 处理该 Ingress
`host`	`spec.rules[].host`	Ingress 规则的主机名。若为空或 `""`，则匹配所有主机。注意：* 不支持将 IP 地址作为 host 值。如果使用 IP，请保持 `host` 为空，或配置一个可解析到该 IP 的域名。
`urlPathPrefix`	`spec.rules[].http.paths[].path`	与 namespace 和 EventListener 名称组合后形成路径：`${urlPathPrefix}/${namespace}/${eventlistener-name}`
`tls`	`spec.tls`	HTTPS 的 TLS 配置。每一项映射到 `spec.tls[].hosts` 和 `spec.tls[].secretName`
`annotations`	`metadata.annotations`	用户提供的注解会与控制器管理的注解合并
`namespaceSelector`	N/A	用于筛选 EventListeners，不会直接映射到 Ingress
`labelSelector`	N/A	用于筛选 EventListeners，不会直接映射到 Ingress
`externalHosts`	N/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: "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 中的 EventListeners 会被暴露，地址为 /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

创建一个包含证书的 TLS Secret：

kubectl create secret tls webhooks-tls-secret \
  --cert=path/to/cert.pem \
  --key=path/to/key.pem \
  -n tekton-pipelines

使用 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（或你配置的 issuer）获取证书
创建 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。

配置工作流

编辑 TektonConfig 资源（参见 配置入口）。
应用更改：kubectl apply -f tektonconfig.yaml。
等待 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 对象

检查是否为匹配的 EventListeners 创建了 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 可能没有找到任何匹配的 EventListeners

故障排查建议

如果某条规则未生效：
- 确认 namespace 是否已列在 matchNames 中（或使用 "*" 匹配所有 namespace）
- 检查 EventListener 标签是否满足 labelSelector 的要求
- 确保 EventListener 处于 Ready 状态
labelSelector 配置错误：
- 会在控制器日志中显示为解析错误
- 检查控制器日志：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 留空，或将其设置为 "*" 以接受所有主机。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 字段中必须使用有效的主机名（或留空）。

通过使用 TektonConfig 管理 ConfigMap，你可以灵活控制 Tekton EventListeners 如何向外部系统暴露。在更新期间请关注控制器日志，以确认协调过程已成功完成。

#配置 EventListener 自动暴露规则

#目录

#本文档可帮助你完成什么

#功能概览

#配置入口

#字段参考

#到 Ingress 资源的字段映射

#请求流图

#配置示例

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

#示例 2：共享 hostname 和前缀

#示例 3：按环境区分的规则

#示例 4：按团队范围发布并使用默认前缀

#示例 5：多个外部端点和调整后的前缀

#示例 6：配置 TLS/HTTPS

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

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

#选项 C：结合 TLS 和注解

#配置工作流

#验证与故障排查

#验证 ConfigMap 内容

#验证 Ingress 对象

#检查 EventListener 地址

#检查 Trigger 注解

#故障排查建议

配置 EventListener 自动暴露规则

目录

本文档可帮助你完成什么

功能概览

配置入口

字段参考

到 Ingress 资源的字段映射

请求流图

配置示例

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

示例 2：共享 hostname 和前缀

示例 3：按环境区分的规则

示例 4：按团队范围发布并使用默认前缀

示例 5：多个外部端点和调整后的前缀

示例 6：配置 TLS/HTTPS

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

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

选项 C：结合 TLS 和注解

配置工作流

验证与故障排查

验证 ConfigMap 内容

验证 Ingress 对象

检查 EventListener 地址

检查 Trigger 注解

故障排查建议