Azure: What We Got Wrong Moving File Servers to Azure Files

#!/usr/bin/env bash
# share-latency.sh: compare end-to-end and service latency for a pilot share.
set -euo pipefail

SUB="<subscription-id>"
RG="<resource-group>"
ACCOUNT="<storage-account>"
FILE_SERVICE="/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.Storage/storageAccounts/$ACCOUNT/fileServices/default"

# Hourly averages over the last 7 days, split by SMB/REST operation name.
az monitor metrics list \
  --resource "$FILE_SERVICE" \
  --metrics SuccessE2ELatency SuccessServerLatency \
  --dimension ApiName \
  --aggregation Average \
  --interval 1h \
  --offset 7d \
  --output table

#!/usr/bin/env bash
# new-files-pilot.sh: HDD provisioned v2 share behind a private endpoint, public endpoint
# denied except for trusted Azure services.
set -euo pipefail

RG="<resource-group>"
ACCOUNT="<storage-account>"          # 3-24 lowercase letters and numbers
REGION="eastus2"
SHARE="finance"
VNET_RG="<vnet-resource-group>"
VNET="<vnet-name>"
SUBNET="<private-endpoint-subnet>"

az storage account create \
  --resource-group "$RG" --name "$ACCOUNT" --location "$REGION" \
  --kind FileStorage --sku StandardV2_LRS --output none

# Omitting --provisioned-iops and --provisioned-bandwidth-mibps uses the recommended values.
az storage share-rm create \
  --resource-group "$RG" --storage-account "$ACCOUNT" --name "$SHARE" \
  --quota 1024 --enabled-protocols SMB --output none

ACCOUNT_ID=$(az storage account show --resource-group "$RG" --name "$ACCOUNT" --query id --output tsv)
VNET_ID=$(az network vnet show --resource-group "$VNET_RG" --name "$VNET" --query id --output tsv)
SUBNET_ID=$(az network vnet subnet show --resource-group "$VNET_RG" --vnet-name "$VNET" --name "$SUBNET" --query id --output tsv)

az network vnet subnet update --ids "$SUBNET_ID" --disable-private-endpoint-network-policies --output none

PE_ID=$(az network private-endpoint create \
  --resource-group "$RG" --name "$ACCOUNT-pe" --location "$REGION" \
  --subnet "$SUBNET_ID" --private-connection-resource-id "$ACCOUNT_ID" \
  --group-id file --connection-name "$ACCOUNT-conn" --query id --output tsv)

# Private DNS so <account>.file.core.windows.net resolves to the private IP.
ZONE="privatelink.file.core.windows.net"
az network private-dns zone create --resource-group "$VNET_RG" --name "$ZONE" --output none
az network private-dns link vnet create --resource-group "$VNET_RG" --zone-name "$ZONE" \
  --name "$VNET-files-link" --virtual-network "$VNET_ID" --registration-enabled false --output none

NIC_ID=$(az network private-endpoint show --ids "$PE_ID" --query "networkInterfaces[0].id" --output tsv)
PE_IP=$(az network nic show --ids "$NIC_ID" --query "ipConfigurations[0].privateIPAddress" --output tsv)
az network private-dns record-set a create --resource-group "$VNET_RG" --zone-name "$ZONE" \
  --name "$ACCOUNT" --output none
az network private-dns record-set a add-record --resource-group "$VNET_RG" --zone-name "$ZONE" \
  --record-set-name "$ACCOUNT" --ipv4-address "$PE_IP" --output none

# Deny the public endpoint; AzureServices bypass keeps Azure File Sync working.
az storage account update --resource-group "$RG" --name "$ACCOUNT" \
  --default-action Deny --bypass AzureServices --output none

<#
.SYNOPSIS
    Registers a storage account in AD DS and grants share-level access to one group.
.DESCRIPTION
    Uses AzFilesHybrid Join-AzStorageAccount to create the computer account that
    represents the storage account, assigns a share-level RBAC role to a synced
    group on one share, and runs the AzFilesHybrid diagnostics.
.PARAMETER SubscriptionId
    Subscription that holds the storage account.
.PARAMETER ResourceGroupName
    Resource group of the storage account.
.PARAMETER StorageAccountName
    Storage account to join.
.PARAMETER SamAccountName
    Name of the AD computer object, 15 characters or less, no trailing $.
.PARAMETER OuDistinguishedName
    OU for the computer object. Use an OU without computer password expiration.
.PARAMETER ShareName
    Share to grant access on.
.PARAMETER GroupObjectId
    Object ID of the synced Entra group that gets Storage File Data SMB Share Contributor.
.EXAMPLE
    .\Join-FilesPilot.ps1 -SubscriptionId "<subscription-id>" -ResourceGroupName "<rg>" -StorageAccountName "<account>" -SamAccountName "<account>" -OuDistinguishedName "OU=AzureFiles,DC=contoso,DC=com" -ShareName "finance" -GroupObjectId "<group-object-id>"
.NOTES
    Author  : Thomas Lasswell (https://www.techcolumnist.com)
    Version : 1.0 (2026-04-22)
    Requires: Windows PowerShell 5.1, Az.Accounts, Az.Storage 8.1.0+, Az.Resources, AzFilesHybrid, ActiveDirectory module
#>
param (
    [Parameter(Mandatory = $true)] [string] $SubscriptionId,
    [Parameter(Mandatory = $true)] [string] $ResourceGroupName,
    [Parameter(Mandatory = $true)] [string] $StorageAccountName,
    [Parameter(Mandatory = $true)] [string] $SamAccountName,
    [Parameter(Mandatory = $true)] [string] $OuDistinguishedName,
    [Parameter(Mandatory = $true)] [string] $ShareName,
    [Parameter(Mandatory = $true)] [string] $GroupObjectId
)

Import-Module -Name AzFilesHybrid
Connect-AzAccount | Out-Null
Select-AzSubscription -SubscriptionId $SubscriptionId | Out-Null

# Create the AD computer account and enable AD DS authentication on the account.
Join-AzStorageAccount `
    -ResourceGroupName $ResourceGroupName `
    -StorageAccountName $StorageAccountName `
    -SamAccountName $SamAccountName `
    -DomainAccountType "ComputerAccount" `
    -OrganizationalUnitDistinguishedName $OuDistinguishedName

# Share-level permission for one synced group, scoped to one share.
$scope = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.Storage/storageAccounts/$StorageAccountName/fileServices/default/fileshares/$ShareName"
New-AzRoleAssignment -ObjectId $GroupObjectId -RoleDefinitionName "Storage File Data SMB Share Contributor" -Scope $scope | Out-Null

# Confirm the identity source, then run the built-in checks as the signed-in AD user.
$account = Get-AzStorageAccount -ResourceGroupName $ResourceGroupName -Name $StorageAccountName
$account.AzureFilesIdentityBasedAuth.DirectoryServiceOptions
Debug-AzStorageAccountAuth -StorageAccountName $StorageAccountName -ResourceGroupName $ResourceGroupName -Verbose

<#
.SYNOPSIS
    Runs one robocopy migration pass for every share listed in a CSV.
.DESCRIPTION
    Reads a CSV with Source and Target columns (UNC paths), runs robocopy with the
    switches from Microsoft's Azure Files migration guide, writes one Unicode log per
    share and pass, and reports any share whose exit code is 8 or higher.
.PARAMETER MappingFile
    CSV with Source and Target columns.
.PARAMETER LogFolder
    Folder for robocopy logs.
.PARAMETER Threads
    Value for /MT. Microsoft suggests 8-20 for the first pass and roughly the core count after.
.PARAMETER ListOnly
    Adds /L so robocopy only lists what it would copy or purge.
.EXAMPLE
    .\Invoke-ShareMigration.ps1 -MappingFile .\shares.csv -LogFolder D:\MigrationLogs -Threads 16
.NOTES
    Author  : Thomas Lasswell (https://www.techcolumnist.com)
    Version : 1.0 (2026-04-22)
    Requires: elevated session, Windows Server 2022 or newer recommended, target shares mounted with admin-level access
#>
param (
    [Parameter(Mandatory = $true)] [string] $MappingFile,
    [Parameter(Mandatory = $true)] [string] $LogFolder,
    [int] $Threads = 16,
    [switch] $ListOnly
)

New-Item -Path $LogFolder -ItemType Directory -Force | Out-Null
$stamp = Get-Date -Format "yyyyMMdd-HHmm"
$results = @()

foreach ($row in (Import-Csv -Path $MappingFile)) {
    $name = ($row.Source.TrimEnd("\") -split "\\")[-1]
    $log = Join-Path -Path $LogFolder -ChildPath "$name-$stamp.log"

    $arguments = @(
        $row.Source, $row.Target,
        "/MT:$Threads", "/R:2", "/W:1", "/B", "/MIR", "/IT",
        "/COPY:DATSO", "/DCOPY:DAT", "/NP", "/NFL", "/NDL",
        "/XD", "System Volume Information",
        "/UNILOG:$log"
    )
    if ($ListOnly) {
        $arguments += "/L"
    }

    $started = Get-Date
    & robocopy.exe @arguments | Out-Null
    $code = $LASTEXITCODE

    $results += [pscustomobject]@{
        Share    = $name
        ExitCode = $code
        Result   = if ($code -ge 8) { "FAILED" } else { "OK" }
        Minutes  = [math]::Round(((Get-Date) - $started).TotalMinutes, 1)
        Log      = $log
    }
}

$results | Format-Table -AutoSize
if ($results | Where-Object { $_.ExitCode -ge 8 }) {
    Write-Warning "One or more shares had copy failures. Check the logs, then run another pass."
}

<#
.SYNOPSIS
    Excludes a folder from cloud tiering and recalls anything in it that is already tiered.
.DESCRIPTION
    Sets the Azure File Sync GhostingExclusionList registry value, restarts FileSyncSvc
    so the exclusion takes effect, then runs Invoke-StorageSyncFileRecall on the folder.
.PARAMETER FolderPath
    Folder under a server endpoint to keep local, for example D:\Shares\Projects\Active.
.EXAMPLE
    .\Set-TieringExclusion.ps1 -FolderPath "D:\Shares\Projects\Active"
.NOTES
    Author  : Thomas Lasswell (https://www.techcolumnist.com)
    Version : 1.0 (2026-04-22)
    Requires: Azure File Sync agent, elevated session. On a failover cluster use the Cluster\StorageSync registry path instead.
#>
param (
    [Parameter(Mandatory = $true)] [string] $FolderPath
)

$key = "HKLM:\SOFTWARE\Microsoft\Azure\StorageSync"
# The value is one pipe-separated string; append instead of overwriting existing exclusions.
$current = (Get-ItemProperty -Path $key -Name "GhostingExclusionList" -ErrorAction SilentlyContinue).GhostingExclusionList
# Paths are stored with doubled backslashes, and ^ $ ( ) [ ] { } + need a backslash escape.
$escaped = $FolderPath.Replace("\", "\\") -replace '([\^\$\(\)\[\]\{\}\+])', '\$1'
$entries = @($current -split "\|" | Where-Object { $_ }) + $escaped | Select-Object -Unique
Set-ItemProperty -Path $key -Name "GhostingExclusionList" -Value ($entries -join "|") -Type String

Restart-Service -Name "FileSyncSvc"

# Exclusions don't apply to files that are already tiered, so recall them now.
Import-Module "C:\Program Files\Azure\StorageSyncAgent\StorageSync.Management.ServerCmdlets.dll"
Invoke-StorageSyncFileRecall -Path $FolderPath -ThreadCount 8 -PerFileRetryCount 3 -PerFileRetryDelaySeconds 10