Grafana Mimir 官方 Helm Chart 深度指南：mimir-distributed 架构、配置与生产化实践

• 时序数据库
• 后端
• 数据存储
• 可观测性
• 云原生

本篇指南以 Grafana Mimir 仓库内operations/helm/charts/mimir-distributed官方 Helm Chart（当前版本6.3.0-weekly.415，对应 Mimirr415-a8aadae14）为核心，系统讲解其在 Kubernetes 上部署 Grafana Mimir 微服务集群的架构组成、values 配置体系、组件级参数、预设规模模板以及升级迁移与版本发布机制。读完本文，你将能够基于该 Chart 完成从快速入门到多可用区高可用生产部署的完整配置实践，并理解底层模板如何将 values 渲染为 Mimir 的配置文件与 K8s 资源。

一、mimir-distributed 图表概览

mimir-distributed是 Grafana Mimir 项目官方维护的 Helm Chart，用于在 Kubernetes 上部署 Grafana Mimir：

apiVersion: v2 version: 6.3.0-weekly.415 appVersion: r415-a8aadae14 description: "Grafana Mimir" kubeVersion: ^1.32.0-0 name: mimir-distributed

关键约束与事实：

• Kubernetes 版本要求：^1.32.0-0，即要求集群版本不低于 1.32（CHANGELOG 中 6.1.0 起将最低支持版本提升到 1.32，反映 Grafana 不再对更老版本做测试）。
• 版本机制：6.3.0-weekly.415属于weekly 周更开发版，按 RELEASE.md 的说明，周更版本格式为x.y.z-weekly.w，仅供测试，helm install时必须加--devel标志 Helm 才会采纳；正式版本形如6.3.0，候选版本形如6.3.0-rc.0。
• 依赖子图表：Chart 依赖三个子 Chart，均通过condition控制是否渲染：

• README 生成机制：仓库内的 README.md 由 README.md.gotmpl 渲染而来，后者通过{{ template "chart.header" . }}、{{ template "chart.requirementsSection" . }}等 Helm 内置 Chart 模板，把 Chart.yaml 的版本、依赖等信息自动拼进 README。因此文章中所见的版本号、依赖表都直接来自 Chart 元数据，每次make doc都会重新生成。

二、微服务架构：Chart 渲染的组件清单

默认 values（values.yaml）会渲染 Mimir 全部核心微服务。每个组件都有独立的enabled开关、副本数、Service、PodDisruptionBudget、探针、安全上下文、持久化等配置块，模板位于 templates 目录下（alertmanager/、distributor/、ingester/、querier/、query-frontend/、query-scheduler/、store-gateway/、compactor/、ruler/、overrides-exporter/、gateway/、kafka/、memcached/等子目录）。

2.1 核心组件与默认副本数

副本数语义需注意：当某组件开启zoneAwareReplication.enabled=true时，replicas表示跨所有可用区的总数，每个 zone 启动ceil(replicas / number_of_zones)个 Pod。例如 ingester 配置replicas: 3且默认 3 个 zone 时，每个 zone 各 1 个 Pod。

2.2 默认启用的 ingest-storage（Kafka）架构

6.x系列默认采用ingest-storage 架构：写入路径通过 Kafka 解耦。values 中kafka.enabled: true（默认内置一个 Kafka 4.1.0 集群用于演示/入门），对应 Mimir 配置中ingest_storage.enabled: true、ingester.push_grpc_method_enabled: false（禁用直推 gRPC，写入全部经由 Kafka）。Kafka topic 默认mimir-ingest，auto_create_topic_enabled: true且默认分区数 100（注释明确说明该值仅供 demo，分区数必须不少于最大 ingester 副本数）。

如果希望回归 2.x/5.x 的经典架构（distributor 直推 ingester，不引入 Kafka），Chart 提供了 classic-architecture.yaml 预设：

kafka: enabled: false mimir: structuredConfig: ingest_storage: enabled: false kafka: address: null topic: null auto_create_topic_default_partitions: null distributor: remote_timeout: null ingester: push_grpc_method_enabled: null

三、快速上手：安装与验证

Chart 默认 values 注释明确说明：默认值足以部署全部微服务，但不适合生产负载。入门部署可直接使用默认值（自带 MinIO 兼容对象存储与 Kafka），流程如下：

# 添加官方 Helm 仓库 helm repo add grafana https://grafana.github.io/helm-charts helm repo update # 周更开发版需要 --devel 才能被选中 helm install mimir grafana/mimir-distributed --devel --version 6.3.0-weekly.415

安装完成后，templates/NOTES.txt 会打印关键访问信息：

• remote-write 写入端点（集群内）：http://<release>-gateway.<namespace>.svc:<http_port>/api/v1/push，对应 OTLP 端点/otlp/v1/metrics与/distributor；
• 查询端点（Grafana 数据源 Prometheus URL）：http://<release>-gateway.<namespace>.svc:<http_port>/prometheus。

即网关（gateway/nginx）是统一流量入口，路径按组件转发：/api/v1/push、/otlp/v1/metrics、/distributor走 distributor；/alertmanager走 alertmanager；/prometheus/config/v1/rules、/prometheus/api/v1/rules、/prometheus/api/v1/alerts走 ruler；其余/prometheus前缀与/api/v1/status/buildinfo走 query-frontend；/api/v1/upload/block/走 compactor。nginx 配置还会强制补全X-Scope-OrgID头（缺失时回落到no_auth_tenant），并拒绝多个X-Scope-OrgID头同时存在（返回 400），这是多租户安全的重要防线，见 gateway 模板。

查看某版本完整默认值，可以用 Helm 直接导出：

helm show values grafana/mimir-distributed --version <version>

若要基于 GitHub 上的源码获取与 chart 版本匹配的 values，仓库会为每个 release 打mimir-distributed-<chart-version>形式的 git tag（见 RELEASE.md），例如mimir-distributed-release-6.2，对应分支上的 values.yaml。由于 values 不向后兼容，务必使用与目标 chart 版本匹配的 values 文件。

四、配置体系：mimir.config / structuredConfig / runtimeConfig

Chart 的核心设计是三层配置叠加，全部围绕 values.yaml 中的mimir字段展开：

4.1 mimir.config：文本模板基线

mimir.config是一段 YAML 字符串，内含 Helm 模板表达式（如{{ .Values.minio.rootUser }}、{{ include "mimir.fullname" . }}），在helm install/upgrade时求值。渲染入口是 templates/_config-render.tpl：

{{- tpl .Values.mimir.config . -}}

求值后通过 templates/_helpers.tpl 中的mimir.calculatedConfig与structuredConfig合并：

{{ tpl (mergeOverwrite (include "mimir.unstructuredConfig" . | fromYaml) .Values.mimir.structuredConfig | toYaml) . }}

即先把mimir.config文本渲染为 YAML，再用structuredConfig做深度合并覆盖——这样既保留了基线，又允许以结构化 YAML 方式精准地增改某些键，无需复制整段模板。

4.2 基线配置中的关键默认项

从 values.yaml 的mimir.config可以提取到一批有代表性的默认参数：

• usage_stats / activity_tracker：installation_mode: helm，启用活动追踪日志/active-query-tracker/activity.log。
• blocks_storage：默认backend: s3；若启用 minio 则指向集群内 MinIO（bucketmimir-tsdb，insecure: true）；可选接入 memcached 的chunks_cache、index_cache、metadata_cache；tsdb.dir: /data/tsdb、head_compaction_interval: 15m、wal_replay_concurrency: 3。
• compactor：compaction_interval: 30m、deletion_delay: 2h、首层压缩等待first_level_compaction_wait_period: 25m，ring 心跳1m、超时4m。
• distributor：remote_timeout: 5s（注释说明写 Kafka 兼容后端可能比直写 ingester 慢，故调大默认值）。
• frontend / frontend_worker：parallelize_shardable_queries: true；启用results-cache时cache_results: true、query_sharding_target_series_per_shard: 2500；frontend_worker 的 gRPC 最大发送消息400MiB。
• ingester：num_tokens: 512、tokens_file_path: /data/tokens、unregister_on_shutdown: false、心跳2m/超时10m；开启 zone-aware 时设置zone_awareness_enabled: true。
• limits：max_total_query_length: 12000h（约 500 天）、max_query_parallelism: 240（15 天 × 16 分片）、max_cache_freshness: 10m（避免缓存不完整结果）。
• memberlist：rejoin_interval: 60s（CHANGELOG 说明这是为了让被瞬断踢出 gossip ring 的成员周期性重连）、compression_enabled: false、join_members指向<release>-gossip-ring的 DNS SRV 地址。
• ruler：alertmanager_url使用dnssrvnoa+http://前缀发现 alertmanager headless 服务；enable_api: true。
• store_gateway：ring 心跳1m/超时10m，wait_stability_min_duration: 1m，zone-aware 时 kvstore 前缀改为multi-zone/。

4.3 配置存储：ConfigMap / Secret / 外部配置

useExternalConfig: false时，chart 自己生成配置对象；templates/mimir-config.yaml 依据configStorageType（默认ConfigMap，可改Secret）生成包含mimir.yamlkey 的对象，内容为mimir.calculatedConfig的求值结果（Secret 模式下做 base64）。相关参数：

• configStorageType：ConfigMap 或 Secret。若想将凭证等敏感信息移出配置对象，官方建议改用 Mimir 配置中的环境变量引用（如${AWS_ACCESS_KEY_ID}），再用global.extraEnvFrom注入 Secret，实现"配置无密文"。
• useExternalConfig：置 true 时 chart 不再生成配置，直接消费名为externalConfigSecretName的现有 Secret/ConfigMap。
• externalConfigVersion：当useExternalConfig=true时，修改该版本号可触发所有服务重启以重新加载配置；内部生成配置时则是配置内容变化自动触发重启（CHANGELOG 6.3.0-weekly 还优化了这一点：checksum/config注解只对配置数据本身做 hash，chart 版本号不再进 Pod labels，避免每次 chart 升级都全量重启 Pod）。
• global.extraEnv/extraEnvFrom：向所有组件注入公共环境变量，是"配置引用环境变量 + Secret 注入"组合的关键一环。

structuredConfig的典型用法（values 注释示例）：

mimir: structuredConfig: common: storage: backend: s3 s3: bucket_name: "${BUCKET_NAME}" endpoint: "${BUCKET_HOST}:${BUCKET_PORT}" access_key_id: "${AWS_ACCESS_KEY_ID}" # 敏感信息用环境变量注入 secret_access_key: "${AWS_SECRET_ACCESS_KEY}" http: insecure_skip_verify: true # S3 证书不受信任时跳过校验

4.4 runtimeConfig：免重启的热加载配置

runtimeConfig（values.yaml）生成一个runtime.yaml，写入/var/mimir/runtime.yaml。其特点是修改后无需重启任何组件即可生效，适用于ingester_limits（单副本强制限额，如max_ingestion_rate、max_series、max_tenants）、distributor_limits（max_inflight_push_requests、max_inflight_push_requests_bytes）以及按租户的overrides（如ingestion_tenant_shard_size、max_global_series_per_user、max_fetched_series_per_query）。

五、组件级配置要点

每个组件块结构高度一致，下面以几个代表性组件展开（完整参数见 values.yaml）。

5.1 副本、资源与持久化

• resources.requests：默认值只是让集群能跑起来的最低配置（如 ingester 请求 100m CPU / 512Mi 内存）。生产请参考small.yaml/large.yaml的资源档位，它们按70% 利用率设计（requests≈70%、limits≈100%），且不设置 CPU limits——values 注释与 RELEASE 文档均引用了 CPU limits 在公有云导致节流问题的业界经验。
• 持久化：有状态组件（ingester、store-gateway、compactor、alertmanager）默认persistentVolume.enabled: true，ingester 的 PV 默认2Gi（values 注释建议务必开启，避免丢指标），storageClass留空则用集群默认 provisioner，设为-表示禁用动态供给。Kubernetes 1.31+ 还支持通过volumeAttributesClassName动态调整卷属性（要求 CSI 驱动支持 ModifyVolume）。
• podManagementPolicy：ingester 用Parallel；store-gateway 为兼容 5.1.0 之前行为默认OrderedReady，注释建议新部署改Parallel（6.0.0 将以此为默认）。
• terminationGracePeriodSeconds：与组件优雅下线相关，例如 ingester 1200s、alertmanager 900s、distributor 100s（需高于 shutdown-delay）。

5.2 zone-aware replication（多可用区）

ingester 与 store-gateway 默认已开启zoneAwareReplication.enabled: true，alertmanager 默认关闭（可通过 values 示例开启）。核心参数（见 values.yaml 与 store-gateway 同构块）：

• topologyKey：设置后生成 pod 反亲和规则，保证不同 zone 的 Pod 不混布在相同拓扑节点上；例如topologyKey: 'kubernetes.io/hostname'。
• zones：zone 列表需整体重定义才能修改（YAML 不支持部分修改列表）。每个 zone 支持nodeSelector（如topology.kubernetes.io/zone: us-central1-a）、extraAffinity、storageClass、noDownscale、downscaleLeader（标注由哪个 StatefulSet 主导缩容，典型为前一 zone）、prepareDownscale（预缩放标签/注解）。
• maxUnavailable/minTimeBetweenZonesDownscale：zone 间滚动时每区允许不可用数量与缩容间隔（ingester 默认50/12h）。
• migration：配合从单 zone 迁移到 zone-aware 的过渡参数（writePath、readPath、scaleDownDefaultZone、excludeDefaultZone、replicas等）。
• autoIngestStorageClientRack（ingester）：启用后自动为每个 zone 的 ingester 设置-ingest-storage.kafka.client-rack为该 zone 名，启用 Kafka rack-aware 消费，降低跨 AZ 流量。

这些 zone 化 StatefulSet 的发布与缩容由依赖的rollout-operator（0.52.0）协同完成。

5.3 KEDA 自动伸缩

kedaAutoscaling为实验性功能，要求集群已安装 KEDA，各组件可独立配置：

distributor: kedaAutoscaling: enabled: false minReplicaCount: 1 maxReplicaCount: 10 targetCPUUtilizationPercentage: 100 targetMemoryUtilizationPercentage: 100 behavior: scaleDown: policies: - periodSeconds: 600 type: Percent value: 10

顶层kedaAutoscaling.prometheusAddress提供 Prometheus 兼容地址（为空时回落到 metamonitoring 的 remote-write 目标，再为空则用 Mimir 集群自身）；querier 还支持基于 query-scheduler 在途请求的querySchedulerInflightRequestsThreshold与预测式伸缩（predictiveScalingEnabled、predictiveScalingPeriod、predictiveScalingLookback，用于应对可预期的周期性查询流量）。

5.4 memcached 缓存族

Chart 提供四类基于 memcached 的缓存组件：chunks-cache（chunk 缓存）、index-cache（索引缓存）、metadata-cache（块元数据缓存）、results-cache（查询结果缓存），默认均关闭，small.yaml/large.yaml中开启并给出副本数（如 large 档 chunks-cache 32 副本、index-cache 10 副本）。核心参数：

• allocatedMemory（MB）：memcached-m内存上限的唯一来源；默认requests.memory = round(1.2 × allocatedMemory) + 100Mi、limits.memory = round(1.5 × allocatedMemory)，为 memcached 留出 OOM 前余量。直接覆盖 resources 不会改变-m，可能造成容器 limit 与实际内存配置不一致。
• maxItemMemory（MB）：最大条目内存，会写进 Mimir 配置（如 index-cache 默认 5MB、results-cache 默认 25MB）。
• connectionLimit、extraExtendedOptions（透传 memcached-o/--extend）、volumeClaimTemplates等。

5.5 Ruler 专用查询路径

ruler.remoteEvaluationDedicatedQueryPath: true时，Chart 额外渲染ruler_querier（2 副本）、ruler_query_frontend（1 副本）、ruler_query_scheduler（2 副本）三个组件，将 ruler 的查询与 API/Grafana 查询路径隔离，并让 ruler 走 remote evaluation 模式（Mimir 配置ruler.query_frontend.address指向专用 frontend）。ruler 默认还带 1GiB 内存 ballast（memBallastSizeBytes，可置 0 关闭），用于降低启动与滚动期间的 GC 频率——注意 ballast 必须小于任何已设置的 GOMEMLIMIT，否则会导致 GC 持续抖动。

六、面向不同规模的预设 values 文件

Chart 仓库根目录提供一组可直接使用的预设 values（均以注释标明适用规模），生产部署强烈建议基于它们调整：

以small.yaml为例，其 ingester 段展示了生产化的反亲和与 zone 配置：

ingester: persistentVolume: size: 50Gi replicas: 3 resources: limits: memory: 12Gi requests: cpu: 3.5 memory: 8Gi topologySpreadConstraints: {} affinity: podAntiAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchExpressions: - key: app.kubernetes.io/component operator: In values: [ingester] topologyKey: "kubernetes.io/hostname" zoneAwareReplication: topologyKey: "kubernetes.io/hostname"

使用方式：helm install mimir grafana/mimir-distributed --devel -f operations/helm/charts/mimir-distributed/small.yaml（或把文件内容作为 values 传给-f）。

七、升级、迁移与弃用项

7.1 升级前必读 CHANGELOG

Chart 的 CHANGELOG.md 记录了全部变更与弃用项列表，其弃用策略是"某项弃用后，从第三个大版本起移除"。README 明确要求升级前务必核对 CHANGELOG 中的破坏性变更。当前已知弃用/移除项（摘录自 CHANGELOG 顶部）：

• GEM gateway Service 上的 8080 端口已弃用（3.1.0起，计划6.0.0移除），需把远程写入、仪表板、自动化中的 8080 替换为 80。
• 顶层nginx配置段并入gateway段（4.0.0弃用，6.0.0已移除），统一为网关代理部署。

7.2 跨大版本迁移

README 给出了三条官方迁移路径（完整步骤在 Grafana 官方 Helm chart 文档站的 migration-guides 下）：

• 从 4.x 升级到 5.0：Migrate the Helm chart from version 4.x to 5.0；
• 从 3.x 的单 zone 部署迁移到 zone-aware replication：Migrate from single zone to zone-aware replication with Helm（zone-aware 配置小节中的migration参数即为此设计，ingester 支持readPath/writePath分阶段切换）；
• 从 2.1 升级到 3.0：Upgrade the Grafana Mimir Helm chart from version 2.1 to 3.0。

7.3 近期值得关注的变更（来自 CHANGELOG 6.x 段）

• 默认 MinIO 镜像替换为pgsty/silo（MinIO 社区版镜像已从公共镜像仓库下架；Silo 是 PGSTY 维护的 MinIO 分支，兼容 S3 API），可通过minio.image/minio.mcImage覆盖。
• memcached 默认镜像更新为1.6.42-alpine/ exporterv0.16.0；缓存容器内存 requests/limits 改为按allocatedMemory推导，与 Jsonnet 的缓冲策略对齐。
• Kafka 内置 broker 设置KAFKA_MESSAGE_MAX_BYTES=16000000（Mimir 单批次最大约 16MB，避免 Kafka 默认 1MB 导致MESSAGE_TOO_LARGE）。
• kafka.clusterId通过CLUSTER_ID环境变量传入（此前使用的KAFKA_CLUSTER_ID被 apache/kafka 镜像忽略），仅在全新安装时生效。
• chart 版本升级不再因helm.sh/chart进入 pod labels 而触发全量滚动。

八、版本发布机制（RELEASE.md）

RELEASE.md 说明了 Chart 的发布节奏与流程：

• 节奏：跟随 Mimir 版本发布，通常在 Mimir 发布后 2 周内；安全更新会单独触发；每周会发布一个基于最新 Mimir build 的周更版（仅供测试，需--devel安装）。
• 版本命名：周更x.y.z-weekly.w、RCx.y.z-rc.w、正式x.y.z；Git tag 形如mimir-distributed-<version>，发布到grafana.github.io/helm-charts仓库。
• 发布流程要点：RC 发布前先准备 CHANGELOG（将main / unreleased条目归入本次版本）→ 创建mimir-distributed-release-x.y分支 → 更新 values 的image.tag与 Chart.yaml 的version/appVersion→make doc重新生成 README → 合并触发 GitHub Action 发布 →helm search repo grafana/mimir-distributed --devel --version <VERSION>验证。
• 从仓库根目录可用./tools/release/notify-changelog-cut.sh operations/helm/charts/mimir-distributed/CHANGELOG.md通知各 open PR 关于 changelog 切割的信息。

九、生产化实践建议

综合 Chart 注释、预设 values 与 CHANGELOG，可提炼以下生产要点：

1. 对象存储：默认入门用 MinIO（minio.enabled: true，数据 5Gi），生产应关闭 MinIO（minio.enabled: false）改用云厂商 S3/GCS，并通过structuredConfig的common.storage或blocks_storage.s3/ruler_storage配置凭证；敏感凭证用${ENV_VAR}引用 +global.extraEnvFrom注入 Secret，而不是写进 ConfigMap。
2. Kafka：生产可关闭内置kafka.enabled改用外部 Kafka；topic 分区数必须不小于最大 ingester 副本数；ingest-storage 模式下 2 个 zone 即可（Kafka 已负责复制），经典架构才需要 3 个 zone（见 ingester zone 注释）。
3. 资源与 QoS：以 small/large 档为起点调整；如需 Guaranteed QoS 用 capped 版本；除非计费需要，否则不建议设置 CPU limits。
4. 持久化：ingester/store-gateway/compactor/alertmanager 务必启用 PV；多可用区场景按 zone 设置storageClass。
5. 可观测性：metaMonitoring段可开启 ServiceMonitor（Prometheus Operator）、Grafana dashboards、PrometheusRule（Mimir 告警与录制规则）；Grafana Agent 已弃用（2025 年底停止支持），官方建议迁移到 Grafana k8s-monitoring / Alloy；KEDA 自动伸缩依赖 metamonitoring 的 Prometheus 地址。
6. 测试辅助：默认渲染的smoke_testJob 与可选的continuous_test（默认关闭，持续读写验证）可用于验证部署；CI 用的 ci/test-oss-values.yaml 展示了如何通过kubeVersionOverride固定 K8s 版本、剥离资源 requests 以便在受限 CI 环境跑通模板渲染。

十、仓库内延伸阅读

• 图表元数据与依赖：Chart.yaml
• 全部可配置项与注释：values.yaml
• 模板渲染逻辑：配置对象 templates/mimir-config.yaml、配置求值 _config-render.tpl、命名/URL 等 helper _helpers.tpl、安装提示 templates/NOTES.txt
• 规模预设：small.yaml、large.yaml、capped-small.yaml、capped-large.yaml、classic-architecture.yaml、ipv6-only.yaml
• 变更与弃用清单：CHANGELOG.md
• 发布流程：RELEASE.md，以及仓库根目录的 RELEASE.md（Mimir 主发布节奏）
• 贡献指南：仓库 docs/internal/contributing 目录下提供了面向 Helm chart 的贡献与发布文档

• 时序数据库
• 后端
• 数据存储
• 可观测性
• 云原生