Prometheus 监控 Tekton 全栈实战：从 PipelineRun 状态到控制器延迟的云原生 CI/CD 可观测性

---

Tekton 是 Kubernetes 原生的 CI/CD 框架，通过声明式 Pipeline 和 Task 将构建、测试、部署自动化。然而，当 PipelineRun 卡在 Running 状态、TaskRun 失败率飙升、控制器队列积压时，整个交付流水线就会停滞。Prometheus 可以通过 Tekton 内置的 Observability 模块 直接抓取 Tekton Pipelines 控制器和 webhook 的指标，同时可结合 tekton-pipeline-exporter 获取 PipelineRun/TaskRun 的详细状态。本文将带你从启用指标端点、配置抓取，到解读核心指标、构建 Grafana 大屏与告警规则，让云原生 CI/CD 管道完全透明可控。

---

1. 方案选型：Tekton 原生指标 vs 社区导出器

方案	适用场景	特点
Tekton Pipelines 控制器 /metrics	控制器内部行为、队列深度、reconcile 延迟、webhook 调用	从 Tekton Pipelines v0.24+ 开始内置，无需额外部署；覆盖队列、资源、API 请求等
tekton-pipeline-exporter (社区)	PipelineRun / TaskRun 状态（成功、失败、运行中）、持续时间	通过 Kubernetes API 轮询，将运行状态转化为 Prometheus 指标，支持多命名空间
Tekton Results + 外部导出器	长期流水线记录和趋势	适合已完成流水线的历史分析

推荐组合：Tekton 控制器内置指标 负责平台健康监控，tekton-pipeline-exporter 负责业务运行状态，二者互补构成完整的 CI 可观测性。本文重点覆盖控制器内置指标，并在进阶部分包含 PipelineRun 状态导出的实践。

---

2. 启用 Tekton Pipelines 的 Prometheus 端点

Tekton Pipelines 控制器的 Prometheus 指标默认已经暴露，只需确保 config-observability ConfigMap 中启用了指标。

2.1 检查并配置 Observability

在 tekton-pipelines 命名空间中查看 ConfigMap：

kubectl get configmap config-observability -n tekton-pipelines -o yaml

确保其中包含：

metrics:
  prometheus.enabled: "true"
  prometheus.port: "9090"   # 默认端口
  prometheus.path: "/metrics"

如果不存在，可以创建或编辑 ConfigMap，重启 tekton-pipelines-controller Pod。

2.2 暴露控制器 Service 或 PodMonitor

默认情况下，控制器 Pod 监听在 9090 端口的 /metrics 路径。可以使用 Kubernetes Service 或 PodMonitor 让 Prometheus 发现。

创建 Service 暴露指标（若已存在可跳过）：

apiVersion: v1
kind: Service
metadata:
  name: tekton-pipelines-controller-metrics
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: tekton-pipelines
spec:
  ports:
    - name: metrics
      port: 9090
      targetPort: 9090
  selector:
    app.kubernetes.io/component: controller
    app.kubernetes.io/name: tekton-pipelines

2.3 验证端点

kubectl port-forward -n tekton-pipelines svc/tekton-pipelines-controller-metrics 9090:9090
curl http://localhost:9090/metrics

应看到 tekton_pipelines_controller_* 等指标。

---

3. 配置 Prometheus 抓取

3.1 使用 ServiceMonitor（Prometheus Operator）

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: tekton-pipelines
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: controller
      app.kubernetes.io/name: tekton-pipelines
  namespaceSelector:
    matchNames:
      - tekton-pipelines
  endpoints:
    - port: metrics
      interval: 30s

3.2 静态配置

如果未使用 Operator，直接在 Prometheus 中添加 Job：

scrape_configs:
  - job_name: 'tekton-pipelines'
    scrape_interval: 30s
    static_configs:
      - targets: ['tekton-pipelines-controller-metrics.tekton-pipelines.svc:9090']
        labels:
          app: 'tekton'
          component: 'controller'

---

4. 核心监控指标与 PromQL

控制器暴露的指标前缀为 tekton_pipelines_controller_，同时包含 Go 运行时指标（go_*）和进程指标（process_*）。

4.1 控制器工作队列与 Reconcile

指标	含义
tekton_pipelines_controller_workqueue_depth	当前工作队列深度（按 reconciler 标签，如 PipelineRun, TaskRun）
tekton_pipelines_controller_workqueue_adds_total	添加到队列的总项数
tekton_pipelines_controller_workqueue_latency_seconds (Histogram)	项目在队列中等待的延迟
tekton_pipelines_controller_workqueue_retries_total	重试总次数
tekton_pipelines_controller_reconcile_duration_seconds (Histogram)	Reconcile 循环耗时
tekton_pipelines_controller_reconcile_total (Counter)	完成的 Reconcile 总数（按 success 状态）

PromQL 示例：

• PipelineRun 队列积压：tekton_pipelines_controller_workqueue_depth{reconciler="PipelineRun"} > 0
• Reconcile 平均延迟：rate(tekton_pipelines_controller_reconcile_duration_seconds_sum[5m]) / rate(tekton_pipelines_controller_reconcile_duration_seconds_count[5m])
• Reconcile 失败率：rate(tekton_pipelines_controller_reconcile_total{status="error"}[5m]) / rate(tekton_pipelines_controller_reconcile_total[5m])

4.2 Webhook 与 API

指标	含义
tekton_pipelines_controller_webhook_admission_total	准入 Webhook 调用总数
tekton_pipelines_controller_webhook_admission_latency_seconds (Histogram)	Webhook 延迟
tekton_pipelines_controller_client_latency_seconds (Histogram)	对 Kubernetes API 的客户端延迟

PromQL 示例：

• Webhook 错误率：rate(tekton_pipelines_controller_webhook_admission_total{status="error"}[5m])
• API 调用 P99 延迟：histogram_quantile(0.99, rate(tekton_pipelines_controller_client_latency_seconds_bucket[5m]))

4.3 资源统计（可选，取决于版本）

部分版本会暴露 tekton_pipelines_controller_running_count（运行中的 PipelineRun/TaskRun 数量）等指标，可以作为 CI 负载的直接度量。

---

5. Grafana 仪表盘推荐

• Tekton Pipelines Controller Dashboard：Dashboard ID 15108（社区贡献），展示队列深度、Reconcile 延迟、Webhook 调用、API 延迟等。
• Kubernetes Controller 通用面板：ID 10856（kube-state-metrics）可配合展示 PipelineRun 的 CRD 状态（需 kube-state-metrics 支持 Tekton CRD）。
• 自定义 CI 运营面板：使用 tekton_pipelines_controller_workqueue_depth 绘制队列热力图，Reconcile 延迟趋势图，以及 PipelineRun 的状态表（若结合 exporter）。

导入后选择数据源，用 namespace 或 component 变量过滤。

---

6. 告警规则实战

groups:
  - name: tekton_alerts
    rules:
      - alert: TektonControllerDown
        expr: up{job="tekton-pipelines"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Tekton Pipelines 控制器不可达"

      - alert: TektonControllerHighQueueDepth
        expr: tekton_pipelines_controller_workqueue_depth{reconciler="PipelineRun"} > 10
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "PipelineRun 工作队列深度超过 10，可能控制器处理缓慢"

      - alert: TektonControllerHighReconcileErrorRate
        expr: rate(tekton_pipelines_controller_reconcile_total{status="error"}[10m]) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Tekton 控制器 Reconcile 错误率 > 0.05/s"

      - alert: TektonWebhookHighLatency
        expr: histogram_quantile(0.99, rate(tekton_pipelines_controller_webhook_admission_latency_seconds_bucket[5m])) > 5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Webhook P99 延迟超过 5 秒，可能影响资源创建"

---

7. 进阶：PipelineRun 状态导出与多集群监控

7.1 使用 tekton-pipeline-exporter 获取业务状态

社区项目 tektoncd/pipeline-exporter（或 wlynch/tekton-exporter）可以通过 Kubernetes watch 跟踪 PipelineRun 和 TaskRun 的状态，并暴露为 Prometheus 指标（如 tekton_pipelinerun_status, tekton_taskrun_duration_seconds）。

部署示例：

docker run -d \
  --name tekton-exporter \
  -v ~/.kube/config:/etc/kubernetes/config \
  wlynch/tekton-exporter:latest \
    --kubeconfig /etc/kubernetes/config \
    --namespace ""   # 所有命名空间

常用指标：

• tekton_pipelinerun_status{status="running|succeeded|failed"}
• tekton_pipelinerun_duration_seconds (Histogram)
• tekton_taskrun_status

Prometheus 抓取后，即可按项目统计流水线成功率、平均持续时间等。

7.2 多集群监控

对于多 Kubernetes 集群的 Tekton 部署，可在每个集群内部署 Prometheus/Agent，通过远程写或联邦方式汇聚到中央 Prometheus，并用 cluster 标签区分。

7.3 安全与访问控制

• 控制器 /metrics 端口应仅对内网或 Prometheus 开放，使用 Kubernetes NetworkPolicy 限制。
• 如果使用 Prometheus Operator，ServiceMonitor 需要适当的 RBAC 权限。
• tekton-pipeline-exporter 需要读取 Tekton CRD 的 RBAC 授权，最小权限为 get, list, watch。

7.4 指标基数控制

Tekton 控制器可能暴露大量按 namespace、pipeline 等细分的指标，如果不想全部收集，可在 Prometheus 中使用 metric_relabel_configs 过滤。

---

8. 总结

通过启用 Tekton 内置的 Prometheus 端点并配合业务状态导出器，你可以在同一套可观测平台中监控 CI/CD 平台本身的健康（控制器队列、Webhook 延迟）以及每一次 PipelineRun 的成败和耗时。当流水线排队积压、控制器错误率攀升或特定 Pipeline 持续失败时，Grafana 看板和 Alertmanager 会第一时间发出警告，为 DevOps 团队争取宝贵的响应时间。将 Tekton 纳入全栈可观测性体系，让云原生交付从代码提交到应用上线，全程透明、可控。