Grafana Mimir 从 Cortex 迁移指南：全面解析与实践步骤

Grafana Mimir 从 Cortex 迁移指南：全面解析与实践步骤

mimir Grafana Mimir provides horizontally scalable, highly available, multi-tenant, long-term storage for Prometheus. 项目地址: https://gitcode.com/gh_mirrors/mimir/mimir

前言

作为 Grafana Mimir 的技术专家，我将为您详细讲解如何从 Cortex 迁移到 Grafana Mimir 的完整流程。Grafana Mimir 是一个水平可扩展、多租户的时间序列数据库，相比 Cortex 在部署和运维方面做了大量优化，使系统更易于管理和维护。

迁移前的准备工作

在开始迁移前，请确保满足以下条件：

1. 版本要求：

   • 当前运行的必须是 Cortex 1.10.X 或 1.11.X 版本
   • 如果使用更旧版本，请先升级到 Cortex 1.11.1

2. 规则和仪表板备份：

   • 确保已安装 Cortex 的告警规则、记录规则和仪表板
   • 建议使用监控混合(mixin)方式安装这些规则到 Prometheus 或 Cortex
   • 仪表板需要导入到 Grafana 中

3. 工具准备：

   • 下载并安装 mimirtool 工具，这是迁移过程中的关键工具

主要变更点解析

1. 默认端口变更

• Cortex：默认监听 80 端口
• Grafana Mimir：默认监听 8080 端口
• 解决方案：如需保持 80 端口，需设置 -server.http-listen-port=80

2. 租户ID默认值变更

• Cortex：当 -auth.enabled=false 时使用 fake 作为默认租户ID
• Grafana Mimir：当 -auth.multitenancy=false 时使用 anonymous 作为默认租户ID
• 解决方案：设置 -auth.no-auth-tenant=fake 以保持与 Cortex 一致

3. HTTP 端点变更

Grafana Mimir 移除了 Cortex 中已弃用的旧版 HTTP 前缀，主要变更包括：

查询端点变更

| 旧版端点 | 新版端点 | |---------|---------| | /<legacy-http-prefix>/api/v1/query | <prometheus-http-prefix>/api/v1/query | | /<legacy-http-prefix>/api/v1/query_range | <prometheus-http-prefix>/api/v1/query_range |

分发器端点变更

| 旧版端点 | 新版端点 | |---------|---------| | /<legacy-http-prefix>/push | /api/v1/push | | /all_user_stats | /distributor/all_user_stats |

规则管理器端点变更

| 旧版端点 | 新版端点 | |---------|---------| | /<legacy-http-prefix>/api/v1/rules | <prometheus-http-prefix>/api/v1/rules | | /ruler_ring | /ruler/ring |

使用 mimirtool 进行配置转换

mimirtool 是迁移过程中的核心工具，它可以自动将 Cortex 配置转换为 Mimir 配置。

安装 mimirtool

curl -fLo mimirtool https://<下载地址>/mimirtool-linux-amd64
chmod +x mimirtool

配置转换命令

基本转换命令：

./mimirtool config convert --output=./mimir-config.yaml ./cortex-config.yaml

如需将显式设置的 Cortex 默认值更新为 Mimir 默认值，添加 --update-defaults 标志：

./mimirtool config convert --update-defaults --output=./mimir-config.yaml ./cortex-config.yaml

Jsonnet 迁移详细步骤

对于使用 Jsonnet 部署的环境，迁移过程更为系统化：

1. 更新库依赖

jb install <mimir-jsonnet库地址>/operations/mimir@main
jb install <mimir-jsonnet库地址>/operations/mimir-mixin@main

2. 更新 Jsonnet 导入

将原来的 Cortex 导入替换为：

import '<mimir-jsonnet库地址>/operations/mimir/mimir.libsonnet'

3. 配置项前缀变更

将所有 cortex_ 前缀的配置项改为无前缀形式，例如：

• cortex_compactor_disk_data_size → compactor_disk_data_size

4. 端口配置

如需保持 80 端口，需显式设置：

{
  _config+: {
    server_http_port: 80,
  },
}

5. 组件参数更新

使用 mimirtool 为每个组件更新配置参数，提取 Jsonnet 中的标志：

# 示例提取命令
./mimirtool config convert --source-format=jsonnet --output=mimir-flags.jsonnet cortex-flags.jsonnet

迁移后验证

完成迁移后，建议通过以下方式验证集群运行状态：

1. 使用 Grafana Mimir 提供的监控混合仪表板检查系统状态
2. 验证所有数据查询功能正常
3. 检查告警规则是否正常触发
4. 确认数据写入和读取延迟在预期范围内

常见问题与解决方案

1. 端口冲突问题：

   • 现象：服务无法启动，报端口占用错误
   • 解决：检查并修改 server_http_port 配置

2. 租户ID不匹配：

   • 现象：查询返回租户不存在的错误
   • 解决：确认 -auth.no-auth-tenant 设置正确

3. 端点404错误：

   • 现象：API调用返回404
   • 解决：更新客户端调用使用新的端点路径

最佳实践建议

1. 分阶段迁移：

   • 先在测试环境验证迁移过程
   • 生产环境采用蓝绿部署方式逐步切换

2. 监控配置：

   • 迁移前后对比关键指标
   • 设置迁移专用告警规则

3. 回滚方案：

   • 准备完整的回滚方案和检查清单
   • 确保旧版Cortex配置和二进制文件备份完整

通过遵循本指南，您应该能够顺利完成从 Cortex 到 Grafana Mimir 的迁移。如果在迁移过程中遇到任何问题，建议参考 Grafana Mimir 的详细文档或寻求社区支持。

mimir Grafana Mimir provides horizontally scalable, highly available, multi-tenant, long-term storage for Prometheus. 项目地址: https://gitcode.com/gh_mirrors/mimir/mimir