amr-migration-skill

Azure Managed Redis 迁移技能

此技能可帮助用户从 Azure Cache for Redis（ACR）的 Basic/Standard/Premium 层迁移到 Azure Managed Redis（AMR），包括通过 ARM REST API 自动迁移。

📝 术语说明

用户可能会以多种名称称呼 Azure Cache for Redis：OSS、ACR，或其层级名称（Basic、Standard、Premium）。这些名称都指同一产品。用户询问迁移时，请将这些术语视为同义词。

⚠️ 范围限制：不支持 Enterprise 层

此技能不涵盖 Azure Cache for Redis Enterprise（ACRE）迁移。如果用户询问从 Enterprise 或 Enterprise Flash 层迁移，请说明这些层有不同的迁移路径，并建议联系 Microsoft 支持或查阅官方文档。

支持的源层级：Basic（C0-C6）、Standard（C0-C6）、Premium（P1-P5）

⚠️ AMR 术语：没有“分片”

描述 AMR 时，请避免使用“分片”一词。在 AMR 中，分片由内部管理，不向客户公开，因此这一概念并不适用，使用它会造成困惑。该术语仅适用于 ACR Premium 群集缓存。讨论 AMR 时，请改用性能层级（例如，Balanced、Memory Optimized）和大小（例如，B10、M20）。

---

Agent 指引

⛔ 破坏性操作确认（必需）

通过迁移脚本执行 Migrate 或 Cancel 操作前，Agent 必须：

1. 向用户显示完整的源和目标资源 ID
2. 清楚说明将执行的操作（例如：“这将启动从 ACR 到 AMR 的 DNS 切换迁移”）
3. 运行脚本前，使用 ask_user 工具明确征求用户确认
4. 绝不自动确认或假定用户已同意这些操作

无论用户如何表述请求，都必须遵守此要求。即使用户说“继续并迁移”，Agent 也必须在执行前确认具体资源 ID。

对于 bash 脚本，Agent 运行时始终传入 --yes（因为 Agent 无法与终端提示交互），但必须先通过 ask_user 工具获得用户确认。

🔍 迁移前验证（必需）

执行 Migrate 前，Agent 必须先使用相同的源和目标资源 ID 运行 Validate，并向用户展示结果。如果验证返回错误，不要继续执行 Migrate。如果验证返回警告，请向用户解释，并询问是否要使用 -ForceMigrate $true（PowerShell）或 --force-migrate（bash）继续。

版本检查（仅手动 — 由用户请求触发）

不要自动检查更新。仅当用户明确要求时才进行版本检查（例如，“检查 amr skill 是否有更新”，“amr-migration-skill 有更新版本吗？”）。

收到请求后：

1. 读取此技能根目录中的本地 VERSION 文件。
2. 从以下地址获取远程版本：https://raw.githubusercontent.com/AzureManagedRedis/amr-migration-skill/main/VERSION
3. 如果远程版本较新，请告知用户："有较新版本的 AMR Migration Skill 可用（本地：X，最新：Y）。请从此处更新：https://github.com/AzureManagedRedis/amr-migration-skill"
4. 如果版本一致，请告知用户："您使用的是最新版本（X）。"
5. 如果获取失败，请告知用户检查失败，并建议稍后重试。

检测平台以选择脚本

检查用户的操作系统，选择合适的迁移脚本变体：

• Windows / PowerShell：使用 .ps1 脚本（需要 Azure CLI）
• Linux / macOS / WSL / Bash：使用 .sh 脚本（需要 Azure CLI + jq）

如果无法确定操作系统，优先使用 bash 脚本——它们可跨平台运行。两个脚本变体都使用 Azure CLI（az rest）调用 ARM API。

构造 ARM 资源 ID

用户通常会提供缓存名称、资源组和订阅。按以下方式构造完整的 ARM 资源 ID：

• ACR 源：/subscriptions/<subId>/resourceGroups/<rg>/providers/Microsoft.Cache/Redis/<cacheName>
• AMR 目标：/subscriptions/<subId>/resourceGroups/<rg>/providers/Microsoft.Cache/redisEnterprise/<cacheName>

如果用户只提供缓存名称，请使用 az redis show -n <name> -g <rg> --query id -o tsv 获取完整资源 ID。如果订阅或 RG 也未知，请使用 az redis list --query "[?name=='<name>'].{id:id, rg:resourceGroup}" -o table 查找。

验证 SKU 建议

向用户推荐 AMR SKU 前，请对照 AMR SKU 规格中的有效 SKU 列表进行核查。切勿推荐该文件中未列出的 SKU。如果理想容量介于两个 SKU 规格之间，请推荐较大的规格。

连接变更提醒

讨论迁移时，务必提及以下需要更改应用程序的事项：

• TLS 端口：ACR 使用 6380 → AMR 使用 10000
• 非 TLS：ACR 使用 6379 → AMR 使用 10000（明文模式，在创建时设置；同一时间只能启用一种模式）
• DNS 后缀：.redis.cache.windows.net → <region>.redis.azure.net
• Redis 版本：6 → 7.4

如果用户使用带 DNS 切换的自动化迁移，旧主机名仍可使用，但端口仍需更改。

迁移后建议：建议采用 Microsoft Entra ID 身份验证来替代访问密钥。Entra ID 配置不会自动迁移，必须在新的 AMR 实例上进行设置。

可用资源

重要：查询定价和检索指标时，务必使用提供的脚本。不要自行编写 API 调用或脚本——提供的脚本已正确处理特定层级的计算逻辑（HA、分片、MRPP）和指标聚合。对于指标，除非用户另有指定，否则默认使用 7 天的时间范围。

文档访问

注意：大多数迁移指南已包含在此技能的本地参考文件中。仅当需要查找本地资料未涵盖的信息（例如最新发行说明、区域可用性或新功能）时，才使用 MCP 服务。

使用 Microsoft Learn MCP 服务获取最新文档：

• MCP 终结点：https://learn.microsoft.com/api/mcp
• 设置指南：设置说明（GitHub Copilot、Claude Desktop）请参阅 MCP 服务配置
• 关键文档路径：
  • /azure/redis/ - Azure Managed Redis 文档中心
  • /azure/redis/overview - AMR 概览汇总、关键场景和层级选择起点
  • /azure/redis/architecture - AMR 架构、集群模型和策略指南
  • /azure/redis/migrate/migrate-overview - 迁移中心，按了解差异、探索选项和规划执行组织

Azure CLI 命令参考

请参阅 Azure CLI 命令，了解实用的 az redis 示例，以便：

• 列出订阅或资源组中的 ACR 缓存
• 提取缓存详情（区域、SKU、分片数、副本数）
• 检查持久性和异地复制设置

SKU 映射参考

请参阅 SKU 映射指南，了解指南、ACR → AMR 映射表、选择标准和决策矩阵。有关 AMR SKU 定义（M、B、X、Flash 系列），请参阅 AMR SKU 规格。

动态定价查询

确定候选 SKU 后，获取实时定价和月度成本计算：

# Windows PowerShell
.\scripts\get_redis_price.ps1 -SKU M10 -Region westus2
.\scripts\get_redis_price.ps1 -SKU M10 -Region westus2 -NoHA
.\scripts\get_redis_price.ps1 -SKU C3 -Region westus2 -Tier Standard
.\scripts\get_redis_price.ps1 -SKU P2 -Region westus2 -Shards 3 -Replicas 2

# Linux/Mac bash
./scripts/get_redis_price.sh M10 westus2
./scripts/get_redis_price.sh P2 westus2 --shards 3

脚本选项：

• -NoHA / --no-ha - 非 HA 部署（仅 AMR，适用于开发/测试，可节省 50%）
• -Shards N / --shards N - 分片数量（ACR Premium 集群）
• -Replicas N / --replicas N - 每个主节点的副本数（ACR Premium MRPP，默认值：1）
• -Currency X / --currency X - 货币代码（默认值：USD）

支持的 SKU：

• ACR：C0-C6（Basic/Standard - 必须指定层级）、P1-P5（Premium）
• AMR：M10-M2000、B0-B1000、X3-X700、A250-A4500

资源：

• 定价层级规则 - HA、集群和 MRPP 的计算逻辑
• Azure 定价计算器 - 官方报价

功能比较

请参阅功能比较，了解 ACR（Basic/Standard/Premium）与 AMR 功能的详细比较。

退役常见问题

请参阅退役常见问题，了解退役日期、时间线和常见迁移问题。

与此技能相关（ACR Basic/Standard/Premium）：

• 2026 年 4 月 1 日：禁止新客户创建
• 2026 年 10 月 1 日：禁止现有客户创建
• 2028 年 9 月 30 日：退役日期（实例将于 2028 年 10 月 1 日禁用）

此技能未涵盖：

• Enterprise/Enterprise Flash 退役（2027 年 3 月 31 日）— 请联系 Microsoft 支持

迁移概述

请参阅迁移概述，了解详细的迁移指南，包括：

• 迁移策略（新缓存、RDB 导出/导入、双写、RIOT）
• 连接字符串变更
• 集群策略和网络隔离注意事项

基础设施即代码（IaC）模板迁移

如需将 ACR 模板（ARM、Bicep、Terraform）转换为 AMR 格式，请使用以下参考文档：

• ACR 模板解析指南 — 如何读取并从 ACR 模板中提取配置
• AMR 模板结构指南 — AMR 模板的转换规则、属性映射和输出结构
• 示例模板 — 按格式整理的转换前后模板对：
  • arm/ — 6 个 ARM JSON 场景（basic、premium non-clustered、clustered、VNet、persistence、all-features）
  • arm-parameterized/ — 4 个带独立参数文件的 ARM JSON 场景
  • bicep/ — 2 个 Bicep 场景（basic、premium clustered）
  • terraform/ — 2 个 Terraform 场景（basic、premium clustered）

工作流选择

根据用户的意图选择正确的工作流。 两种工作流相互独立 — 不要混合其中的步骤。

用户意图	线索短语	工作流
将运行中的缓存迁移到 AMR	"migrate cache", "move to AMR", "select SKU", "assess metrics", "migration strategy", "switch traffic"	迁移工作流（步骤 1-4）
将 IaC 模板转换为 AMR 格式	"convert template", "Bicep migration", "ARM to AMR", "Terraform", "IaC", "template transformation", "region buildout"	IaC 迁移工作流（步骤 1-8）
比较功能或回答一般问题	"compare ACR vs AMR", "feature compatibility", "retirement date", "best practices"	直接使用参考文档回答 — 无需工作流

意图不明确的请求

如果用户的意图不明确（例如，“帮我迁移到 AMR”可能有多种含义），请询问：

“您是想迁移运行中的缓存（数据迁移、SKU 选择、流量切换），还是想将基础设施即代码模板（Bicep/ARM/Terraform）转换为 AMR 格式？还是两者都需要？”

两种工作流

如果用户两者都需要（例如，“迁移所有内容，包括我们的 IaC”）：

1. 先运行迁移工作流——这将确定目标 AMR SKU，并根据指标验证规格
2. 然后运行 IaC 迁移工作流——将步骤 1 中选定的 SKU 用作目标

---

迁移工作流

步骤 1：评估当前缓存

从现有 ACR 缓存中收集指标，为 SKU 选择提供依据：

# Windows PowerShell
.\scripts\get_acr_metrics.ps1 -SubscriptionId <id> -ResourceGroup <rg> -CacheName <name>
.\scripts\get_acr_metrics.ps1 -SubscriptionId <id> -ResourceGroup <rg> -CacheName <name> -Days 7

# Linux/Mac bash
./scripts/get_acr_metrics.sh <subscriptionId> <resourceGroup> <cacheName>
./scripts/get_acr_metrics.sh <subscriptionId> <resourceGroup> <cacheName> 7

另请获取实际内存预留量，以确定真正可用的容量（SKU 映射表中的默认值假设约为 20%）：

az redis show -n <cache-name> -g <resource-group> -o json \
  --query "{maxfragmentationmemoryReserved: redisConfiguration.maxfragmentationmemoryReserved, maxmemoryReserved: redisConfiguration.maxmemoryReserved}"

两个值的单位均为 MB。实际可用容量 = SKU 容量 − (maxmemoryReserved + maxfragmentationmemoryReserved)。请以此为规格评估的真实依据。

要求：已登录 Azure CLI（az login）

备用方案：如果脚本运行失败（例如，租户已锁定、权限不足或无法访问 CLI），请指导用户在其缓存的 Azure 门户 监视 → 指标页中手动获取相同指标。

获取的指标（每项均包括峰值、P95 和平均值）：

• 已用内存 RSS（字节和 GB）
• 服务器负载（%）
• 已连接客户端数
• 网络带宽——缓存读取和缓存写入（字节/秒）

集群缓存：对于包含多个分片的 Premium 缓存，脚本会自动检测分片数并汇总所有分片的指标。内存和带宽会求和（总容量），而服务器负载和已连接客户端数则报告每个分片的最大值（瓶颈值）。如果启用了分片汇总，输出标题会注明。

使用这些值来：

1. 确定目标 AMR SKU 的规格（可用内存 ≥ 峰值已用内存——采用驱逐策略时无需额外缓冲）
2. 选择层级（服务器负载高且内存使用低 → 计算优化型 X 系列）
3. 验证连接数限制是否足够
4. 使用 P95 值区分持续负载和偶发峰值

可用区固定检查：另请检查源缓存是否使用了可用区固定：

az redis show -n <cache-name> -g <resource-group> -o json \
  --query "{zones: zones, zonalAllocationPolicy: properties.zonalAllocationPolicy}"

如果设置了 zones，且 zonalAllocationPolicy 为 UserDefined，则该缓存为可用区固定——部署在客户选择的特定可用区中。请提醒用户：AMR 不支持可用区固定。启用高可用性后，AMR 会自动跨区域内所有可用区实现可用区冗余，但无法固定到特定可用区。如果用户采用可用区固定是为了与其他资源共置（例如，将 VM 部署在同一可用区以降低延迟），则应注意 AMR 无法延续这一保证。

步骤 2：选择目标 AMR SKU

1. 参阅 SKU 映射指南
2. 使用步骤 1 中的指标验证规格
3. 获取候选 SKU 的定价：

   .\scripts\get_redis_price.ps1 -SKU M20 -Region westus2
   .\scripts\get_redis_price.ps1 -SKU B20 -Region westus2
   

步骤 3：规划迁移

1. 确定迁移策略（双写、快照/还原等）
2. 集群策略：根据源缓存类型和目标 AMR 大小进行选择。请参阅迁移概述获取指导，或参阅 AMR 模板结构 §6查看完整的决策矩阵。
3. 网络隔离：使用 VNet 注入的 ACR 缓存必须改用 AMR 上的 Private Link，因为 AMR 不支持 VNet 注入。请确保在切换前配置好专用终结点。
4. 规划可能的停机时间或数据同步要求
5. 更新应用程序连接字符串和配置

步骤 4：执行迁移

1. 创建目标 AMR 缓存
2. 使用适当的方法迁移数据
3. 验证数据完整性
4. 将应用程序流量切换到新缓存

---

IaC 迁移工作流

如需查看完整的 8 步工作流，请参阅 IaC 迁移工作流。

使用 AI 驱动的转换方式，将 ACR 模板（ARM JSON、Bicep、Terraform）转换为 AMR 格式，并使用参考文档提供依据。包括 SKU 映射、定价比较、功能差距分析、客户确认关卡和模板生成。脚本仅用于查询价格。

---

自动迁移（ARM REST API）

Azure 提供从 ACR 迁移到 AMR 的自动迁移路径，通过 ARM REST API 自动处理 DNS 切换，因此使用旧 OSS 终结点的客户端在迁移后仍可继续工作。

重要：此功能目前处于公共预览版。在正式发布之前，生产工作负载请使用手动迁移策略（上文的步骤 1–4）。

要点：

• 支持：所有 Basic/Standard/Premium SKU——VNet 注入或异地复制缓存除外。Private Link 和群集缓存可以迁移，但不符合数据迁移条件
• 源和目标必须位于同一区域和订阅
• 迁移内容：访问密钥、OSS 主机终结点（DNS 切换）、OSS 端口、缓存数据（如果请求）。不会迁移 Entra ID、持久性配置或托管标识
• 工作流：验证 → 迁移 → 状态 → 取消（回滚）
• 也可通过启用了功能标志的 Azure 门户使用

脚本：

• PowerShell：scripts/Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1（需要 Azure CLI）
• Bash：scripts/azure-redis-migration-arm-rest-api-utility.sh（需要 Azure CLI + jq）

📖 如需了解完整工作流、先决条件、脚本参数和故障排除，请阅读自动迁移参考。 如需了解 ARM API 内部机制，请参阅迁移脚本参考。 如需查看验证错误代码，请参阅验证错误和警告。

常见问题

Azure Cache for Redis（ACR）与 Azure Managed Redis（AMR）有什么区别？

如需查看完整对照表，请参阅功能比较。主要区别包括：

• AMR 提供 Redis Stack 功能（JSON、Search、Time Series、Bloom filters）
• AMR 针对不同工作负载优化了不同的 SKU 层级
• AMR 提供更出色的性能和可扩展性选项

如何选择合适的 AMR SKU？

请参阅 SKU 映射指南，并考虑以下因素：

• 当前内存用量
• 计算压力（服务器负载 %）
• 功能需求（群集、异地复制、Redis 模块）
• 预算限制

AMR 不支持哪些功能？

请查看功能比较，了解当前的功能对照表。使用 MCP 服务获取最新文档，以权威信息为准。

企业层级迁移有哪些注意事项？

此技能不涵盖企业层级迁移。 如果有人询问 ACRE（Azure Cache for Redis Enterprise）迁移，请告知用户，企业层级有不同的注意事项，应咨询 Microsoft 支持或查阅官方文档。

高效迁移提示

1. 充分测试：始终先在非生产环境中测试
2. 监控性能：比较迁移前后的基准指标
3. 制定回滚计划：准备回滚策略，以应对可能出现的问题
4. 更新客户端库：确保 Redis 客户端库支持 AMR 功能
5. 检查安全设置：更新防火墙规则、专用终结点和身份验证