将 SigNoz 用作 Kubernetes 的 Prometheus 数据源

Grafana、KEDA、Headlamp、Ray、OpenCost、Argo Rollouts 以及 Kubernetes 自动扩缩组件（HPA、VPA）都要求提供 Prometheus 服务器 URL。一旦指标数据存入 SigNoz，这个 URL 往往就是保留 Prometheus 服务器运行的唯一理由。

Prometheus API Bridge 是一款开源无状态服务，由它直接承接这些工具原本对 Prometheus 的请求，底层数据源切换为 SigNoz。

Info

这是社区集成项目，并非 SigNoz 官方产品。相关问题、完整配置参考及更新信息，请参阅上游仓库。

架构

KEDA、Kubernetes 自动扩缩组件及本指南涉及的其他工具，均通过 Prometheus HTTP API 通信。它们会执行 PromQL 查询、获取指标和标签名称以支持自动补全，并查找时间序列将指标映射到 Kubernetes 资源。然而，SigNoz 仅实现了该 API 中的两个查询端点（/api/v1/query 和 /api/v1/query_range），不足以支撑上述工具运行。Bridge 基于这两个端点实现了其余部分，保持 PromQL 查询语句不变进行转发，并使用您的 API 密钥向 SigNoz 进行身份验证，因此客户端仅需提供标准的 Bearer Token 即可。

前置条件

1. 一个可从待部署 Bridge 的 Kubernetes 集群访问的 SigNoz 实例（Cloud 或 Self-Hosted 均可）。
2. 一个用于 SigNoz 的服务账户 API 密钥，需授予 SigNoz-Viewer 角色以获得只读权限。
3. Helm 3.8 或更高版本，以支持 OCI Chart。

已在 SigNoz Cloud 环境下使用 Prometheus API Bridge v0.2.0 及 Self-Hosted SigNoz v0.141.1 完成测试。

安装 Bridge

步骤 1：创建命名空间和密钥

这个桥接服务会从 Kubernetes Secret 中读取两个凭据。Chart 本身不会创建它们，在两个 Secret 都存在之前，Pod 会一直处于 CreateContainerConfigError 状态。本文全程使用 observability 命名空间。

先在 shell 中设置好这两个值。桥接服务在启动时会拒绝空 Secret，所以如果这里没有设置变量，之后不会报认证错误，而是直接进入崩溃循环。

Copy

export SIGNOZ_API_KEY="<your-signoz-api-key>"
export BRIDGE_BEARER_TOKEN="$(openssl rand -hex 32)"

确认以下取值：

• <your-signoz-api-key>：前置条件中创建的服务账号 API key。
• BRIDGE_BEARER_TOKEN：一个新生成的随机 token，由 Prometheus 客户端发给桥接服务，与你的 SigNoz key 无关。

现在创建命名空间和两个 Secret：

Copy

kubectl create namespace observability
kubectl -n observability create secret generic prometheus-api-bridge-signoz \
  --from-literal=api-key="$SIGNOZ_API_KEY"
kubectl -n observability create secret generic prometheus-api-bridge-auth \
  --from-literal=token="$BRIDGE_BEARER_TOKEN"

第 2 步：安装 Chart

values.yaml

backend:
  type: signoz
  signoz:
    url: <signoz-url>
    apiKeySecret:
      name: prometheus-api-bridge-signoz
      key: api-key
server:
  auth:
    bearerTokenSecret:
      name: prometheus-api-bridge-auth
      key: token

Copy

helm upgrade --install prometheus-api-bridge \
  oci://ghcr.io/simonepri/charts/prometheus-api-bridge \
  --version <bridge-version> \
  --namespace observability \
  --values values.yaml

确认以下取值：

• <signoz-url>：SigNoz 实例的基础 URL。Cloud 版为 https://<tenant>.<region>.signoz.cloud；自托管版则是你自己的地址，如 https://signoz.example.com，或集群内 query 服务的 URL。
• <bridge-version>：项目 releases 页面上的最新版本。

该 Chart 默认要求使用 Bearer Token，且仅允许 ClusterIP Service。Ingress、TLS、免认证模式及 NetworkPolicy 选项的详细说明，请参阅 Chart 参数参考。

验证

将 Service 端口转发到本地。该命令会保持终端会话打开，请让它继续运行：

Copy

kubectl -n observability port-forward service/prometheus-api-bridge 9090:9090

第二个终端不会继承第一个终端中导出的环境变量。请从 Secret 中读取 Token，然后询问 Bridge 某个已收集指标在 SigNoz 中报告的标签：

Copy

export BRIDGE_BEARER_TOKEN=$(kubectl -n observability get secret prometheus-api-bridge-auth \
  -o jsonpath='{.data.token}' | base64 -d)
 
curl -sSG --fail-with-body http://localhost:9090/api/v1/labels \
  --data-urlencode 'match[]={__name__="<metric-name>"}' \
  --header "Authorization: Bearer $BRIDGE_BEARER_TOKEN"

验证以下值：

• <metric-name>：SigNoz 中已存在的低基数指标，例如 k8s.pod.memory.usage。你可以在 SigNoz UI 的 Metrics 页面找到该指标。

SigNoz 的指标名称包含点号，而 PromQL 不允许在裸指标选择器中使用点号。务必将名称包装为 {__name__="..."}。如果直接使用裸名称 k8s.pod.memory.usage，会报错 backend query failed。

单个指标的数据量可能仍然过大。请添加标签匹配器以缩小范围，并为包含点号的标签名加上引号：

Copy

--data-urlencode 'match[]={__name__="k8s.pod.memory.usage","k8s.namespace.name"="<namespace>"}'

如果返回了标签名称列表，说明 Bridge 已接受该 Token 且 SigNoz 做出了响应。如果 data 数组为空，则表示 Bridge 可达，但 SigNoz 中没有该指标的数据。因此，在接入任何工具之前，请确保数据正在正常流入 SigNoz。

Warning

/-/ready 接口在进程启动后即返回 200。它不会测试你的 SigNoz URL 或 API Key，因此不要将其作为 Bridge 正常工作的证明。

集群内的工具现在可以在任何预期连接 Prometheus 服务器的地方使用此 URL：

Copy

http://prometheus-api-bridge.observability.svc:9090

连接你的工具

将各个工具的 Prometheus 服务器地址统一替换为该 URL。例如，KEDA 中的 serverAddress 或 Prometheus Adapter 中的 prometheus.url。部分工具所需的配置不止一个 URL。项目文档中的已验证集成列表是最新的工具清单，其中每一项都附有对应的 Helm values 和 manifests 链接。

其中若干工具无法发送 bearer token

项目端到端测试用例运行该 bridge 时并未配置 token。它们将 server.auth.allowUnauthenticated=true 置为真值，并清除 server.auth.bearerTokenSecret.name 字段。

这两项操作必须同时执行。仅设置前者只能绕过 chart 强制要求 token 名称的检查。只要名称字段存在，chart 仍会注入 token，导致 bridge 对无法发送该 header 的工具返回 401 错误。

在生产集群中，项目建议通过 networkPolicy.ingress 或等效的网络控制机制来限制 bridge 的访问。由于 networkPolicy.enabled 默认值为 false，chart 不会自动添加相关策略。

bridge 返回的指标名称与 SigNoz 中存储的名称一致，而这些名称取决于采集方式。OpenTelemetry 接收器存储的是带点号的名称，如 k8s.pod.memory.usage；Prometheus 抓取存储的是下划线名称，如 up。

仅支持 Prometheus 的工具请求的是标准 Prometheus 指标名称，例如 container_cpu_usage_seconds_total、kube_pod_status_phase 和 node_cpu_seconds_total。原生 OpenTelemetry 流水线不会生成这些名称。因此，即使 bridge 和数据摄入正常，该工具也会得到空结果。

若要增加 Prometheus 风格的指标副本，需开启 chart 的采集配置。这些配置会抓取 cAdvisor、kubelet 和 kube-state-metrics。所有数据源默认关闭，请通过 collection.sources.cadvisor.enabled、collection.sources.kubelet.enabled 和 collection.sources.kubeStateMetrics.enabled 启用所需项。

若缺少必要参数，chart 将拒绝渲染。在启用任何数据源前，请先设置以下参数：

• clusterName：开启采集时必填。Chart 会把它附加到每一条采集到的指标上。
• collection.sources.kubeStateMetrics.target：启用 kube-state-metrics 但不使用内置依赖时必填。建议改为设置 kube-state-metrics.enabled=true，让 Chart 一并安装它。

把 collection.mode 设为 standalone 可安装一个专用 Collector；设为 existing 则可复用你已有的 Collector。

在 existing 模式下，还需把 collection.existing.serviceAccount.name 和 collection.existing.serviceAccount.namespace 指向该 Collector 的 ServiceAccount。之后 Chart 会向 ConfigMap prometheus-api-bridge-collector 的 collector.yaml 键中渲染一段配置。剩下三步需要你自己完成：

1. 把该键挂载到你的 Collector，并用 --config=file:/etc/prometheus-api-bridge/collector.yaml 加载。
2. 确保你的 Collector 发行版包含 Prometheus receiver。
3. 确保 collection.existing.exporter 指定的 exporter 已存在于你的 Collector 中，且其端点和认证均已配置好。

项目的 existing-Collector fixture 提供了一个可用的示例。

在 standalone 模式下，Collector 由 Chart 管理，导出配置也由它负责。默认端点是集群内的自托管地址，不启用 TLS、无认证。如果使用 SigNoz Cloud，请将端点指向你的数据接入端点，并附上接入密钥：

values.yaml

collection:
  mode: standalone
  otlp:
    endpoint: "https://ingest.<region>.signoz.cloud:443"
    insecure: false
    secretHeaders:
      - name: signoz-ingestion-key
        secretKeyRef:
          name: signoz-ingestion
          key: ingestion-key

请核对这些值：

• <region>：你的 SigNoz Cloud region。
• signoz-ingestion：由你自行创建的 Secret，保存你的
  原始来源： signoz