Behind the Scenes of a Large-Scale Azure File Share Migration
From assessment through cutover — the complete architectural story of how large enterprise file share migrations actually work: what tools to use when, how to design your share mapping, where the surprises live, and what the monitoring looks like at scale.
5Migration tools evaluated — only 2 used in production8Phases from assessment to post-migration validation100M+Files Storage Mover tested to at enterprise scale0Files lost in production — the only acceptable numberLarge-scale file share migrations sound like infrastructure projects. They are not. They are change management projects with an infrastructure implementation layer underneath. The file copying is the easy part. The hard parts are the conversations you have before the first byte moves — with storage architects about share mapping, with security teams about ACL preservation, with service owners about downtime tolerance, and with the finance team about the cost model that justifies the move. This post covers both layers: the architecture and tooling decisions that determine whether the migration works, and the organisational patterns that determine whether it lands without an incident.
I am writing this as a companion to the QNAP case study and lessons learned posts in this series. Where those posts covered a specific 15TB migration in detail, this post covers the general pattern — applicable to migrations ranging from a few terabytes to hundreds of terabytes across dozens of file servers. The scale changes the tool choices and the coordination overhead. The fundamentals do not change.
From assessment through cutover — the complete architectural story of how large enterprise file share migrations actually work: what tools to use when, how to design your share mapping, where the surprises live, and what the monitoring looks like at scale.
Large-scale file share migrations sound like infrastructure projects. They are not. They are change management projects with an infrastructure implementation layer underneath. The file copying is the easy part. The hard parts are the conversations you have before the first byte moves — with storage architects about share mapping, with security teams about ACL preservation, with service owners about downtime tolerance, and with the finance team about the cost model that justifies the move. This post covers both layers: the architecture and tooling decisions that determine whether the migration works, and the organisational patterns that determine whether it lands without an incident.
I am writing this as a companion to the QNAP case study and lessons learned posts in this series. Where those posts covered a specific 15TB migration in detail, this post covers the general pattern — applicable to migrations ranging from a few terabytes to hundreds of terabytes across dozens of file servers. The scale changes the tool choices and the coordination overhead. The fundamentals do not change.
The eight-phase migration lifecycle — the full picture before you start
Most migration guides describe the data movement phases. What they omit is the assessment and validation work that determines whether the data movement phases succeed. Here is the complete lifecycle.
Figure 1 — The complete Azure file share migration lifecycle: 8 phasesBlue = planning phases · Amber = provisioning phases · Green = migration phases · Red = cutover
Most migration guides describe the data movement phases. What they omit is the assessment and validation work that determines whether the data movement phases succeed. Here is the complete lifecycle.
Phase 1 — Assessment and discovery: the work that determines everything else
Azure Migrate now supports automated discovery and assessment of SMB and NFS file shares hosted on Windows and Linux servers — agentlessly, without manual inventory scripts. This capability, announced in April 2026, changes the discovery phase from a weeks-long manual exercise into an hours-long automated assessment.
Figure 2 — Azure Migrate file share assessment: automated discovery to migration planAzure Migrate appliance discovery typically completes within a few hours — no manual scripting required
Azure Migrate now supports automated discovery and assessment of SMB and NFS file shares hosted on Windows and Linux servers — agentlessly, without manual inventory scripts. This capability, announced in April 2026, changes the discovery phase from a weeks-long manual exercise into an hours-long automated assessment.
Phase 2 — Share mapping: the decision that shapes everything downstream
The most consequential pre-migration decision is how your on-premises share structure maps to Azure file shares. Get this wrong and you create performance bottlenecks, unnecessary IOPS sharing, or an operational complexity that costs more to manage than the migration saved.
Figure 3 — Share mapping strategies: 1:1 mapping vs share grouping vs common-root approachFor active shares in HDD storage accounts, pool only archival or low-activity shares — high-activity shares need dedicated storage accounts to avoid shared IOPS contention
The most consequential pre-migration decision is how your on-premises share structure maps to Azure file shares. Get this wrong and you create performance bottlenecks, unnecessary IOPS sharing, or an operational complexity that costs more to manage than the migration saved.
Phase 4 — Tool selection: the decision matrix you actually need
There is no single correct migration tool. The correct tool depends on your source type, your network bandwidth, your need for continuous sync post-migration, and whether you want a managed service or a scriptable command-line approach. Here is how the decision actually works in practice.
Figure 4 — Migration tool selection: decision flowchartAzure Storage Mover is faster than RoboCopy for cloud transfer because it uses the FileREST API rather than SMB — tested to 100 million itemsTool Best for ACL fidelity Ongoing sync Managed service Speed Azure Storage Mover One-time NAS/server migration, SMB + NFS, large namespaces ✓ Full Delta only ✓ Fully managed Fastest — FileREST API Azure File Sync + RoboCopy Hybrid deployments, cloud tiering needed, ongoing sync required ✓ Full via /COPY:DATSO ✓ Continuous Agent-based Moderate — WAN upload AzCopy Windows Server source, scriptable, no managed service needed ✓ Full ✗ Manual reruns ✗ Script only Fast — parallel threads Azure Data Box >10TB + constrained WAN, offline transfer, physical shipment ✓ Full via RoboCopy ✗ One-time only Appliance-based Fastest for large offline Azure Migrate + Mover Large enterprise, automated assessment + execution in one tool ✓ Full Delta only ✓ Fully managed Fast — optimised API
There is no single correct migration tool. The correct tool depends on your source type, your network bandwidth, your need for continuous sync post-migration, and whether you want a managed service or a scriptable command-line approach. Here is how the decision actually works in practice.
| Tool | Best for | ACL fidelity | Ongoing sync | Managed service | Speed |
|---|---|---|---|---|---|
| Azure Storage Mover | One-time NAS/server migration, SMB + NFS, large namespaces | ✓ Full | Delta only | ✓ Fully managed | Fastest — FileREST API |
| Azure File Sync + RoboCopy | Hybrid deployments, cloud tiering needed, ongoing sync required | ✓ Full via /COPY:DATSO | ✓ Continuous | Agent-based | Moderate — WAN upload |
| AzCopy | Windows Server source, scriptable, no managed service needed | ✓ Full | ✗ Manual reruns | ✗ Script only | Fast — parallel threads |
| Azure Data Box | >10TB + constrained WAN, offline transfer, physical shipment | ✓ Full via RoboCopy | ✗ One-time only | Appliance-based | Fastest for large offline |
| Azure Migrate + Mover | Large enterprise, automated assessment + execution in one tool | ✓ Full | Delta only | ✓ Fully managed | Fast — optimised API |
Phase 5 — Deploying Azure Storage Mover: step by step
Storage Mover is the recommended path for most large-scale NAS-to-Azure-Files migrations where hybrid sync is not required long-term. It is faster than SMB-based tools because it uses the FileREST API, it is fully managed from the Azure portal, and it has been tested to 100 million namespace items. Here is exactly how to set it up.
Figure 5 — Azure Storage Mover deployment architecture and setup sequenceAgent VM must be deployed close to the source — ideally on the same LAN segment — to minimise source-to-agent transfer latency1Azure Portal → Storage Mover → Create
Storage Mover is the recommended path for most large-scale NAS-to-Azure-Files migrations where hybrid sync is not required long-term. It is faster than SMB-based tools because it uses the FileREST API, it is fully managed from the Azure portal, and it has been tested to 100 million namespace items. Here is exactly how to set it up.
Create the Storage Mover resource
In the Azure portal, create a new Storage Mover resource in the same region as your target storage accounts. The resource is the orchestration plane — it tracks agents, projects, jobs, and telemetry. One Storage Mover resource can manage multiple agents and migration projects simultaneously.
2Deploy VM on Hyper-V or VMware → SSH registration
In the Azure portal, create a new Storage Mover resource in the same region as your target storage accounts. The resource is the orchestration plane — it tracks agents, projects, jobs, and telemetry. One Storage Mover resource can manage multiple agents and migration projects simultaneously.
Deploy and register the Storage Mover agent VM
Download the Storage Mover agent VM image and deploy it on a Hyper-V or VMware host close to your source shares. Connect locally over SSH to complete agent registration. All subsequent steps are managed from the Azure portal — the SSH connection is only needed for initial registration. For large migrations, deploy multiple agents to run parallel jobs across different shares.
3Key Vault → Secrets → username + password
Download the Storage Mover agent VM image and deploy it on a Hyper-V or VMware host close to your source shares. Connect locally over SSH to complete agent registration. All subsequent steps are managed from the Azure portal — the SSH connection is only needed for initial registration. For large migrations, deploy multiple agents to run parallel jobs across different shares.
Create Azure Key Vault with source share credentials (SMB only)
For SMB source shares, create an Azure Key Vault and add two secrets: one for the username and one for the password the agent will use to access the source share. NFS source shares do not require Key Vault credentials — they use the NFS export's access controls directly. The Key Vault is referenced when creating the migration job, not when registering the agent.
4Storage Mover → Endpoints → Source + Target
For SMB source shares, create an Azure Key Vault and add two secrets: one for the username and one for the password the agent will use to access the source share. NFS source shares do not require Key Vault credentials — they use the NFS export's access controls directly. The Key Vault is referenced when creating the migration job, not when registering the agent.
Define source and target endpoints
Create a source endpoint pointing to the SMB share path on your NAS or file server. Create a target endpoint pointing to the Azure file share in your target storage account. Each share pair requires its own source and target endpoint. You can create all endpoints before starting any jobs — this is useful for large migrations where you want to review the full mapping before beginning data transfer.
5Storage Mover → Projects → Jobs → Start
Create a source endpoint pointing to the SMB share path on your NAS or file server. Create a target endpoint pointing to the Azure file share in your target storage account. Each share pair requires its own source and target endpoint. You can create all endpoints before starting any jobs — this is useful for large migrations where you want to review the full mapping before beginning data transfer.
Create migration jobs and start the transfer
Create a Storage Mover project and define individual migration jobs within it — one per share pair. Review migration settings carefully before starting: copy mode (overwrite vs mirror), conflict resolution, and whether to copy ACLs. Start jobs sequentially or in parallel depending on network capacity and agent count. Monitor progress and copy logs from the Azure portal.
6Run delta job → validate → cutover
Create a Storage Mover project and define individual migration jobs within it — one per share pair. Review migration settings carefully before starting: copy mode (overwrite vs mirror), conflict resolution, and whether to copy ACLs. Start jobs sequentially or in parallel depending on network capacity and agent count. Monitor progress and copy logs from the Azure portal.
Run delta sync, validate, then cut over
Once the initial bulk transfer completes, run a second Storage Mover job in delta mode to capture changes made to the source since the bulk transfer began. Validate a sample of migrated files — check permissions, timestamps, and file content. Schedule the cutover maintenance window, run a final delta job, then redirect DFS-N targets from the source to the Azure file share endpoints.
Once the initial bulk transfer completes, run a second Storage Mover job in delta mode to capture changes made to the source since the bulk transfer began. Validate a sample of migrated files — check permissions, timestamps, and file content. Schedule the cutover maintenance window, run a final delta job, then redirect DFS-N targets from the source to the Azure file share endpoints.
Phase 5–6 — Monitoring at scale: what to track and when to intervene
Figure 6 — Large-scale migration monitoring: the metrics that actually matter
Phase 8 — Post-migration validation: the checks that close the project
A migration is not complete when the data transfer finishes. It is complete when you can demonstrate — with evidence, not assumption — that the Azure file shares match the source across four dimensions: data integrity, permission fidelity, performance baseline, and business continuity.
Figure 7 — Post-migration validation checklist: four dimensions before decommissioning source
A migration is not complete when the data transfer finishes. It is complete when you can demonstrate — with evidence, not assumption — that the Azure file shares match the source across four dimensions: data integrity, permission fidelity, performance baseline, and business continuity.
The production pitfalls that emerge at enterprise scale
Small migrations surface individual problems. Large migrations surface systemic problems. These are the issues that consistently appear at enterprise scale that do not show up in small proof-of-concept migrations.
⚠ Pitfall 1 — IOPS contention when pooling active shares in one storage accountAzure standard HDD storage accounts have shared IOPS and throughput limits across all file shares within the account. If you pool multiple active shares in a single storage account to save cost, peak usage periods can cause shares to throttle each other — and none of them will show an obvious error. Users experience intermittent slowness that looks like a network problem and is actually a storage account IOPS ceiling being hit. The rule: pool only archival or low-activity shares. High-activity shares get their own dedicated storage account. Premium SSD file shares do not have this problem — IOPS are explicitly provisioned per share.
⚡ Pitfall 2 — Azure File Sync scale limits at large namespaceAzure File Sync scales primarily with the number of items (files and folders), not total storage size. The recommended maximum is 100 million items per registered server. For migrations with very large file counts — millions of small files — you may need to split across multiple server endpoints or multiple sync groups rather than placing everything under a single endpoint. The TreeSize tool helps you determine item counts before deployment so you can plan endpoint boundaries before you begin syncing.
⚠ Pitfall 3 — Storage Mover agent network path to source matters enormouslyThe Storage Mover agent reads from the source share over the network and uploads to Azure over the internet. If the agent VM is placed on a different network segment from the source NAS — with a routing hop, a firewall inspection, or a bandwidth-constrained link in between — your effective transfer speed will be limited by the slowest link between the agent and the source, not between the agent and Azure. Deploy the agent VM on the same LAN segment as the source, connected via the fastest available link. A 10GbE local connection between agent and NAS is what allows the agent to saturate a 500Mbps WAN link.
✓ Scale lesson — migrate in waves, not all at onceFor migrations involving more than 10 shares or more than 10TB of active data, migrate in waves rather than attempting to move everything simultaneously. Wave 1 should be your lowest-risk shares — archives, read-only data, small shares with simple ACLs. Validate completely before Wave 2. Wave 2 adds moderate-complexity active shares. Wave 3 is your highest-stakes shares — Finance, HR, anything with complex ACLs or high user sensitivity to outage. This sequencing lets you discover and resolve systemic problems (SID mapping issues, illegal filename patterns, storage account configuration errors) on low-risk data before they affect your most critical shares.
Key takeaways- Use Azure Migrate for assessment before touching any migration tool. Automated discovery in hours replaces weeks of manual inventory. The readiness classification and tier recommendation output directly feeds your share mapping and wave planning decisions.
- Match migration tool to requirement: Storage Mover for one-time NAS migration, AFS for ongoing hybrid sync. Storage Mover is faster because it uses FileREST rather than SMB. AFS is correct only if you need continuous cloud sync or cloud tiering after migration. Do not use AFS for pure one-time migrations — it adds unnecessary long-term infrastructure overhead.
- Active shares need dedicated storage accounts — never pool high-IOPS shares in HDD accounts. Shared IOPS contention is silent, intermittent, and difficult to diagnose after the fact. The per-share cost of a dedicated storage account is lower than the cost of one incident caused by IOPS throttling.
- Migrate in waves, validate completely between waves. Every enterprise migration has at least one systemic problem that Wave 1 surfaces. Discovering it on an archive share is a recoverable situation. Discovering it on your Finance share on cutover weekend is not.
- Validate across all four dimensions before decommissioning source. Data integrity, permission fidelity, performance baseline, and business continuity. All four. With evidence, not assumption. Keep source read-only for a minimum of two weeks after cutover.
- DFS Namespaces is your cutover mechanism — configure it before migration, not at cutover. If you are not already using DFS-N, establish it as part of Phase 3 provisioning. Use it to preserve existing share paths throughout the migration and redirect targets transparently at cutover.
Small migrations surface individual problems. Large migrations surface systemic problems. These are the issues that consistently appear at enterprise scale that do not show up in small proof-of-concept migrations.
Azure standard HDD storage accounts have shared IOPS and throughput limits across all file shares within the account. If you pool multiple active shares in a single storage account to save cost, peak usage periods can cause shares to throttle each other — and none of them will show an obvious error. Users experience intermittent slowness that looks like a network problem and is actually a storage account IOPS ceiling being hit. The rule: pool only archival or low-activity shares. High-activity shares get their own dedicated storage account. Premium SSD file shares do not have this problem — IOPS are explicitly provisioned per share.
Azure File Sync scales primarily with the number of items (files and folders), not total storage size. The recommended maximum is 100 million items per registered server. For migrations with very large file counts — millions of small files — you may need to split across multiple server endpoints or multiple sync groups rather than placing everything under a single endpoint. The TreeSize tool helps you determine item counts before deployment so you can plan endpoint boundaries before you begin syncing.
The Storage Mover agent reads from the source share over the network and uploads to Azure over the internet. If the agent VM is placed on a different network segment from the source NAS — with a routing hop, a firewall inspection, or a bandwidth-constrained link in between — your effective transfer speed will be limited by the slowest link between the agent and the source, not between the agent and Azure. Deploy the agent VM on the same LAN segment as the source, connected via the fastest available link. A 10GbE local connection between agent and NAS is what allows the agent to saturate a 500Mbps WAN link.
For migrations involving more than 10 shares or more than 10TB of active data, migrate in waves rather than attempting to move everything simultaneously. Wave 1 should be your lowest-risk shares — archives, read-only data, small shares with simple ACLs. Validate completely before Wave 2. Wave 2 adds moderate-complexity active shares. Wave 3 is your highest-stakes shares — Finance, HR, anything with complex ACLs or high user sensitivity to outage. This sequencing lets you discover and resolve systemic problems (SID mapping issues, illegal filename patterns, storage account configuration errors) on low-risk data before they affect your most critical shares.
- Use Azure Migrate for assessment before touching any migration tool. Automated discovery in hours replaces weeks of manual inventory. The readiness classification and tier recommendation output directly feeds your share mapping and wave planning decisions.
- Match migration tool to requirement: Storage Mover for one-time NAS migration, AFS for ongoing hybrid sync. Storage Mover is faster because it uses FileREST rather than SMB. AFS is correct only if you need continuous cloud sync or cloud tiering after migration. Do not use AFS for pure one-time migrations — it adds unnecessary long-term infrastructure overhead.
- Active shares need dedicated storage accounts — never pool high-IOPS shares in HDD accounts. Shared IOPS contention is silent, intermittent, and difficult to diagnose after the fact. The per-share cost of a dedicated storage account is lower than the cost of one incident caused by IOPS throttling.
- Migrate in waves, validate completely between waves. Every enterprise migration has at least one systemic problem that Wave 1 surfaces. Discovering it on an archive share is a recoverable situation. Discovering it on your Finance share on cutover weekend is not.
- Validate across all four dimensions before decommissioning source. Data integrity, permission fidelity, performance baseline, and business continuity. All four. With evidence, not assumption. Keep source read-only for a minimum of two weeks after cutover.
- DFS Namespaces is your cutover mechanism — configure it before migration, not at cutover. If you are not already using DFS-N, establish it as part of Phase 3 provisioning. Use it to preserve existing share paths throughout the migration and redirect targets transparently at cutover.