企业官网建设流程全解析

• 云原生
• 容器编排

Grafana Tempo 是一个与 Grafana 原生集成、高度可扩展的分布式链路追踪系统，支持 Jaeger、OpenTelemetry、Zipkin 等多种主流追踪协议。本指南以 Bitnami grafana-tempo Helm Chart 为对象，系统讲解其在 Kubernetes 集群上的安装、配置、监控集成与持久化方案，读者读完可独立完成一套生产可用的 Tempo 分布式追踪平台的搭建与调优。

一、Chart 概览与前置条件

1.1 这个 Chart 做了什么

Bitnami 的 grafana-tempo Chart 通过 Helm 包管理器在 Kubernetes 集群中引导一个完整的 Grafana Tempo 部署。从 Chart 元数据（Chart.yaml）可以看到，它当前对应应用版本2.8.2，Chart 版本为5.0.1，并声明了两个子 Chart 依赖：

• memcached（7.x.x）：默认随 Chart 一起部署，为 Tempo 提供 bloom 过滤器与 trace-id 索引缓存；
• common（2.x.x）：提供标签、affinity、securityContext 渲染等公共模板能力。

Chart 的关键字（keywords）为grafana、tracing、metrics、infrastructure，定位非常明确：基础设施层的链路追踪与指标一体化组件。

1.2 前置条件

在开始安装前，需要满足以下环境要求：

• Kubernetes 1.23+
• Helm 3.8.0+
• 底层基础设施支持 PV（Persistent Volume）供应（因为 ingester 默认开启持久化）

二、快速安装

2.1 最简单的方式（TL;DR）

helm install my-release oci://registry-1.docker.io/bitnamicharts/grafana-tempo

2.2 通过自定义 Registry 安装

如果从私有 Registry 或镜像仓库安装，需要替换占位符REGISTRY_NAME和REPOSITORY_NAME：

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/grafana-tempo

例如 Bitnami 官方仓库的对应值为REGISTRY_NAME=registry-1.docker.io、REPOSITORY_NAME=bitnamicharts。安装完成后，可以使用helm list查看已部署的所有 release。

默认配置即可完成一次可用的部署。如需调整参数，可参考下文 Parameters 章节列出的全部可配置项。

2.3 使用--set指定参数

每个参数都可以通过helm install的--set key=value[,key=value]参数指定。例如启用 Jaeger GRPC 追踪接入：

helm install my-release \ --set tempo.traces.jaeger.grpc=true \ oci://REGISTRY_NAME/REPOSITORY_NAME/grafana-tempo

2.4 使用 values 文件

更推荐的方式是将参数写入 YAML 文件，通过-f传入：

helm install my-release -f values.yaml oci://REGISTRY_NAME/REPOSITORY_NAME/grafana-tempo

Chart 仓库中的默认 values.yaml（共 3352 行）可作为自定义配置的起点模板。

三、Tempo 组件架构与配置原理

3.1 组件级（Component）拆分部署

从模板目录 templates 的结构可以看出，这个 Chart 将 Tempo 拆分为 6 个核心工作负载，每个组件以-target=xxx启动参数运行（见各组件模板中的args）：

从源码结构可以推断：所有组件共享同一份tempo.yaml配置与同一套镜像，区别只在于-target指定了该进程扮演的角色。这与 Tempo 官方"单二进制多 target"的设计一脉相承。

此外还有一个附加工作负载：

• vulture（deployment.yaml）：Tempo 官方自带的负载测试工具，默认启用（vulture.enabled=true），用于向集群持续注入合成追踪数据以验证链路。

3.2 端口规划

所有 Tempo 组件统一使用以下端口（由tempo.containerPorts定义，见 values.yaml）：

• web（HTTP）：3200，提供/ready就绪探针等 HTTP 端点；
• grpc：9095，组件间及查询的 gRPC 通信；
• gossipRing：7946，memberlist gossip 协议端口，用于组件间发现与 ring 同步。

vulture 组件额外使用8080（vulture.containerPorts.http），query-frontend 的 tempo-query sidecar 使用7777（queryFrontend.query.containerPorts.grpcJaeger）暴露给 Jaeger query 的 gRPC 端口。

3.3 配置共享机制

Chart 通过两个 ConfigMap 向所有组件下发配置：

1. tempo-configmap（tempo-configmap.yaml）：生成tempo.yaml，内容来自tempo.configuration；
2. overrides-configmap（overrides-configmap.yaml）：生成overrides.yaml（per-tenant override），内容来自tempo.overridesConfiguration。

各组件的 Pod 模板中通过checksum/config注解对 tempo-configmap 内容做 sha256 校验（如 compactor deployment.yaml），配置变更会触发滚动更新，确保配置与进程始终一致。configmap 以 subPath 方式挂载到/bitnami/grafana-tempo/conf/tempo.yaml与/bitnami/grafana-tempo/conf/overrides.yaml。

query-frontend 额外使用 query-configmap.yaml 生成 tempo-query 的tempo-query.yaml配置。

3.4 默认配置内容解读

Chart 内置的默认tempo.configuration（见 values.yaml）涵盖了生产所需的核心骨架，值得逐段理解：

• multitenancy_enabled: false：默认关闭多租户；
• cache：使用随 Chart 部署的 memcached 作为 bloom 过滤器与 trace-id-index 的缓存后端；
• compactor：block 保留策略48h，ring 的 kvstore 使用memberlist；
• distributor：根据tempo.traces.*开关动态生成各协议的 receiver 端点：
  • Jaeger gRPC：0.0.0.0:14250
  • Jaeger thrift_compact：0.0.0.0:6831，thrift_binary：0.0.0.0:6832
  • Jaeger thrift_http：0.0.0.0:14268
  • Zipkin：0.0.0.0:9411
  • OTLP HTTP：0.0.0.0:4318，OTLP gRPC：0.0.0.0:4317
  • OpenCensus：0.0.0.0:55678
• querier：frontend_worker指向 query-frontend 的 headless 服务，实现查询结果回传；
• ingester：lifecycler.ring使用 memberlist，tokens_file_path位于tempo.dataDir；
• metrics_generator：WAL 路径为{dataDir}/wal，remote_write来自metricsGenerator.remoteWrite；
• memberlist：bind 到 gossipRing 端口7946，并自动加入 gossip-ring headless 服务完成集群成员发现；
• server：http_listen_port=3200、grpc_listen_port=9095；
• storage.trace：本地后端，WAL 路径{dataDir}/wal、trace 数据路径{dataDir}/traces。

注意：配置内容支持 Go 模板渲染（include "common.tplvalues.render"），这意味着你可以在tempo.configuration中引用 Chart 内计算出的服务名等动态值。

3.5 追踪协议开关

在tempo.traces下，Chart 提供了细粒度的协议开关（默认值见下表），用于决定 distributor 监听哪些 receiver：

从 values.yaml 的模板逻辑可以看出，每个开关对应的 receiver 端点只有在对应开关为 true 时才会被渲染进tempo.yaml。

四、配置与安装细节

4.1 资源请求与限制

Chart 允许为所有容器设置resources（CPU、内存请求与限制），这对生产工作负载至关重要，且应针对实际场景调整。为了简化这一过程，Chart 提供了resourcesPreset预设值，可自动填充resources段，合法取值为：none、nano、micro、small、medium、large、xlarge、2xlarge（预设定义复用自 bitnami/common chart 的 _resources.tpl）。

需要说明：resourcesPreset适合快速起步，但生产环境不建议直接使用预设，因为预设无法完全贴合你的具体需求，官方推荐显式配置resources（compactor.resources、ingester.resources等）。

资源渲染逻辑（如 compactor deployment.yaml）：当resources非空时优先使用resources，否则当resourcesPreset != "none"时套用预设。

4.2 滚动标签（Rolling tag）与不可变标签（Immutable tag）

生产环境强烈建议使用不可变标签（immutable tag）。这样可以确保部署不会因为同一 tag 被更新为不同镜像而自动变化。Bitnami 会在主容器发布新版本、发生重大变更或存在严重漏洞时，发布新版本 Chart 来更新容器。

在 values.yaml 中可以看到当前默认 tag 为2.8.2-debian-12-r1，这是带完整版本号的可追溯镜像。也可以使用tempo.image.digest（如sha256:aa....）锁定镜像摘要，注意 digest 一旦设置会覆盖 tag。

4.3 附加环境变量

若需为某个组件注入额外环境变量（如自定义初始化脚本），可在各子配置中通过extraEnvVars添加，distributor、compactor、ingester、querier、queryFrontend、vulture六个子配置均支持：

compactor: extraEnvVars: - name: LOG_LEVEL value: error distributor: extraEnvVars: - name: LOG_LEVEL value: error ingester: extraEnvVars: - name: LOG_LEVEL value: error querier: extraEnvVars: - name: LOG_LEVEL value: error queryFrontend: extraEnvVars: - name: LOG_LEVEL value: error vulture: extraEnvVars: - name: LOG_LEVEL value: error

也可以改用 ConfigMap 或 Secret 承载环境变量，通过各子配置的extraEnvVarsCM或extraEnvVarsSecret引用。在模板中，这些值会分别渲染为env（列表）与envFrom（configMapRef/secretRef），见 compactor deployment.yaml。

4.4 Sidecar 与 Init Container

如果需要在同一 Pod 中附加额外容器（如额外的指标或日志导出器），可以通过各子配置的sidecars参数定义：

sidecars: - name: your-image-name image: your-image imagePullPolicy: Always ports: - name: portname containerPort: 1234

如果 sidecar 需要暴露额外端口，可通过service.extraPorts补充：

service: extraPorts: - name: extraPort port: 11311 targetPort: 11311

两点重要提示：

• Chart 本身已为可用的 Prometheus exporter 内置了 sidecar 容器，可通过部署时添加--enable-metrics=true激活；因此sidecars参数只应用来添加额外容器。
• 如需 init 容器，使用initContainers参数：

initContainers: - name: your-image-name image: your-image imagePullPolicy: Always ports: - name: portname containerPort: 1234

另外，Chart 还内置了可选的volumePermissionsinit 容器（默认enabled: false），用于在启用持久化时修正 PV 挂载点的属主为runAsUser:fsGroup，其实现逻辑可参考 ingester statefulset.yaml。

4.5 Pod 亲和性（Affinity）

Chart 允许通过affinity参数设置自定义亲和性。作为替代，也可使用 bitnami/common chart 提供的预设配置：podAffinityPreset、podAntiAffinityPreset或nodeAffinityPreset，每个组件子配置均支持。

从模板实现看（如 compactor deployment.yaml），当affinity为空时，模板会依次渲染podAffinity、podAntiAffinity、nodeAffinity三个预设；当显式设置affinity后预设即被忽略。各组件默认podAntiAffinityPreset=soft。

4.6 外部 Memcached 支持

如果希望 Tempo 连接集群外部的 Memcached（例如使用托管缓存服务，或让多个应用共享缓存服务器），可以通过externalMemcached参数指定连接信息，并同时关闭 Chart 自带的 memcached 子 Chart：

memcached.enabled=false externalMemcached.host=myexternalhost externalMemcached.port=11211

相关参数包括externalMemcached.host（默认""）与externalMemcached.port（默认11211）。若保留内置 memcached（memcached.enabled=true，默认），它作为子 Chart 部署，默认端口11211，支持memcached.auth.enabled认证开关（默认 false）。

4.7 备份与恢复

Kubernetes 上备份/恢复 Helm Chart 部署，需要备份源部署的持久卷，并使用 Velero 等工具将其挂载到新部署中。具体操作请参考 Bitnami 官方 Velero 备份恢复指南。

五、持久化（Persistence）

Bitnami 的 grafana-tempo 镜像将 ingester 数据存放在容器/bitnami路径下（实际数据目录由tempo.dataDir指定，默认/bitnami/grafana-tempo/data）。Chart 使用 Persistent Volume Claims（PVC）保证数据跨部署留存：

• ingester.persistence.enabled（默认true）：ingester 是 StatefulSet，通过volumeClaimTemplates动态创建 PVC（见 ingester statefulset.yaml）；
• metricsGenerator.persistence.enabled（默认false）：metrics-generator 的 WAL 持久化默认关闭，可按需开启。

ingester 的持久化参数如下：

metrics-generator 的持久化参数与 ingester 结构一致（metricsGenerator.persistence.*），默认8Gi、ReadWriteOnce。

六、Prometheus 监控集成

6.1 开启原生指标

将metrics.enabled设为true后，Chart 会在容器与服务中暴露 Grafana Tempo 原生的 Prometheus 端口，并为 Service 添加 Prometheus 自动抓取所需的注解。

6.2 前置要求

集成生效需要集群中已有可用的 Prometheus 或 Prometheus Operator 部署。可以安装 Bitnami 的 prometheus Chart 或 kube-prometheus Chart 快速获得。

6.3 与 Prometheus Operator 集成

Chart 支持部署ServiceMonitor对象以便与 Prometheus Operator 集成，只需设置：

metrics.serviceMonitor.enabled=true

注意：如果集群未安装 Prometheus Operator 的 CustomResourceDefinitions，安装会失败并报错：

no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

解决方式是先安装 Bitnami kube-prometheus Chart 以获得必要的 CRD 与 Operator。

从模板看，各组件目录下都有独立的 servicemonitor.yaml 模板，说明每个 Tempo 组件都可被单独监控。

七、核心参数速查表

7.1 Global 参数

7.2 Common 参数

7.3 Tempo 公共参数

7.4 各组件 Deployment 参数（结构一致）

compactor、distributor、ingester、querier、queryFrontend、vulture、metricsGenerator的部署参数结构高度一致，核心差异仅在默认值上：

• 副本数：replicaCount（默认均为1）；
• 探针：livenessProbe/readinessProbe（默认enabled=true，period10s、timeout1s、failureThreshold3）、startupProbe（默认false）；compactor 的 liveness/readiness 探针 initialDelaySeconds 为80s，其余组件为10s；也可通过customLivenessProbe/customReadinessProbe/customStartupProbe完全覆盖默认探针；
• 资源：resourcesPreset（默认nano）、resources（默认{}，生产推荐）；
• 安全上下文：podSecurityContext.fsGroup=1001，containerSecurityContext.runAsUser=1001、runAsGroup=1001、runAsNonRoot=true、privileged=false、readOnlyRootFilesystem=true、allowPrivilegeEscalation=false、capabilities.drop=["ALL"]、seccompProfile.type=RuntimeDefault；
• 调度：podAffinityPreset（""）、podAntiAffinityPreset（soft）、nodeAffinityPreset.*、affinity、nodeSelector、tolerations、topologySpreadConstraints、priorityClassName、schedulerName；
• 更新策略：updateStrategy.type=RollingUpdate；
• 扩展：extraVolumes、extraVolumeMounts、sidecars、initContainers、extraEnvVars、extraEnvVarsCM、extraEnvVarsSecret、command、args；
• 可用性：pdb.create=true（minAvailable与maxUnavailable均空时默认 maxUnavailable=1）；
• 其他：lifecycleHooks、automountServiceAccountToken（默认 false）、hostAliases、podLabels、podAnnotations、enableServiceLinks。

组件特有参数补充：

• queryFrontend：queryFrontend.query.enabled（默认false，仅 Grafana <7.5 的旧版 Jaeger UI 兼容需要）、queryFrontend.query.image.*、queryFrontend.query.configuration、queryFrontend.query.existingConfigmap、queryFrontend.query.containerPorts.grpcJaeger=7777；
• metricsGenerator：metricsGenerator.remoteWrite（remote_write 配置数组）；
• vulture：vulture.image.repository=REPOSITORY_NAME/grafana-tempo-vulture、vulture.containerPorts.http=8080。

7.5 Traffic Exposure（流量暴露）参数

每个组件都有对应的 service 参数块，结构一致：

差异点：distributor/ingester/querier的 service 同时暴露nodePorts.grpc；queryFrontend额外暴露queryFrontend.service.ports.grpcJaeger=7777（供 Jaeger query 集成）以及queryFrontend.service.headless.annotations；compactor的 service 只暴露nodePorts.http。

7.6 网络策略（NetworkPolicy）

每个组件默认创建 NetworkPolicy（XXX.networkPolicy.enabled=true），常用子参数：

7.7 其他参数

ServiceAccount 参数：

Metrics 参数：

VolumePermissions 参数：volumePermissions.enabled（默认false），使用os-shell镜像（默认 tag 为12-debian-12-r50），volumePermissions.containerSecurityContext.runAsUser=0。

Memcached 子 Chart 参数：memcached.enabled=true、memcached.auth.enabled=false、memcached.service.ports.memcached=11211、memcached.resourcesPreset=nano。

八、升级注意事项

Chart 的 README.md 记录了多个破坏性升级要点，升级前务必对照：

• 升级到 5.0.0：grafana-tempo-query改为独立的 gRPC 服务，不再作为 Jaeger 存储插件工作，Jaeger 不再随grafana-tempo-query镜像分发。影响：移除 Jaeger 暴露的端口；tempo-query暴露的 gRPC 端口已加入 Service 与网络策略以支持与 Jaeger 集成；
• 升级到 4.0.0：metrics-generator组件由 Deployment 改为 StatefulSet；
• 升级到 3.8.0：引入镜像校验，可通过global.security.allowInsecureImages=true关闭；
• 升级到 3.0.0：安全默认值变更，包括runAsGroup从0改为1001、readOnlyRootFilesystem=true、resourcesPreset从none调整为测试可用的最小规格（注意resourcesPreset不面向生产）、global.compatibility.openshift.adaptSecurityContext从disabled改为auto。这些变更可能影响自定义或 init 脚本，如受影响请改回旧默认值；
• 升级到 2.0.0：移除search_enabled与metrics_generator_enabled配置参数，视为始终启用；
• 升级到 1.0.0：大量参数重命名，包括端口参数归入containerPorts与ports映射，以及 Memcached 子 Chart 升级到 6.x.x 大版本。

九、故障排查

遇到 Chart 相关常见错误时，可参考 Bitnami 官方的 Helm Chart 故障排查指南（面向通用 Bitnami Chart 问题）。结合本文已覆盖的源码与配置，这里给出几个高频排查切入点：

• ServiceMonitor 报no matches for kind "ServiceMonitor"：确认 Prometheus Operator CRD 已安装（见 6.3 节）；
• 配置未生效：确认tempo.configuration修改后 Pod 已因checksum/config注解变化而滚动更新；
• 持久化问题：确认ingester.persistence.enabled与 StorageClass 配置，必要时启用volumePermissions修正 PV 属主；
• 组件间发现异常：确认 gossip-ring headless 服务存在，且各组件带有tempo-gossip-member: "true"标签（由模板自动添加）。

十、结语

Bitnami 的 grafana-tempo Chart 以组件化方式将 Tempo 的 distributor、ingester、querier、compactor、query-frontend、metrics-generator 与 vulture 完整打包到 Kubernetes，开箱即用且保留了高度的可定制性：从追踪协议开关、memcached 缓存、本地/远程存储、Prometheus 与 ServiceMonitor 监控集成，到细粒度的资源、探针、安全上下文与亲和性控制。无论是快速验证还是生产落地，这份 Chart 的 values.yaml 与 templates 目录都是可直接上手研读的第一手参考资料。

• 云原生
• 容器编排