Migration Tooling Skill

az acr import (Preferred Method)

Server-side import — no local Docker daemon, no bandwidth through your machine:

# Import from ECR (requires IAM credentials configured)
az acr import \
  --name myacr \
  --source public.ecr.aws/myorg/myapp:v1.2.3 \
  --image myapp:v1.2.3

# Import from GCR
az acr import \
  --name myacr \
  --source gcr.io/my-project/myapp:v1.2.3 \
  --image myapp:v1.2.3

# Import from Docker Hub
az acr import \
  --name myacr \
  --source docker.io/library/nginx:1.25 \
  --image nginx:1.25

# Batch import with tag preservation
for img in app1:v1 app2:v2 app3:v3; do
  az acr import --name myacr --source old-registry.example.com/$img --image $img
done

skopeo copy (For Private/On-Prem Registries)

# Copy without Docker daemon
skopeo copy \
  docker://harbor.internal.com/project/myapp:v1 \
  docker://myacr.azurecr.io/project/myapp:v1 \
  --src-tls-verify=false \
  --dest-creds "$(az acr credential show -n myacr --query username -o tsv):$(az acr credential show -n myacr --query 'passwords[0].value' -o tsv)"

# Copy all tags for a repository
skopeo sync \
  --src docker --dest docker \
  harbor.internal.com/project/myapp \
  myacr.azurecr.io/project/myapp

crane copy (Lightweight Alternative)

# Copy single image
crane copy old-registry.example.com/myapp:v1 myacr.azurecr.io/myapp:v1

# Copy with platform filtering (linux/amd64 only)
crane copy --platform linux/amd64 old-registry.example.com/myapp:v1 myacr.azurecr.io/myapp:v1

Image Reference Updates in Manifests

After registry migration, update all image references in converted YAML:

ACR Authentication for AKS

# Attach ACR to AKS (managed identity-based pull, no imagePullSecret needed)
az aks update --name myaks --resource-group myrg --attach-acr myacr

# Verify
az aks check-acr --name myaks --resource-group myrg --acr myacr.azurecr.io

Velero — Backup & Restore

What Velero Handles

Velero for Migration Workflow

Source Cluster                    Target AKS Cluster
──────────────                    ──────────────────
1. Install Velero                 4. Install Velero
   (configured with                  (configured with
    Azure Blob storage)               same Azure Blob storage)

2. Backup namespace(s)            5. Restore backup
   velero backup create              velero restore create
   --include-namespaces app           --from-backup app-backup
   --snapshot-volumes                 --namespace-mappings
                                      old-ns:new-ns

3. Verify backup completed        6. Verify restore
   velero backup describe            velero restore describe

Velero Installation on AKS

# Install Velero CLI
# Windows: choco install velero / scoop install velero
# macOS: brew install velero
# Linux: download from GitHub releases

# Install Velero on AKS with Azure plugin
velero install \
  --provider azure \
  --plugins velero/velero-plugin-for-microsoft-azure:v1.10.0 \
  --bucket velero-backups \
  --secret-file ./credentials-velero \
  --backup-location-config \
    resourceGroup=myRG,storageAccount=myStorageAcct,subscriptionId=xxx \
  --snapshot-location-config \
    resourceGroup=myRG,subscriptionId=xxx \
  --use-node-agent  # for file-level PV backup via Kopia

Backup & Restore Commands

# Backup a namespace (resources + PV snapshots)
velero backup create app-migration \
  --include-namespaces production \
  --snapshot-volumes \
  --wait

# Backup with label selector
velero backup create frontend-backup \
  --selector app=frontend \
  --snapshot-volumes

# Restore to AKS (with namespace remapping)
velero restore create app-restore \
  --from-backup app-migration \
  --namespace-mappings production:production \
  --restore-volumes

# Restore specific resources only
velero restore create db-restore \
  --from-backup app-migration \
  --include-resources persistentvolumeclaims,persistentvolumes \
  --include-namespaces database

Velero Limitations & Considerations

Persistent Volume Data Migration

Migration Strategies by Data Size

azcopy for Storage Migration

# Copy Azure Files share to new location
azcopy copy \
  "https://source-storage.file.core.windows.net/share?SAS_TOKEN" \
  "https://target-storage.file.core.windows.net/share?SAS_TOKEN" \
  --recursive

# Copy Azure Blob container
azcopy copy \
  "https://source-storage.blob.core.windows.net/container?SAS_TOKEN" \
  "https://target-storage.blob.core.windows.net/container?SAS_TOKEN" \
  --recursive

# Sync (incremental copy — only changed files)
azcopy sync \
  "https://source.file.core.windows.net/share?SAS" \
  "https://target.file.core.windows.net/share?SAS" \
  --recursive

Cross-Cloud PV Migration

For PVs on source platforms (EBS, GCP PD, vSphere VMDK):

1. Source cluster: Use Velero with Kopia (file-level) to back up PV data to Azure Blob
2. Target AKS: Restore PV data from Azure Blob to Azure Disk/Files PVs
3. Alternative: Mount source PV → azcopy/rsync to Azure Files → mount on AKS

# Example: rsync from source pod to Azure Files (via jumpbox)
kubectl exec -n app source-pod -- tar czf - /data | \
  ssh jumpbox "az storage file upload-batch --destination share --source /dev/stdin"

DNS & Traffic Cutover

Cutover Strategy

flowchart TD
    Pre["Pre-Cutover<br/>Both clusters running<br/>Source handles traffic"]
    DNS["DNS Update<br/>Lower TTL to 60s<br/>24-48h before cutover"]
    Switch["Traffic Switch<br/>Update DNS to AKS<br/>ingress IP / FQDN"]
    Monitor["Monitor<br/>Watch error rates,<br/>latency, 5xx responses"]
    Rollback{"Issues?"}
    Complete["Cutover Complete<br/>Restore normal TTL<br/>Decommission source"]
    Revert["Rollback<br/>Revert DNS to source<br/>Investigate issues"]

    Pre --> DNS --> Switch --> Monitor --> Rollback
    Rollback -- No --> Complete
    Rollback -- Yes --> Revert --> Monitor

Cutover Checklist

Azure DNS Integration

# Update A record to point to AKS ingress
az network dns record-set a update \
  --resource-group dns-rg \
  --zone-name example.com \
  --name app \
  --set aRecords[0].ipv4Address=<AKS_INGRESS_IP>

# Or use CNAME for Azure-managed ingress FQDN
az network dns record-set cname set-record \
  --resource-group dns-rg \
  --zone-name example.com \
  --record-set-name app \
  --cname <AKS_INGRESS_FQDN>

Pre-Migration Validation

Source Cluster Assessment

AKS Readiness Checks

# Verify AKS cluster is ready
kubectl get nodes -o wide
kubectl get cs  # component status (deprecated but useful)

# Verify CSI drivers
kubectl get csidriver

# Verify storage classes
kubectl get sc

# Verify ingress controller
kubectl get svc -n ingress-nginx  # or kube-system for AGIC

# Verify ACR connectivity
az aks check-acr --name myaks --resource-group myrg --acr myacr.azurecr.io

# Verify DNS resolution
kubectl run dnstest --image=busybox --rm -it -- nslookup kubernetes.default

Post-Migration Validation

Functional Validation Checklist

Data Integrity Verification

# Compare record counts (database workloads)
# Source:
kubectl exec -n db source-db-pod -- psql -c "SELECT COUNT(*) FROM important_table"
# Target:
kubectl exec -n db target-db-pod -- psql -c "SELECT COUNT(*) FROM important_table"

# Compare file checksums (file storage workloads)
# Source:
kubectl exec -n app source-pod -- find /data -type f -exec md5sum {} \; | sort > /tmp/source-checksums.txt
# Target:
kubectl exec -n app target-pod -- find /data -type f -exec md5sum {} \; | sort > /tmp/target-checksums.txt
diff /tmp/source-checksums.txt /tmp/target-checksums.txt

Rollback Plan

Every migration must have a documented rollback procedure:

1. DNS rollback — revert DNS records to source cluster IPs (TTL should still be low)
2. Data rollback — restore from pre-cutover backup if writes occurred on target
3. Traffic rollback — update load balancer / traffic manager to route to source
4. Timeline — rollback decision must be made within defined window (typically 1-4 hours)

Phase-Specific Guidance

Phase 1: Analysis

During source analysis, assess and document:

1. Registry inventory — list all container image registries and image count per registry
2. PV inventory — list all PVs with size, access mode, and current usage
3. Data migration complexity — score based on total data volume and number of stateful workloads
4. CRD dependencies — list CRDs and check AKS compatibility
5. External dependencies — databases, message queues, caches outside the cluster

Include in the analysis report:

• Image registry migration scope table
• Persistent data migration strategy recommendation
• External dependency mapping

Phase 4: Documentation

Include in the migration report:

1. Registry Migration Runbook with:
   • az acr import commands for each image
   • ACR authentication setup (az aks update --attach-acr)
   • Image reference update checklist
2. Data Migration Runbook with:
   • Velero backup/restore commands (if applicable)
   • azcopy commands for storage migration (if applicable)
   • Data integrity verification steps
3. DNS Cutover Runbook with:
   • TTL reduction timeline
   • DNS update commands
   • Monitoring checklist
   • Rollback procedure with commands
4. Validation Runbook with:
   • Pre-cutover smoke test commands
   • Post-cutover functional validation checklist
   • Data integrity verification commands
   • Rollback decision criteria and timeline