Azure Storage Account Migration Guide: Complete PowerShell Solution

Migrating Azure storage containers between accounts or within the same account can be complex. This guide provides production-ready PowerShell scripts using AzCopy to handle different migration scenarios efficiently.

Prerequisites

Before starting the migration, ensure you have the following tools and setup completed:

Required Tools

• Windows PowerShell ISE or PowerShell
• AzCopy v10 - Download from Microsoft Learn
• Azure PowerShell Module (if not already installed)

Setup Steps

1. Download and Extract AzCopy

1. Download the AzCopy zip file from the Microsoft Learn link above
2. Extract the contents to your Downloads directory
3. Note the extraction path for later use in the scripts

2. Create Destination Storage Account

• Create a new storage account in your destination Azure subscription
• Ensure the storage account name is globally unique

3. Generate SAS Tokens

Generate Shared Access Signature (SAS) tokens for both source and destination storage accounts. Ensure the SAS tokens have appropriate permissions:

• Read - Required for source account
• Write - Required for destination account
• List - Required for both accounts
• Create - Required for destination account

Migration Scenarios

Scenario 1: Copy All Containers Between Storage Accounts

Use this script when you need to migrate all containers from one storage account to another.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Define the storage account information
$srcSA = ""    # Current storage account name
$destSA = ""   # Destination storage account name
# Use the provided SAS tokens directly
$srcSAS = ""   # Current storage account SAS token
$destSAS = ""  # Destination storage account SAS token
# Search for azcopy.exe in the downloads folder
$downloadFolder = "" # The location of Azure Copy
Write-Host "Searching for AzCopy in $downloadFolder..." -ForegroundColor Yellow
$azcopyPath = Get-ChildItem -Path $downloadFolder -Recurse -Filter "azcopy.exe" | 
Select-Object -First 1 -ExpandProperty FullName
if ($azcopyPath) {
Write-Host "Found AzCopy at: $azcopyPath" -ForegroundColor Green
# Get the context for the source storage account using the SAS token
$srcContext = New-AzStorageContext -StorageAccountName $srcSA -SasToken $srcSAS

Scenario 2: Copy Specific Container Between Storage Accounts

Use this script when you need to migrate only a specific container from one storage account to another.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Define the storage account information
$srcSA = ""           # Current storage account name
$destSA = ""          # Destination storage account name
$containerName = ""   # Storage container name to be transferred
# Use the provided SAS tokens directly
$srcSAS = ""          # Current storage account SAS token
$destSAS = ""         # Destination storage account SAS token
# Search for azcopy.exe in the downloads folder
$downloadFolder = ""  # Current location of Azure Copy
Write-Host "Searching for AzCopy in $downloadFolder..." -ForegroundColor Yellow
$azcopyPath = Get-ChildItem -Path $downloadFolder -Recurse -Filter "azcopy.exe" | 
Select-Object -First 1 -ExpandProperty FullName
if ($azcopyPath) {
Write-Host "Found AzCopy at: $azcopyPath" -ForegroundColor Green
# Construct the source and destination URLs for the specific container

Scenario 3: Copy Container Within Same Storage Account

Use this script when you need to duplicate a container within the same storage account (e.g., for backup or testing purposes).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Define the storage account information
$storageAccount = ""   # Your storage account name
$srcContainer = ""     # Source container name
$destContainer = ""    # Destination container name
$sasToken = ""         # SAS token for the storage account
# Search for azcopy.exe in the downloads folder
$downloadFolder = ""   # Location of the Azure Copy
Write-Host "Searching for AzCopy in $downloadFolder..." -ForegroundColor Yellow
$azcopyPath = Get-ChildItem -Path $downloadFolder -Recurse -Filter "azcopy.exe" | 
Select-Object -First 1 -ExpandProperty FullName
if ($azcopyPath) {
Write-Host "Found AzCopy at: $azcopyPath" -ForegroundColor Green
# Construct the source and destination URLs for the containers
$source = "https://$storageAccount.blob.core.windows.net/$srcContainer/?$sasToken"
$destination = "https://$storageAccount.blob.core.windows.net/$destContainer/?$sasToken"

Security Considerations

When working with Azure storage migrations, security should be your top priority:

• SAS Token Security: Keep your SAS tokens secure and avoid sharing them. Store them in secure variables or Azure Key Vault for production environments.
• Token Expiration: Ensure SAS tokens have sufficient expiration time for the migration. Large migrations can take hours or even days.
• Permissions: Verify that SAS tokens have only the necessary permissions (Read, Write, List, Create). Follow the principle of least privilege.

Performance Tips

To optimize your migration performance:

• Bandwidth Considerations: Large transfers may take significant time depending on your network bandwidth. Plan migrations during low-traffic periods.
• Parallel Operations: AzCopy automatically optimizes parallel transfers, but you can adjust the concurrency with the --cap-mbps flag if needed.
• Monitoring: Monitor the progress in the PowerShell console. AzCopy provides detailed progress information for long-running operations.

Troubleshooting Common Issues

AzCopy Not Found

If you get "AzCopy executable not found" errors:

• Ensure AzCopy is properly extracted from the zip file
• Verify the $downloadFolder path is correct
• Check that the azcopy.exe file exists in the specified directory

Permission Errors

If you encounter permission-related errors:

• Verify SAS token permissions include Read, Write, List, and Create as needed
• Check that SAS tokens haven't expired
• Ensure the destination storage account exists and is accessible

Network Issues

For network-related problems:

• Check network connectivity to Azure storage endpoints
• Verify firewall settings allow HTTPS traffic to *.blob.core.windows.net
• Consider using the --cap-mbps flag to limit bandwidth usage

Monitoring Migration Progress

For large migrations, consider implementing additional monitoring:

1
2
3
4
5
6
7
8
9
10
11
12
# Enhanced script with progress monitoring
$logFile = "migration-log-$(Get-Date -Format 'yyyyMMdd-HHmmss').txt"
function Write-Log {
param($Message)
$timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
$logMessage = "[$timestamp] $Message"
Write-Host $logMessage
Add-Content -Path $logFile -Value $logMessage
}
# Use Write-Log instead of Write-Host for better tracking
Write-Log "Starting migration process..."
Write-Log "Source: $srcSA, Destination: $destSA"

Best Practices

• Test First: Always test with a small container before running full migrations
• Backup: Ensure you have backups of critical data before migration
• Validation: Verify data integrity after migration by comparing file counts and sizes
• Cleanup: Remove temporary SAS tokens and log files after migration
• Documentation: Document your migration process for future reference

Additional Resources

• AzCopy Documentation
• Azure Storage SAS Documentation
• Azure PowerShell Module

This guide provides you with production-ready scripts for Azure storage migrations. Remember to always test in a development environment first and follow security best practices when handling SAS tokens and sensitive data.