What I Would Do Differently in My Next Azure Storage Migration

Seven lessons drawn from real Azure file share migrations. Not theory — the specific decisions that cost time, created risk, or produced regret. With illustrated improved processes for each one.

By Francis Avorgbedor | Azure Engineer  ·  July 11, 2026  ·  17 min read  ·  Azure Files · Migration · Lessons

FA

Francis Avorgbedor

Azure Engineer  ·  SEVENAI  ·  Azure Field Notes

7

Things I would change on the next migration

3

Days of rework caused by the SID estimation mistake alone

4

Days added to upload phase by the bandwidth oversight

0

Of these mistakes I expect to make twice

Ihave now written the case study of the 15TB QNAP-to-Azure migration, the lessons learned post, the behind-the-scenes architecture guide, and the why-we-moved story. Each of those posts describes what happened. This one describes what I would change. There is a difference between a migration that completed successfully and a migration that was executed well. Our migrations complete successfully. They are not always executed as well as they could be. This post is the honest account of the gaps — the things I knew better but did not do, the things I did not know and had to learn, and the things I will do first on the next engagement before anything else.

I am writing this for two audiences. The first is engineers planning their first Azure storage migration who want to avoid the specific mistakes that are not obvious from documentation. The second is engineers who have already run a migration and recognise some of what follows from their own experience. Both groups will find something useful here. Neither group will find reassuring fiction about everything going smoothly.

Lesson 01

I would run Azure Migrate discovery before writing a single line of Terraform

On the QNAP migration, we built the target infrastructure — storage accounts, file shares, Private Endpoints, sync groups — based on a manual inventory we assembled over two days from QNAP's admin portal and a PowerShell script against the file shares. The inventory was accurate. It was also incomplete: it told us sizes and file counts, but did not tell us access patterns, did not classify shares by activity level, and did not surface the 23 files with illegal characters until Day 22 of the upload phase.

What I did — and why it cost us

Manual inventory via QNAP admin portal + PowerShell. Took two days. Missed access frequency data (which would have changed tier selection for two shares). Missed illegal filenames (found 22 days too late). Missed automated tier recommendations (we estimated manually and got two shares wrong initially).

✓ What I would do instead

Deploy Azure Migrate appliance on day one. It runs agentlessly, discovers all SMB and NFS shares automatically, captures storage consumed, file counts, and access patterns, classifies each share as Ready/Conditional/Not Ready for Azure Files, and provides per-share tier recommendations. Discovery completes in hours. Everything downstream — Terraform design, tier selection, wave planning — is driven by real data rather than estimates.

Figure 1 — Azure Migrate vs manual inventory: what each gives you

Lesson 02

I would estimate SID remap time by file count and unique ACL entries — not by share count

This is the mistake that cost us the most time on the QNAP migration. We had eight shares to remap. We estimated two days for SID mapping. It took six. Finance alone ran for eleven hours on the icacls script. The estimation error was not about the difficulty of the task — it was about the unit of measurement. We estimated by number of shares. We should have estimated by number of files with non-standard ACLs.

The wrong estimation formula

8 shares × 0.25 days/share = 2 days. Wrong. Finance had 1.4M files with 847 unique ACL entries. icacls processes approximately 2,000 entries per minute. 847 entries × (1.4M files ÷ average inheritance depth) = 11 hours for Finance alone.

✓ The correct estimation formula

Run this PowerShell query on each share before estimation. Use the output to calculate realistic remap time. Budget contingency for shares with high ACL complexity — Finance and HR shares in professional services environments consistently have more complex permission structures than any estimate suggests.

Figure 2 — SID remap estimation: the correct pre-migration query and formula

Lesson 03

I would configure Private Endpoints and verify connectivity before registering the AFS agent — every time

We configured Private Endpoints after the Azure File Sync agent was already registered and syncing. This required a sync pause and full agent re-registration — an hour of work that should have been zero. The correct sequence is always: Private Endpoints → connectivity test → then agent registration. Azure Files traffic should never traverse the public internet in a production deployment.

What we did — wrong order

Provisioned storage → Registered AFS agent → Configured Private Endpoints → Re-registered agent (1 hour rework). Azure Files synced over public internet for 3 days before Private Endpoints were in place.

✓ Correct order — next time

Provisioned storage → Private Endpoints → Test-NetConnection to verify private IP resolves → AD auth → Storage Sync Service → AFS agent registration. Zero re-registration. Zero public internet traversal.

Figure 3 — Correct provisioning sequence: Private Endpoint verification step before AFS agent

Verify Private Endpoint before AFS agent registration# Run from Windows Server — confirm storage account resolves to private IP Test-NetConnection -ComputerName <storageaccount>.file.core.windows.net -Port 445
# Expected: TcpTestSucceeded = True AND RemoteAddress = 10.x.x.x (private IP) # If RemoteAddress = public IP: Private Endpoint DNS not configured correctly — fix before proceeding

Lesson 04

I would use Storage Mover for archive shares and Azure File Sync only for active hybrid shares

We used Azure File Sync for all eight shares — including Archive2022 and Archive2023, which are read-only after migration, never written to, and accessed less than once per quarter. AFS is designed for continuously synced, actively used file shares. Deploying it for read-only archives means maintaining a sync infrastructure that provides no benefit — the archives are never updated, so the continuous sync capability of AFS generates zero value. Storage Mover is the correct tool for one-time archive migrations.

Figure 4 — Tool assignment by share type: the decision I would make differently

Lesson 05

I would measure actual WAN bandwidth and factor the client's traffic shaping — then double the upload timeline estimate

We estimated the Phase 4 AFS upload based on 500Mbps line capacity. We did not measure the actual available upload bandwidth during business hours, and we did not ask about the client's existing traffic shaping policies. The result: AFS upload throughput dropped to approximately 60GB per day during business hours (from 200GB+ overnight), and Phase 4 ran four days longer than the plan. The fix is a two-hour measurement exercise on day one of the project.

Our estimation error

Estimated: 500Mbps × 24hrs × 11 days = 15TB transferred in 11 days. Actual: business-hours throttling + existing traffic shaping cut average throughput in half. Result: 15 days, not 11. Client maintenance window had to be pushed one week.

✓ The pre-project bandwidth measurement I would run first

Figure 5 — Bandwidth measurement process: the 2-hour exercise that saves days of estimation error

Lesson 06

I would provision the Windows Server intermediate in Azure — not on-premises

We used an on-premises Windows Server as the Azure File Sync intermediate. This meant the initial RoboCopy ran over the 10GbE local network (fast — 300MB/s), but the AFS upload from the Windows Server to Azure Files ran over the 500Mbps WAN link (the bottleneck). If we had provisioned the Windows Server as an Azure VM in the same region as the target storage accounts, the AFS sync between the Azure VM and Azure Files would have run at intra-Azure speeds — effectively unlimited — rather than WAN upload speeds. The only WAN transfer would have been the initial RoboCopy from the QNAP to the Azure VM, which would still have been the bottleneck, but the subsequent sync would have been dramatically faster.

What we did — on-premises Windows Server

QNAP → WinSrv (10GbE, fast) → Azure Files (500Mbps WAN, slow). The WAN was the bottleneck for 100% of the data. 11 days for upload phase.

✓ Next time — Azure VM as intermediate

QNAP → Azure VM (500Mbps WAN, same bottleneck for initial copy) → Azure Files (intra-Azure, essentially free). Post-initial-copy delta syncs run at intra-Azure speed. Cutover delta takes minutes, not hours.

Figure 6 — On-premises vs Azure VM intermediate: where the bottleneck moves

Lesson 07

I would set up monitoring and alerts before the first byte moves — not after the first problem appears

We configured monitoring reactively. The AFS sync error alert was not in place when the 23 silently skipped files accumulated over 22 days. The storage account IOPS alert was not in place when one share briefly throttled during a high-traffic hour. The Azure Backup alert was not configured until after cutover. Each of these gaps meant we discovered problems by checking dashboards manually rather than being notified automatically. The monitoring configuration takes two hours. Run it before Phase 3, not after cutover.

Figure 7 — The monitoring stack that should be in place before Phase 3 starts

The most important alert — AFS files not syncing (run before Phase 3)# Azure CLI — create alert rule on ItemsNotSyncing metric az monitor metrics alert create \
  --name "afs-items-not-syncing" \
  --resource-group <rg> \
  --scopes <storage-sync-service-resource-id> \
  --condition "count ItemsNotSyncing > 0" \
  --window-size 5m \
  --evaluation-frequency 1m \
  --severity 1 \
  --action-group <action-group-id>
# This alert fires within 5 minutes of ANY file being skipped # Without it: silently skipped files accumulate for days before you notice

"A migration that completed successfully is not the same as a migration that was executed well. The first tells you the data got there. The second tells you it got there without unnecessary risk, rework, or lost sleep."

— Francis Avorgbedor | Azure Field Notes, July 2026

The seven changes — quick reference

Change 01

Deploy Azure Migrate before writing Terraform

Automated discovery gives you access patterns, tier recommendations, and illegal filename flags in hours. Every downstream decision is better for it.

Change 02

Estimate SID remap by file count and unique ACL entries

Run the Get-Acl query on each share before estimation. Budget by (files × unique ACLs) ÷ 2,000 entries/min. Add 50% contingency.

Change 03

Private Endpoints before AFS agent — Test-NetConnection as the gate

Run Test-NetConnection and confirm the private IP resolves before registering the AFS agent. Non-negotiable every time.

Change 04

Storage Mover for archives, AFS only for active hybrid shares

Continuous sync infrastructure for read-only archives generates zero value and adds unnecessary agent complexity.

Change 05

Measure actual WAN bandwidth at business hours — then double the estimate

Two hours of measurement at the start of the project prevents four days of schedule renegotiation at the end of it.

Change 06

Azure VM as intermediate — not on-premises Windows Server

Moves the WAN bottleneck to apply only once. Post-initial-copy delta syncs run at intra-Azure speed. Cutover deltas take minutes.

Change 07

Full monitoring stack configured before Phase 3 starts

Five alert rules in two hours. Discovers skipped files in minutes rather than days. Never configure monitoring reactively on a data migration.

The principle

Measure first, configure second, migrate third

Every item on this list is a variation of the same mistake: starting the technical work before the measurement work was complete. On the next migration, the first two weeks are measurement and planning. Not a line of Terraform until the data says we understand what we are working with.

Get the Azure field notes — every week

Real retrospectives, honest engineering, specific fixes. Written by Francis Avorgbedor.