Amr Migration Skill

Azure Managed Redis Migration Skill

This skill assists users in migrating from Azure Cache for Redis (ACR) Basic/Standard/Premium tiers to Azure Managed Redis (AMR), including automated migration via ARM REST APIs.

📝 Terminology Note

Users may refer to Azure Cache for Redis by several names: OSS, ACR, or by tier name (Basic, Standard, Premium). These all refer to the same product. Treat these terms interchangeably when users ask about migration.

⚠️ Scope Limitation: Enterprise Tier NOT Supported

This skill does not cover Azure Cache for Redis Enterprise (ACRE) migrations. If users ask about migrating from Enterprise or Enterprise Flash tiers, explain that those have different migration paths and suggest contacting Microsoft support or consulting the official documentation.

Supported source tiers: Basic (C0-C6), Standard (C0-C6), Premium (P1-P5)

⚠️ AMR Terminology: No "Shards"

Avoid using the term "shards" when describing AMR. In AMR, sharding is managed internally and not exposed to customers, so the concept doesn't apply and would be confusing. The term only applies to ACR Premium clustered caches. When discussing AMR, refer to the performance tier (e.g., Balanced, Memory Optimized) and size (e.g., B10, M20) instead.

---

Agent Guidance

⛔ Destructive Operation Confirmation (Mandatory)

Before executing Migrate or Cancel actions via the migration scripts, the agent must:

1. Display the full source and target resource IDs to the user
2. Clearly state the action being performed (e.g., "This will initiate a DNS switch migration from ACR to AMR")
3. Ask for explicit user confirmation using the ask_user tool before running the script
4. Never auto-confirm or assume consent for these operations

This applies regardless of how the user phrased their request. Even if the user says "go ahead and migrate", the agent must confirm the specific resource IDs before executing.

For the bash script, always pass --yes when the agent runs it (since the agent cannot interact with the terminal prompt), but only after obtaining user confirmation through the ask_user tool first.

🔍 Validate-Before-Migrate (Mandatory)

Before executing Migrate, the agent must first run Validate with the same source and target resource IDs and present the results to the user. Do not proceed to Migrate if validation returns errors. If validation returns warnings, explain them and ask the user whether to proceed with -ForceMigrate $true (PowerShell) or --force-migrate (bash).

Version Check (manual only — triggered by user request)

Do not check for updates automatically. Only perform a version check when the user explicitly asks (e.g., "check for updates for the amr skill", "is there a newer version of amr-migration-skill?").

When requested:

1. Read the local VERSION file in this skill's root directory.
2. Fetch the remote version from: https://raw.githubusercontent.com/AzureManagedRedis/amr-migration-skill/main/VERSION
3. If the remote version is newer, tell the user: "A newer version of the AMR Migration Skill is available (local: X, latest: Y). Update from: https://github.com/AzureManagedRedis/amr-migration-skill"
4. If versions match, tell the user: "You're on the latest version (X)."
5. If the fetch fails, tell the user the check failed and suggest trying again later.

Detecting Platform for Script Selection

Check the user's OS to choose the right migration script variant:

• Windows / PowerShell: Use .ps1 scripts (requires Azure CLI)
• Linux / macOS / WSL / Bash: Use .sh scripts (requires Azure CLI + jq)

If the OS is unclear, prefer the bash scripts — they work cross-platform. Both script variants use Azure CLI (az rest) for ARM API calls.

Constructing ARM Resource IDs

Users will typically provide a cache name, resource group, and subscription. Construct the full ARM resource IDs as follows:

• ACR source: /subscriptions//resourceGroups//providers/Microsoft.Cache/Redis/
• AMR target: /subscriptions//resourceGroups//providers/Microsoft.Cache/redisEnterprise/

If the user only provides a cache name, use az redis show -n -g --query id -o tsv to retrieve the full resource ID. If the subscription or RG is also unknown, use az redis list --query "[?name==''].{id:id, rg:resourceGroup}" -o table to find it.

Validating SKU Recommendations

Before recommending an AMR SKU to the user, cross-check it against the valid SKU list in [AMR SKU Specs](references/amr-sku-specs.md). Never recommend a SKU that doesn't appear in that file. If the ideal capacity falls between two SKU sizes, recommend the next size up.

Connection Changes Reminder

Always mention these when discussing migration — they require application changes:

• TLS port: ACR uses 6380 → AMR uses 10000
• Non-TLS: ACR 6379 → AMR uses 10000 (Plaintext mode, set at creation; only one mode active at a time)
• DNS suffix: .redis.cache.windows.net → .redis.azure.net
• Redis version: 6 → 7.4

If the user is using the automated migration with DNS switching, the old hostname continues to work, but the port change still applies.

Post-migration recommendation: Suggest adopting Microsoft Entra ID authentication as a replacement for access keys. Entra ID configurations are not migrated automatically and must be set up on the new AMR instance.

Available Resources

> Important: Always use the provided scripts for pricing lookups and metrics retrieval. Do not craft custom API calls or scripts — the provided ones already handle tier-specific calculation logic (HA, shards, MRPP) and metric aggregation correctly. For metrics, use a default time range of 7 days unless the user specifies otherwise.

Documentation Access

> Note: Most migration guidance is already available in this skill's local reference files. Only use the MCP server to look up information not covered locally (e.g., latest release notes, region availability, or new features).

Use the Microsoft Learn MCP server to fetch up-to-date documentation:

• MCP Endpoint: https://learn.microsoft.com/api/mcp
• Setup Guide: See [MCP Server Configuration](references/mcp-server-config.md) for setup instructions (GitHub Copilot, Claude Desktop)
• Key documentation paths:
• /azure/redis/ - Azure Managed Redis documentation hub
• /azure/redis/overview - Consolidated AMR overview, key scenarios, and tier selection starting point
• /azure/redis/architecture - AMR architecture, clustering model, and policy guidance
• /azure/redis/migrate/migrate-overview - Migration hub organized into Understand differences, Explore options, and Plan execution

Azure CLI Command Reference

See [Azure CLI Commands](references/azure-cli-commands.md) for practical az redis examples to:

• List ACR caches in a subscription or resource group
• Extract cache details (region, SKU, shard count, replicas)
• Check persistence and geo-replication settings

SKU Mapping Reference

See [SKU Mapping Guide](references/sku-mapping.md) for guidelines, ACR → AMR mapping tables, selection criteria, and decision matrix. For AMR SKU definitions (M, B, X, Flash series), see [AMR SKU Specs](references/amr-sku-specs.md).

Dynamic Pricing Lookup

Once you've identified candidate SKUs, get real-time pricing with monthly cost calculations:

# 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

Script options:

• -NoHA / --no-ha - Non-HA deployment (AMR only, 50% savings for dev/test)
• -Shards N / --shards N - Number of shards (ACR Premium clustered)
• -Replicas N / --replicas N - Replicas per primary (ACR Premium MRPP, default: 1)
• -Currency X / --currency X - Currency code (default: USD)

SKUs supported:

• ACR: C0-C6 (Basic/Standard - must specify tier), P1-P5 (Premium)
• AMR: M10-M2000, B0-B1000, X3-X700, A250-A4500

Resources:

• [Pricing Tier Rules](references/pricing-tiers.md) - Calculation logic for HA, clustering, MRPP
• Azure Pricing Calculator - Official quotes

Feature Comparison

See [Feature Comparison](references/feature-comparison.md) for detailed comparison between ACR (Basic/Standard/Premium) and AMR features.

Retirement FAQ

See [Retirement FAQ](references/retirement-faq.md) for retirement dates, timelines, and common migration questions.

Relevant to this skill (ACR Basic/Standard/Premium):

• April 1, 2026: Creation blocked for new customers
• October 1, 2026: Creation blocked for existing customers
• September 30, 2028: Retirement date (instances disabled October 1, 2028)

Not covered by this skill:

• Enterprise/Enterprise Flash retirement (March 31, 2027) — contact Microsoft support

Migration Overview

See [Migration Overview](references/migration-overview.md) for detailed migration guidance including:

• Migration strategies (new cache, RDB export/import, dual-write, RIOT)
• Connection string changes
• Clustering policy and network isolation considerations

Infrastructure-as-Code (IaC) Template Migration

For converting ACR templates (ARM, Bicep, Terraform) to AMR format, use these reference docs:

• [ACR Template Parsing Guide](references/iac-acr-template-parsing.md) — How to read and extract configuration from ACR templates
• [AMR Template Structure Guide](references/iac-amr-template-structure.md) — Transformation rules, property mappings, and output structure for AMR templates
• [Example Templates](references/examples/iac/) — Before/after template pairs organized by format:
• arm/ — 6 ARM JSON scenarios (basic, premium non-clustered, clustered, VNet, persistence, all-features)
• arm-parameterized/ — 4 ARM JSON scenarios with separate parameter files
• bicep/ — 2 Bicep scenarios (basic, premium clustered)
• terraform/ — 2 Terraform scenarios (basic, premium clustered)

Workflow Selection

Choose the correct workflow based on the user's intent. The two workflows are independent — do not mix their steps.

| User Intent | Signal Phrases | Workflow | |---|---|---| | Move a live cache to AMR | "migrate cache", "move to AMR", "select SKU", "assess metrics", "migration strategy", "switch traffic" | Migration Workflow (Steps 1-4) | | Convert IaC templates to AMR format | "convert template", "Bicep migration", "ARM to AMR", "Terraform", "IaC", "template transformation", "region buildout" | IaC Migration Workflow (Steps 1-8) | | Compare features or answer general questions | "compare ACR vs AMR", "feature compatibility", "retirement date", "best practices" | Answer directly using reference docs — no workflow needed |

Ambiguous Requests

If the user's intent is unclear (e.g., "help me migrate to AMR" could mean either), ask:

> "Are you looking to migrate a live cache (data migration, SKU selection, traffic cutover) or convert your infrastructure-as-code templates (Bicep/ARM/Terraform) to AMR format? Or both?"

Both Workflows

If the user needs both (e.g., "migrate everything including our IaC"):

1. Run Migration Workflow first — this determines the target AMR SKU and validates sizing with metrics
2. Then run IaC Migration Workflow — using the SKU selected in step 1 as the target

---

Migration Workflow

Step 1: Assess Current Cache

Gather metrics from the existing ACR cache to inform SKU selection:

# Windows PowerShell
.\scripts\get_acr_metrics.ps1 -SubscriptionId  -ResourceGroup  -CacheName 
.\scripts\get_acr_metrics.ps1 -SubscriptionId  -ResourceGroup  -CacheName  -Days 7

# Linux/Mac bash
./scripts/get_acr_metrics.sh   
./scripts/get_acr_metrics.sh    7

Also retrieve the actual memory reservation to determine true usable capacity (defaults in the SKU mapping tables assume ~20%):

az redis show -n  -g  -o json \
  --query "{maxfragmentationmemoryReserved: redisConfiguration.maxfragmentationmemoryReserved, maxmemoryReserved: redisConfiguration.maxmemoryReserved}"

Both values are in MB. Actual Usable = SKU Capacity − (maxmemoryReserved + maxfragmentationmemoryReserved). Use this as the source of truth for sizing.

Requires: Azure CLI logged in (az login)

> Fallback: If the scripts fail (e.g., locked tenant, insufficient permissions, no CLI access), direct the user to retrieve the same metrics manually from the Azure Portal under their cache's Monitoring → Metrics blade.

Metrics retrieved (Peak, P95, and Average for each):

• Used Memory RSS (bytes and GB)
• Server Load (%)
• Connected Clients
• Network Bandwidth — Cache Read and Cache Write (bytes/sec)

> Clustered caches: For Premium caches with multiple shards, the scripts automatically detect the shard count and aggregate metrics across all shards. Memory and bandwidth are summed (total capacity), while Server Load and Connected Clients report the max per shard (bottleneck value). The output header indicates when shard aggregation is active.

Use these values to:

1. Size the target AMR SKU (usable memory ≥ peak used memory — no extra buffer needed with an eviction policy)
2. Choose tier (high Server Load + low memory → Compute Optimized X-series)
3. Verify connection limits are sufficient
4. Use P95 values to distinguish sustained load from occasional spikes

Zone pinning check: Also check if the source cache uses zone pinning:

az redis show -n  -g  -o json \
  --query "{zones: zones, zonalAllocationPolicy: properties.zonalAllocationPolicy}"

If zones is set and zonalAllocationPolicy is UserDefined, the cache is zone-pinned — deployed to specific availability zones chosen by the customer. Warn the user: AMR does not support zone pinning. When high availability is enabled, AMR is automatically zone redundant across all available zones in the region, but cannot be pinned to specific zones. If the user had zone pinning for co-locality with other resources (e.g., VMs in the same zone for lower latency), they should be aware this guarantee will not carry over to AMR.

Step 2: Select Target AMR SKU

1. Refer to the [SKU Mapping Guide](references/sku-mapping.md)
2. Use metrics from Step 1 to validate sizing
3. Get pricing for candidate SKUs:

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

Step 3: Plan Migration

1. Determine migration strategy (dual-write, snapshot/restore, etc.)
2. Clustering policy: Choose based on source cache type and target AMR size. See [Migration Overview](references/migration-overview.md) for guidance or [AMR Template Structure §6](references/iac-amr-template-structure.md#6-clustering-policy-decision-matrix) for the full decision matrix.
3. Network isolation: ACR caches using VNet injection must be replaced with Private Link on AMR, as AMR does not support VNet injection. Ensure Private Endpoints are configured before cutover.
4. Plan for potential downtime or data sync requirements
5. Update application connection strings and configuration

Step 4: Execute Migration

1. Create the target AMR cache
2. Migrate data using appropriate method
3. Validate data integrity
4. Switch application traffic to new cache

---

IaC Migration Workflow

> For the full 8-step workflow, see [IaC Migration Workflow](references/iac-migration-workflow.md).

Converts ACR templates (ARM JSON, Bicep, Terraform) to AMR format using AI-driven transfo

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AzureManagedRedis
• Source: AzureManagedRedis/amr-migration-skill
• License: MIT

Install and usage instructions live in the source repository linked above.