Grafana Tempo 中 metrics-generator 使用 Azure Blob 存储的 Helm 配置指南环境变量展开与密钥注入实践【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempoGrafana Tempo 的 metrics-generator 从 Kafka 消费 trace 数据并通过 Prometheus remote write 协议将派生指标写入指标后端。当它以 Helm 方式如tempo-distributed部署且需要访问 Azure Blob 存储时必须把存储账号访问密钥通过config.expand-envtrue环境变量展开机制注入。本文基于仓库中的共享文档 azure-metrics-generator.md 及其在 Azure 托管存储配置 中的完整上下文深入讲解这一配置的语法、原理、适用场景与排错要点。为什么 metrics-generator 需要访问 Azure Blob 存储先厘清 metrics-generator 在 Tempo 中的定位。根据 modules/generator/AGENTS.md 的架构说明在 Tempo 3.0 微服务模式下distributor 将 span 写入 Kafkametrics-generator 通过 Kafka consumer 消费这些 trace 数据消费到的 span 会进入各处理流程processor聚合生成指标并经由 Prometheus remote write 协议发送到指标存储如 Prometheus、Mimir聚合过程中涉及注册表registry与 WAL 存储见 modules/generator/storage/config.go 中的storage.path、remote_write等配置。因此“从 Kafka 读取、向 remote write 写出”是 metrics-generator 的常态路径。那么共享文档为何专门要求“如果 metrics-generator 需要访问 Azure blob storage就把它列入 env var 展开配置”从仓库源码可以推断在需要将派生指标、聚合状态或中间数据落到 Azure Blob 存储的场景例如配合 Azure 作为 Tempo 的 trace 后端或指标处理链路依赖 Azure 存储凭证时metrics-generator 进程内必须持有STORAGE_ACCOUNT_ACCESS_KEY这个密钥。由于 Kubernetes 中密钥通常以 Secret 形式保存而非直接写入配置或明文环境变量因此需要通过extraEnvsecretKeyRef从 Secret 取值再配合config.expand-envtrue让配置中的${STORAGE_ACCOUNT_ACCESS_KEY}占位符被真实值替换。核心配置示例共享文档原文以下是共享文档 azure-metrics-generator.md 给出的完整示例适用于 Helm charts如tempo-distributedgenerator: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: TEMPO-TRACES-STG-KEY key: TEMPO-TRACES-KEY使用说明将generator.extraArgs中加入-config.expand-envtrue开启 Tempo 配置的环境变量展开能力在generator.extraEnv中通过secretKeyRef将 Kubernetes Secret 中的密钥注入为环境变量把所有大写占位符STORAGE_ACCOUNT_ACCESS_KEY、TEMPO-TRACES-STG-KEY、TEMPO-TRACES-KEY替换为你 Helm 部署中的实际值环境变量名、Secret 名称与 Secret 中的 key。需要特别提醒环境变量名建议直接使用STORAGE_ACCOUNT_ACCESS_KEY这样既与 Azure 托管存储配置 中的storage_account_key: ${STORAGE_ACCOUNT_ACCESS_KEY}占位符一一对应也便于后续在多组件间复用同一密钥。环境变量展开config.expand-env的原理与作用-config.expand-envtrue是理解该配置的关键开关。Tempo 基于 dskit 的配置加载体系在解析 YAML 配置时会对config.expand-env标志做出响应当其为true时配置文件中形如${ENV_VAR}的占位符会被展开为对应环境变量的值。该机制的价值在于把敏感信息密钥、密码从配置文件与 Helm Values 中剥离。你可以在配置或 Values 中安全地写storage_account_key: ${STORAGE_ACCOUNT_ACCESS_KEY}而真正的密钥值由 Kubernetes Secret 提供并通过extraEnv注入进程环境。这样配置文件可以入库、可评审密钥则只存在于集群 Secret 中。在 Azure 托管存储配置 的单体monolithic模式示例中可以看到同样的用法tempo: storage: trace: backend: azure azure: container_name: container-name storage_account_name: storage-account-name storage_account_key: ${STORAGE_ACCOUNT_ACCESS_KEY} extraArgs: config.expand-env: true extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: secret-name key: STORAGE_ACCOUNT_ACCESS_KEY注意单体模式下extraArgs的写法是config.expand-env: trueHelm Values 映射为启动参数而共享文档中分布式模式的写法是- -config.expand-envtrue直接追加命令行参数列表两者殊途同归。共享文档在 Tempo 文档体系中的位置该共享文档shared content被多处文档引用是典型的“一次编写、多处引用”模式。根据文件头部的注释azure-metrics-generator.md它会被包含进以下位置/tempo/docs/sources/tempo/configuration/hosted-storage/azure.md/tempo/docs/sources/tempo/metrics-from-traces/metrics-queries/configure-traceql-metrics.md/helm-charts/tempo-distributed/get-started-helm-charts/_index.md例如在 Azure 托管存储配置 中通过 Hugo shortcode{{ docs/shared sourcetempo lookupazure-metrics-generator.md versionTEMPO_VERSION }}直接嵌入。这意味着该配置不仅是 metrics-generator 专项话题也是 Tempo 使用 Azure 托管存储时的通用前置条件文档维护者要求链接使用全限定路径如/docs/grafana/而非../grafana/以保证在任何引用位置都不会失效。与完整 Azure 存储配置的组合使用共享文档中的generator片段通常不是孤立存在的而是与完整的分布式模式 Azure 配置组合。完整的分布式模式配置见 Azure 托管存储配置中trace 存储配置位于 Values 根部的storage对象且extraArgs/extraEnv需要同时应用于以下服务distributorblockBuilderliveStorequerierqueryFrontendbackendSchedulerbackendWorker对每个服务都需要重复同一组密钥注入配置例如querier: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key如果你还需要在generator之外让 trace 链路也使用 Azure 后端可以合并为storage: trace: backend: azure azure: container_name: tempo-traces storage_account_name: stgappgeneraluks storage_account_key: ${STORAGE_ACCOUNT_ACCESS_KEY} generator: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key源码级佐证Azure 凭证如何被消费为了确认STORAGE_ACCOUNT_ACCESS_KEY的最终去向可以查看 Azure 后端的实现tempodb/backend/azure/config.go 定义了 Azure 配置结构体其中StorageAccountKey对应 YAML 键storage_account_key同时支持use_managed_identity、use_federated_token、user_assigned_id等认证方式tempodb/backend/azure/azure_helpers.go 中的getContainerClient根据配置选择认证方式默认走azblob.NewSharedKeyCredential(accountName, getStorageAccountKey(cfg))共享密钥认证这正是共享文档所讨论的场景tempodb/backend/azure/azure_helpers.go 展示了账号名的回退逻辑storage_account_name未配置时回退到环境变量AZURE_STORAGE_ACCOUNT。也就是说${STORAGE_ACCOUNT_ACCESS_KEY}在配置展开后被解析进storage_account_key字段最终作为 SharedKeyCredential 的密钥部分用于签名 Azure Blob 请求。如果环境变量没有被正确注入storage_account_key会保留字面量${STORAGE_ACCOUNT_ACCESS_KEY}或为空导致请求鉴权失败。三种认证方式的取舍从 azure_helpers.go 的switch逻辑可以看到 Tempo 支持的三种认证路径认证方式配置开关说明共享密钥Shared Key默认不设置任何开关使用storage_account_key即共享文档中的STORAGE_ACCOUNT_ACCESS_KEY场景托管身份Managed Identityuse_managed_identity: true可选user_assigned_id系统/用户分配身份无需在配置中保存密钥Azure Workload Identityuse_federated_token: true基于联邦令牌需要集群侧配置 Service Account 标签与注解共享密钥方式最简单但需要像共享文档那样通过 Kubernetes Secret 保护密钥如果对密钥安全要求更高可以改用托管身份或 Workload Identity此时STORAGE_ACCOUNT_ACCESS_KEY便不再需要。运维排错与补充配置确认环境变量已生效如果 metrics-generator 报出 Azure 鉴权或连接错误可依次排查确认generator.extraArgs中存在-config.expand-envtrue否则${STORAGE_ACCOUNT_ACCESS_KEY}不会被替换确认secretKeyRef中的 Secret 名称与 key 真实存在且与generator.extraEnv中的name一致进入 generator Pod 执行env | grep STORAGE_ACCOUNT_ACCESS_KEY验证环境变量是否注入在配置中确认storage_account_name、container_name与实际 Azure 资源一致账号名也可通过环境变量AZURE_STORAGE_ACCOUNT提供见 azure_helpers.go。Azure 后端其他实用参数结合 Azure 托管存储配置 与 config.go可同时配置以下参数container_name/prefix自定义容器名与嵌套对象前缀便于在共享容器中组织数据endpoint_suffix默认blob.core.windows.net可指向区域云或本地 Azurite 模拟器hedge_requests_at/hedge_requests_up_to对冲请求参数用于降低长尾延迟默认HedgeRequestsUpTo 2max_buffers并发上传数默认 4Azurite 本地开发当endpoint_suffix不以blob.开头时Tempo 会自动切换到 Azurite 的 URL 风格见 azure_helpers.go。blocklist 轮询参数在 Azure 上运行 Tempo 时若遇到 blocklist 轮询异常如 DNS 抖动导致的超时可参考 Azure 托管存储配置 设置storage: trace: blocklist_poll_tenant_index_builders: 1 blocklist_poll_jitter_ms: 500总结本文围绕共享文档 azure-metrics-generator.md 的核心配置展开核心要点如下开启环境变量展开在generator.extraArgs中加入-config.expand-envtrue使配置中的${STORAGE_ACCOUNT_ACCESS_KEY}占位符得以展开安全注入密钥通过generator.extraEnvsecretKeyRef从 Kubernetes Secret 读取密钥避免明文出现在配置或 Helm Values 中替换占位符将STORAGE_ACCOUNT_ACCESS_KEY、TEMPO-TRACES-STG-KEY、TEMPO-TRACES-KEY替换为实际的环境变量名、Secret 名称与 key理解认证路径共享密钥默认、托管身份、Workload Identity 三种方式对应 azure_helpers.go 中的不同分支密钥注入只在共享密钥场景下必需注意共享文档的多处引用该配置同样适用于 TraceQL 指标配置与 Helm chart 快速开始文档是 Tempo × Azure 部署的通用前置步骤。按照上述步骤配置后你的 Tempo 分布式部署即可让 metrics-generator 在 Azure Blob 存储凭证可用的情况下正常运行同时保证密钥只存在于集群 Secret 之中。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考