Operator 计费指标推送技术说明书¶

本文档指导 tfrs-operator 配置租户 Prometheus remote_write，将计费指标推送到 TFRSManager 侧的 VictoriaMetrics。

凭证管理、Nginx 加固、密钥轮换的完整方案见 specs/metrics-credential-solution.md。

1. 数据流架构¶

应用 Pod (OTLP) → OtelCollector (prometheus exporter :8889) → Prometheus (scrape + remote_write)
  → https://metrics.turingfocus.cn/api/v1/write → Nginx (Basic Auth + Fail-Closed)
  → VictoriaMetrics (127.0.0.1:8428) → ConsumptionScheduler 查询

2. 需要推送的指标与标签规范¶

指标名称	类型	必需标签	值格式
`llm_tokens`	Gauge	`cluster_id`, `namespace`, `trace_id`, `model_name`, `provider`	JSON: `{"cached_input_tokens":N, "input_tokens":N, "output_tokens":N}`
`resource_utilization`	Gauge	`cluster_id`, `namespace`, `type`	浮点数 0.0~1.0

标签说明¶

cluster_id：TFRSManager 数据库 k8s_clusters.id 的字符串值，来源于 TFRCluster.spec.metrics.remoteWrite.clusterID，由 Operator 作为 Prometheus external_labels 注入
namespace：租户命名空间名
type（resource_utilization 专用）：cpu 或 memory
trace_id（llm_tokens 专用）：LLM 调用的追踪 ID
model_name（llm_tokens 专用）：模型名称，如 gpt-4
provider（llm_tokens 专用）：提供商，如 openai

3. 关键注意事项¶

3.1 指标名称中的点号¶

OtelCollector 的 prometheus exporter 会将 OTLP 指标名中的 . 转为 _。因此： - OTLP 侧发送 llm.tokens - Prometheus 侧实际为 llm_tokens

ConsumptionScheduler 当前 PromQL 使用 llm.tokens（含点号），后续会统一为 llm_tokens。

3.2 OtelCollector namespace 前缀¶

当前 OtelCollector 配置 namespace: {{ .Namespace }}，会给所有指标名加前缀（如 tenant_a_llm_tokens）。

建议移除此 namespace 前缀，改用 external_labels 或 const_labels 中的 namespace 标签区分租户，否则 PromQL 查询时指标名不固定。

3.3 cluster_id 标识¶

cluster_id 由 TFRCluster.spec.metrics.remoteWrite.clusterID（Required 字段）提供，Operator 将其作为 Prometheus 的 external_labels 写入配置。不再依赖 annotation 或 CustomLabels 传入。

4. Prometheus remote_write 配置模板¶

global:
  scrape_interval: 15s
  evaluation_interval: 15s
  external_labels:
    cluster_id: "{{ .ClusterID }}"

remote_write:
  - url: "{{ .RemoteWriteURL }}"
    basic_auth:
      # 引用 Secret 挂载的文件，而非内联值
      # Prometheus 每次 remote_write 时重新读取文件，密钥轮换无需重启
      username_file: /etc/prometheus/remote-write-credentials/username
      password_file: /etc/prometheus/remote-write-credentials/password
    write_relabel_configs:
      - source_labels: [__name__]
        regex: 'llm_tokens|resource_utilization'
        action: keep
    queue_config:
      max_samples_per_send: 1000
      batch_send_deadline: 5s

scrape_configs:
  # ... 现有配置不变

write_relabel_configs 的 keep 规则确保只推送计费相关指标，减少带宽和存储开销。

使用 username_file / password_file（Prometheus 2.26+ 支持）而非内联 username / password，配合 K8s Secret Volume 挂载，kubelet 自动同步 Secret 变更（默认 ~1min），密钥轮换时无需重启 Prometheus。

5. 凭证管理¶

5.1 核心原则¶

凭证的唯一真实来源是 Infisical，不在磁盘上存储明文密钥
Operator 只消费凭证，不生成凭证 — 凭证通过 TFRCluster.spec.metrics.remoteWrite 必填字段注入
TFRSManager 侧 Fail-Closed — Nginx htpasswd 文件不存在时拒绝启动，VictoriaMetrics 只监听 127.0.0.1

5.2 凭证流转¶

Infisical (/metrics/REMOTE_WRITE_PASSWORD)
    │
    ├── TFRSManager 服务器: deploy.sh → 拉取密码 → 生成 htpasswd → 写入 tmpfs → nginx reload
    │
    └── K8s 集群: helm install --set metrics.remoteWrite.password=<从 Infisical 获取>
            → TFRCluster CR
            → Operator reconcile → 创建各租户 namespace 的 Secret
            → Prometheus 通过 password_file 引用

5.3 凭证 Secret¶

Operator 在每个租户 namespace 创建以下 Secret，由 Prometheus Deployment 挂载为文件：

apiVersion: v1
kind: Secret
metadata:
  name: tfrs-remote-write-credentials
  namespace: {{ .TenantNamespace }}
type: Opaque
stringData:
  username: {{ .RemoteWriteUsername }}
  password: {{ .RemoteWritePassword }}

Prometheus Deployment 将此 Secret 挂载到 /etc/prometheus/remote-write-credentials/。

5.4 密钥轮换¶

支持零停机轮换：更新 Infisical → TFRSManager 侧双密码过渡 → patch TFRCluster CR → Operator 自动更新所有租户 Secret → Prometheus 自动感知文件变更。完整流程见 specs/metrics-credential-solution.md 第 3.3 节。

6. Operator 代码改动清单¶

6.1 CRD 与 Webhook¶

文件	改动
`api/infra/v1/tfrcluster_types.go`	新增 `MetricsConfig` / `RemoteWriteConfig` 结构体，`Metrics` 字段为 Required
`api/infra/v1/tfrcluster_webhook.go`	Validating Webhook 校验 `spec.metrics.remoteWrite.*` 必填字段
`make generate && make manifests`	重新生成 deepcopy 和 CRD manifest

6.2 Controller 与 Deployable¶

文件	改动
`internal/controller/infra/tenant/options.go`	`PrometheusOptions` 新增 `RemoteWriteURL`, `RemoteWriteUsername`, `RemoteWritePassword`, `ClusterID` 字段
`internal/controller/infra/tenant/prometheus.go`	`prometheusYAMLTemplate` 添加 `external_labels` + `remote_write` 段；新增创建 `tfrs-remote-write-credentials` Secret 逻辑；Deployment 添加 Secret Volume 挂载
`internal/controller/infra/tenant/otel_collector.go`	移除 `namespace:` 前缀配置，改用 `const_labels` 中的 `namespace` 标签
`internal/controller/infra/tfrtenant_controller.go`	从 TFRCluster 读取 `spec.metrics.remoteWrite.*`，传入 `PrometheusOptions`

6.3 Helm Chart¶

文件	改动
`chart/tfrcluster/values.yaml`	新增 `metrics.remoteWrite.{url, username, password, clusterID}`（空字符串，部署时必须通过 `--set` 注入）
`chart/tfrcluster/templates/tfrcluster.yaml`	映射 values 到 CR `spec.metrics`

6.4 测试¶

文件	改动
`internal/controller/infra/tenant/prometheus_test.go`	验证 remote_write ConfigMap 生成、Secret 创建、Volume 挂载
`internal/controller/infra/tfrtenant_controller_test.go`	验证从 TFRCluster 读取 metrics 配置并传递