diff --git a/README.md b/README.md index fd38b98..167334a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,104 @@ -# MigratingToAMR -Support for migrating Azure Redis workloads into Azure Managed Redis +# Migrating to Azure Managed Redis + +Support for migrating Azure Cache for Redis workloads into Azure Managed Redis (AMR). + +## Overview + +This repository provides tooling to migrate an existing **Azure Cache for Redis** instance to **Azure Managed Redis** using the ARM REST API. The migration is a DNS-switchover-based, live migration that keeps your endpoint and credentials intact — clients reconnect automatically without needing configuration changes. + +## Contents + +| Path | Description | +| ---- | ----------- | +| [Scripts/Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1](Scripts/Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1) | PowerShell script for driving the full migration lifecycle via ARM REST APIs | + +## Prerequisites + +- [Az PowerShell module](https://learn.microsoft.com/powershell/azure/install-azps-windows) installed +- An existing **Azure Cache for Redis** instance (source) +- An existing **Azure Managed Redis** instance (target) in the same subscription +- Sufficient RBAC permissions on both resources + +## Script: Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 + +The script supports four actions that map to the migration lifecycle: + +| Action | Description | +| ------ | ----------- | +| `Validate` | Checks whether the source and target caches are compatible for migration and reports any disparities | +| `Migrate` | Initiates the migration (DNS switchover; data migration is skipped by default) | +| `Status` | Retrieves the current state of an in-progress or completed migration | +| `Cancel` | Cancels an in-progress migration | + +### Parameters + +| Parameter | Required | Default | Description | +| --------- | -------- | ------- | ----------- | +| `-Action` | Yes | — | One of `Validate`, `Migrate`, `Status`, `Cancel` | +| `-TargetResourceId` | Yes | — | Full ARM resource ID of the target Azure Managed Redis cluster | +| `-SourceResourceId` | For `Validate` / `Migrate` | — | Full ARM resource ID of the source Azure Cache for Redis instance | +| `-ForceMigrate` | No | `$false` | When `$true`, proceeds with migration even if parity validation returns warnings | +| `-TrackMigration` | No | `$false` | When set, blocks until the long-running operation completes | +| `-Environment` | No | `AzureCloud` | Azure environment. Allowed values: `AzureCloud`, `AzureChinaCloud`, `AzureUSGovernment`, `AzureGermanCloud` | +| `-Help` | No | `$false` | Displays full help for the script | + +### Usage Examples + +**Validate compatibility before migrating:** + +```powershell +.\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 ` + -Action Validate ` + -SourceResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/Redis/" ` + -TargetResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/redisEnterprise/" +``` + +**Start migration and wait for completion:** + +```powershell +.\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 ` + -Action Migrate ` + -SourceResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/Redis/" ` + -TargetResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/redisEnterprise/" ` + -TrackMigration +``` + +**Start migration, ignoring parity warnings:** + +```powershell +.\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 ` + -Action Migrate ` + -SourceResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/Redis/" ` + -TargetResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/redisEnterprise/" ` + -ForceMigrate $true +``` + +**Check migration status:** + +```powershell +.\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 ` + -Action Status ` + -TargetResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/redisEnterprise/" +``` + +**Cancel an in-progress migration:** + +```powershell +.\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 ` + -Action Cancel ` + -TargetResourceId "/subscriptions//resourceGroups//providers/Microsoft.Cache/redisEnterprise/" +``` + +## Migration Flow + +```mermaid +flowchart LR + Validate --> Migrate --> Status + Status -.-> Cancel + style Cancel stroke-dasharray: 5 5 +``` + +1. **Validate** — confirm the source and target are compatible. +2. **Migrate** — triggers the ARM long-running operation. DNS is switched so the source hostname begins resolving to the AMR endpoint. +3. **Status** — poll until the migration reports a terminal state (`Succeeded` or `Failed`). +4. **Cancel** — available while migration is still in progress. diff --git a/Scripts/Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 b/Scripts/Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 index 6cb1bb7..5c57c35 100644 --- a/Scripts/Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 +++ b/Scripts/Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 @@ -14,6 +14,7 @@ If set to $false (default), migration is blocked when validation returns any warning. .PARAMETER Environment The Azure environment to use (default is the public "AzureCloud"). + Some possible values: "AzureCloud", "AzureChinaCloud", "AzureUSGovernment", "AzureGermanCloud". .PARAMETER TrackMigration If set, the script will wait for the migration operation to complete (default is $false). .PARAMETER Verbose @@ -25,6 +26,8 @@ Initiates a migration and tracks its progress. .\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 -Action Migrate -SourceResourceId "/subscriptions/xxxxx/resourceGroups/rg1/providers/Microsoft.Cache/Redis/redis1" -TargetResourceId "/subscriptions/xxxxx/resourceGroups/rg1/providers/Microsoft.Cache/redisEnterprise/amr1" -ForceMigrate $true Initiates a migration and forces migration when parity validation returns warnings. + .\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 -Action Validate -SourceResourceId "/subscriptions/xxxxx/resourceGroups/rg1/providers/Microsoft.Cache/Redis/redis1" -TargetResourceId "/subscriptions/xxxxx/resourceGroups/rg1/providers/Microsoft.Cache/redisEnterprise/amr1" + Validates whether a migration can be performed between the source and target caches. .\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 -Action Status -TargetResourceId "/subscriptions/xxxxx/resourceGroups/rg1/providers/Microsoft.Cache/redisEnterprise/amr1" Checks the status of the migration. .\Azure-Redis-Migration-Arm-Rest-Api-Utility.ps1 -Action Cancel -TargetResourceId "/subscriptions/xxxxx/resourceGroups/rg1/providers/Microsoft.Cache/redisEnterprise/amr1" @@ -37,7 +40,7 @@ param ( [Parameter()] - [ValidateSet("Migrate", "Status", "Cancel")] + [ValidateSet("Migrate", "Validate", "Status", "Cancel")] [string] $Action, [Parameter()] @@ -77,7 +80,7 @@ if ($Help) } # Parse the TargetResourceId (Azure Managed Redis resourceId) -$pattern = '(?i)^/subscriptions/(?[^/]+)/resourceGroups/(?[^/]+)/providers/[^/]+/redisEnterprise/(?[^/]+)(?:/.*)?/?$' +$pattern = '(?i)^/subscriptions/(?[^/]+)/resourceGroups/(?[^/]+)/providers/Microsoft\.Cache/redisEnterprise/(?[^/]+)(?:/.*)?/?$' if ($TargetResourceId -match $pattern) { $SubscriptionId = $Matches.SubscriptionId @@ -226,8 +229,28 @@ switch ($Action) break } + "Validate" + { + $payload = @{ + properties = @{ + sourceResourceId = $SourceResourceId; + skipDataMigration = $true; + }; + } | ConvertTo-Json -Depth 3 + + Write-Host "This command will validate whether a migration can be performed between the source and target caches." + $response = Invoke-AzRestMethod ` + -Method POST ` + -Path "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.Cache/RedisEnterprise/$AmrCacheName/migrations/default/validate?api-version=$ArmApiVersion" ` + -Payload $payload + + Print-Response $response + + break + } + Default { - throw "Invalid action specified. Please use one of the following: 'Migrate', 'Status', 'Cancel'." + throw "Invalid action specified. Please use one of the following: 'Migrate', 'Validate', 'Status', 'Cancel'." } } \ No newline at end of file