配置 EventListener 自动暴露规则

本文档帮助你完成的操作

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

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

适用场景：当你希望系统自动为 EventListener 创建 Ingress 资源，而无需手动创建和管理 Ingress 资源时，请使用此功能。这在需要统一 webhook URL 模式的生产环境中尤其有用。

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

功能概览

自动暴露控制器（内部名称为 trigger-wrapper）会读取 Tekton 系统命名空间中的 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 系统命名空间（默认：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 头匹配）	Kubernetes Ingress	`webhooks.example.com`（仅域名，不含协议）
`externalHosts`	面向用户的 webhook URL，用于 UI 展示	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（可选）– 该规则允许的命名空间。使用 "*" 表示所有命名空间。
labelSelector（可选）– 用于筛选 EventListener 的 Kubernetes LabelSelector。
tls（可选）– Ingress 的 TLS 配置。每个条目指定 hosts（主机名列表）和 secretName（包含证书的 TLS Secret 名称）。
annotations（可选）– 为 Ingress 添加额外注解。适用于 cert-manager、nginx 特定配置等。由控制器管理的注解（例如 nginx.ingress.kubernetes.io/rewrite-target）会与用户提供的注解合并。

当前命名空间匹配仅支持 matchNames。如果你需要基于标签选择命名空间，请显式列出这些命名空间。

到 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`	与命名空间和 EventListener 名称组合后形成路径：`${urlPathPrefix}/${namespace}/${eventlistener-name}`
`tls`	`spec.tls`	HTTPS 的 TLS 配置。每个条目映射到 `spec.tls[].hosts` 和 `spec.tls[].secretName`
`annotations`	`metadata.annotations`	用户提供的注解会与控制器管理的注解合并
`namespaceSelector`	N/A	用于筛选 EventListener，不直接映射到 Ingress
`labelSelector`	N/A	用于筛选 EventListener，不直接映射到 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：使用自定义前缀的通配主机

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

创建一个包含证书的 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 对象

检查是否为匹配的 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 所在的命名空间，而不是系统命名空间（tekton-pipelines）。自动暴露功能会在与 EventListener 相同的命名空间中创建 Ingress 资源。

预期输出（正常）：

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

检查项：

是否存在与导出规则匹配的 EventListener 对应的 Ingress 对象
HOSTS 字段是否与导出规则中指定的 host 一致
Ingress 是否已分配 ADDRESS（可能需要几分钟）
如果没有出现 Ingress，请确认命名空间是否匹配 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

故障排查提示

如果规则未生效：
- 确认命名空间是否已列入 matchNames（或者使用 "*" 表示所有命名空间）
- 检查 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 留空，或将其设置为 "*" 以接受所有主机。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 EventListener 对外部系统的暴露方式。在更新期间请关注控制器日志，以确认协调过程已成功完成。

#配置 EventListener 自动暴露规则

#目录

#本文档帮助你完成的操作

#功能概览

#配置入口

#字段参考

#到 Ingress 资源的字段映射

#请求流图

#配置示例

#示例 1：使用自定义前缀的通配主机

#示例 2：共享主机名和前缀

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

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

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

#示例 6：配置 TLS/HTTPS

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

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

#选项 C：结合 TLS 和注解

#配置工作流

#验证与故障排查

#验证 ConfigMap 内容

#验证 Ingress 对象

#检查 EventListener 地址

#查看 Trigger 注解

#故障排查提示

配置 EventListener 自动暴露规则

目录

本文档帮助你完成的操作

功能概览

配置入口

字段参考

到 Ingress 资源的字段映射

请求流图

配置示例

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

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

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

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

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

示例 6：配置 TLS/HTTPS

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

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

选项 C：结合 TLS 和注解

配置工作流

验证与故障排查

验证 ConfigMap 内容

验证 Ingress 对象

检查 EventListener 地址

查看 Trigger 注解

故障排查提示