Skip to main content

Task 05 — Storage Configuration

DOCUMENT CATEGORY: Implementation Guide SCOPE: Azure Local Cluster — Post-Deployment Storage PURPOSE: Create Storage Spaces Direct (S2D) volumes on the cluster MASTER REFERENCE: Azure Local Storage Spaces Direct and create the matching storage paths in Azure so they appear as placement targets for virtual machines deployed through Azure Local.

Status: Active

Storage Topology

This task covers two storage topologies:

A hybrid cluster (S2D plus an external SAN attached after deployment) uses Sections 1–3 for the S2D volumes and Task 10: Enable external storage (hybrid) for the SAN, including the host-side configuration that must be done first.

When scenario.storage_architecture is san, the volume script does nothing and exits 0. There is no S2D pool to create volumes in.

Tested by unit tests only

The two toolkit scripts in this task are covered by unit tests. They have not been run on a cluster yet. Run each one with -WhatIf first and read what it plans to do. Run the first real pass on a lab cluster.

The two scripts​

Both scripts are in the toolkit under:

scripts/deploy/04-cluster-deployment/phase-06-post-deployment/
task-05-storage-configuration/powershell/
ScriptWhat it doesWhere it works
New-StorageVolume.ps1Creates the S2D volumes of storage.volumes. Sets the CSV read cache and the pool alert threshold when the file names them.On the cluster, over PowerShell remoting
New-StoragePath.ps1Creates the Azure storage paths of storage.paths.In Azure, with your Azure sign-in

Both scripts:

  • Need PowerShell 7 and read only the master infrastructure.yml.
  • Read no secret. They do not sign in. New-StorageVolume.ps1 connects as the account that runs it (or as -Credential). New-StoragePath.ps1 uses your Connect-AzAccount session.
  • Are safe to run again. What exists is reported and left as it is.
  • Support -WhatIf, which changes nothing.
  • Use exit code 0 for success or nothing to do, 1 for a failed step, and 2 for a value in the file that is missing or not usable.

The older scripts of this task are gone (Invoke-StorageCSV-Orchestrated.ps1, Invoke-StoragePaths-Orchestrated.ps1, New-StorageCSV-Standalone.ps1, New-StoragePaths-Standalone.ps1, Set-StorageConfiguration.ps1 and Set-StorageVolumesConfig.ps1). They read storage.volumes[], which does not exist in the master file. Move any such block to storage.volumes and storage.paths (see Section 1).

Section 1 — Volume Sizing & YAML Verification​

This step should already be complete

Volume sizing and the storage.volumes and storage.paths keys should have been completed during the Discovery & Planning phase. If those values are not in your infrastructure.yml, stop here and complete sizing before proceeding. Both scripts read only the file. Nothing is hardcoded in them.

If sizing was not completed, use the S2D Capacity Calculator:

tools/planning/S2D_Capacity_Calculator.xlsx

The calculator requires:

  • Number of cluster nodes
  • Number and size of capacity drives per node
  • Resiliency type (Two-way Mirror / Three-way Mirror)
  • Target usable capacity per volume

Once you have the outputs, set these keys in the storage: section of your infrastructure.yml before you run any script in this task. The example values are from the master template.

YAML PathExampleDescription
storage.pool.nameSU1_PoolName of the pool. On an Azure Local deployment the pool is SU1_Pool. Leave it empty and the script finds the one S2D pool itself.
storage.pool.thin_provisioning_alert_threshold_percent70Pool share, in percent, at which the thin provisioning alert is raised. Not in the file means not touched.
storage.csv.read_cache_size_mib1024Memory per machine, in MiB, for the CSV in-memory read cache (BlockCacheSize). Not in the file means not touched.
storage.volumes[].namevol-workloads-01Volume name. It becomes C:\ClusterStorage\<name>.
storage.volumes[].size_gib4096Size in GiB (binary units, as Windows counts).
storage.volumes[].resiliencytwo_waytwo_way, three_way, four_way, parity, nested_two_way, mirror_accelerated_parity or nested_mirror_accelerated_parity. Empty means S2D chooses.
storage.volumes[].provisioning_typethinthin or fixed.
storage.volumes[].file_systemrefsrefs (default) or ntfs.
storage.volumes[].parity_percent80Parity share of the two accelerated-parity types only. Default 80.
storage.volumes[].media_typessdssd or hdd. Needed when the machines have both and the resiliency uses tiers.
storage.volumes[].deduplication.typenonenone (default), dedup, compress or dedup_and_compress.
storage.volumes[].deduplication.schedule.start_time22:00Time of day the job starts, as HH:mm.
storage.volumes[].deduplication.schedule.days["Friday", "Saturday"]Days the job runs, Sunday to Saturday, or EveryDay.
storage.volumes[].deduplication.schedule.duration_hours4Longest one run may take, in hours.
storage.paths[].namesp-workloads-01Storage path name: 3 to 64 letters, digits or hyphens.
storage.paths[].pathC:\ClusterStorage\vol-workloads-01\vmsFolder on a cluster shared volume.
cluster.nameiic-azl-01The cluster New-StorageVolume.ps1 connects to.
scenario.storage_architecture, nodess2dWhether there is a pool, and how many machines (for the resiliency check).
hardware.drives.capacity.medianvmeMedia type of the tiers, unless a volume sets media_type.
azure.resource_grouprg-iic-azl-01Resource group where New-StoragePath.ps1 creates the storage paths.
azure.locationeastusAzure region of the storage paths.
azure.custom_locationcl-iic-azl-01Custom location of the instance.
azure.tenant_id, azure.subscription_idGUIDsThe tenant your sign-in must belong to, and the subscription.

The example below is the storage: block of the master template (the SAN part is left out here).

infrastructure.yml (storage, S2D part)
storage:
pool:
name: "SU1_Pool"
thin_provisioning_alert_threshold_percent: 70
csv:
read_cache_size_mib: 1024
volumes:
- name: "vol-workloads-01"
size_gib: 4096
resiliency: "two_way"
provisioning_type: "thin"
file_system: "refs"
parity_percent: 80 # only for the two accelerated-parity types
media_type: "ssd"
deduplication:
type: "none"
schedule:
start_time: "22:00"
days: ["Friday", "Saturday"]
duration_hours: 4
paths:
- name: "sp-workloads-01"
path: "C:\\ClusterStorage\\vol-workloads-01\\vms"
What the file does not list

List only the extra volumes you want. The deployment makes Infrastructure_1 and the UserStorage_<n> volumes itself. The volume script never touches them and refuses those names in the file.

How the volume script reads the file​

  • Resiliency. The script passes what Microsoft Learn describes for New-Volume.

    resiliencyWhat the script passes
    two_way-ResiliencySettingName Mirror -PhysicalDiskRedundancy 1
    three_way-ResiliencySettingName Mirror -PhysicalDiskRedundancy 2 (3 or more machines)
    four_way-ResiliencySettingName Mirror -PhysicalDiskRedundancy 3 (rack aware, 4 or more machines)
    parity-ResiliencySettingName Parity -PhysicalDiskRedundancy 2 (dual parity, 4 or more machines)
    nested_two_wayThe tier NestedMirrorOn<media> (2 machines)
    mirror_accelerated_parityThe tiers MirrorOn<media> and ParityOn<media> (4 or more machines, ReFS)
    nested_mirror_accelerated_parityThe tiers NestedMirrorOn<media> and NestedParityOn<media> (2 machines, ReFS)
    emptyNothing is passed. S2D chooses two-way with 1 or 2 machines and three-way with 3 or more.
  • Pool. The script finds the pool itself. With one S2D pool it uses that one. With more than one it stops and asks you to name the pool in storage.pool.name.

  • Existing volumes. The script never changes, resizes or deletes a volume that exists. It reports AlreadyExists and moves on.

  • Names. UserStorage_<n> and Infrastructure_<n> are refused. A name is 1 to 63 letters, digits, dot, underscore or hyphen.

  • Deduplication and compression are off unless the file says otherwise. The script uses ReFS deduplication (Enable-ReFSDedup), not Windows Data Deduplication. It needs file_system: refs. It sets deduplication on the machine that owns the volume. With a schedule it also sets the job time (Set-ReFSDedupSchedule). Without a schedule, a job runs only when someone starts one.

  • Cache and threshold. read_cache_size_mib takes effect when the volumes next move or come online.


Section 2 — Create the Volumes​

When to use: Initial deployment, repeat runs, and CI/CD. The script connects to the cluster with PowerShell remoting and runs New-Volume there.

Prerequisites:

Verify prerequisites on the management server
# PowerShell 7 or later
$PSVersionTable.PSVersion

# WinRM must be reachable from the management server to the cluster
Test-NetConnection -ComputerName "iic-azl-01" -Port 5985

Run from the toolkit repo root:

Plan first, then create
$script = '.\scripts\deploy\04-cluster-deployment\phase-06-post-deployment\task-05-storage-configuration\powershell\New-StorageVolume.ps1'

# 1. Read the cluster and show what would be created or set. Changes nothing.
& $script -InfrastructureFile .\infrastructure.yml -WhatIf

# 2. Create the volumes that are missing. Pass -Credential to connect as another account.
& $script -InfrastructureFile .\infrastructure.yml
ParameterMeaning
-InfrastructureFileThe master infrastructure.yml (schema 5). Required.
-ComputerNameOptional. The machine to connect to instead of cluster.name, for example one node when the cluster name does not resolve from where you run the script.
-CredentialOptional. The account for the remoting sessions. Without it the account that runs the script is used.
-LogPathOptional. Also append the progress lines to this file. Keep it out of the repository.
-WhatIfRead the cluster and change nothing.

What you see. One line per item with an action: Created, AlreadyExists, Set, AlreadySet, WouldCreate, WouldSet or Failed. Run it again: volumes that exist are reported as AlreadyExists. Exit code 1 means a step failed or the cluster could not be reached. Exit code 2 means a value in the file is missing or not usable.

Tiered volumes and provisioning

For the tier-based resiliency types the provisioning type comes from the tier templates of the pool. The script sets it on the templates for this one volume and puts the old value back afterwards, also when the creation fails.


Section 3 — Create the Storage Paths in Azure​

Storage paths are Azure resources that tell Azure Local where to place VM configuration files, images and disks. Each storage path maps an Azure resource name to a folder on a cluster shared volume.

Never on the infrastructure volume

Do not create a storage path on Infrastructure_1. Microsoft reserves it for Azure Local components. The script refuses a path on it. Use a workload volume.

Create the volume first (Section 2). Storage paths the deployment made are not touched.

When to use: One or two paths, or to check what exists.

Steps:

  1. Open the Azure portal
  2. Go to Azure Local and select your instance (iic-azl-01)
  3. Select Storage paths
  4. Select + Create storage path and fill in:
    • Path: C:\ClusterStorage\vol-workloads-01\vms
    • Name: sp-workloads-01 (3 to 64 letters, digits and hyphens)
  5. Wait for the notification that the storage path is created
  6. Repeat for each entry in storage.paths
The script is faster for many paths

Use the Toolkit Script tab to create all paths in one run instead of clicking through the portal for each one.


Validation​

Run all checks from the management server (or a cluster node for pool/volume checks).

1 — Verify storage pool health
# Run on a cluster node or via PS Remoting to the cluster
Invoke-Command -ComputerName "iic-azl-01" -ScriptBlock {
Get-StoragePool -IsPrimordial $false |
Select-Object FriendlyName, HealthStatus, OperationalStatus,
@{N='AllocatedTB'; E={[math]::Round($_.AllocatedSize/1TB, 2)}},
@{N='FreeTB'; E={[math]::Round(($_.Size - $_.AllocatedSize)/1TB, 2)}}
}
2 — Verify CSV volumes are online
Invoke-Command -ComputerName "iic-azl-01" -ScriptBlock {
Get-ClusterSharedVolume | Select-Object Name, State,
@{N='Path'; E={ $_.SharedVolumeInfo.FriendlyVolumeName }}
}
3 — Verify virtual disk health
Invoke-Command -ComputerName "iic-azl-01" -ScriptBlock {
Get-VirtualDisk | Select-Object FriendlyName, HealthStatus, OperationalStatus,
@{N='SizeGB'; E={[math]::Round($_.Size/1GB, 0)}}
}
4 — Verify Azure storage paths created
az stack-hci-vm storagepath list `
--resource-group "rg-iic-azl-01" `
--query "[].{name:name, path:properties.path, state:properties.provisioningState}" `
-o table

Expected results:

CheckExpected
Storage pool HealthStatusHealthy
Storage pool OperationalStatusOK
Get-ClusterSharedVolume StateOnline for all volumes
Get-VirtualDisk HealthStatusHealthy for all virtual disks
storagepath list provisioningStateSucceeded for all paths
A second run of either scriptEvery item reported as AlreadyExists or AlreadySet

Variables from infrastructure.yml​

VariableConfig PathExample
Storage pool namestorage.pool.nameSU1_Pool
Thin provisioning alertstorage.pool.thin_provisioning_alert_threshold_percent70
CSV read cache (MiB)storage.csv.read_cache_size_mib1024
Volume namestorage.volumes[].namevol-workloads-01
Volume size (GiB)storage.volumes[].size_gib4096
Resiliencystorage.volumes[].resiliencytwo_way
Deduplicationstorage.volumes[].deduplication.typenone
Storage path namestorage.paths[].namesp-workloads-01
Storage path folderstorage.paths[].pathC:\ClusterStorage\vol-workloads-01\vms

Troubleshooting​

IssueCauseResolution
Volume script exits 2 and names storage.volumes[n].nameThe name is UserStorage_<n> or Infrastructure_<n>, is listed twice, or has characters that are not allowedChoose another name
Volume script exits 2 about resiliencyThe resiliency needs more or fewer machines than nodes lists (for example parity with fewer than 4)Choose a resiliency that fits the cluster
Volume script exits 1: more than one storage poolThe cluster has more than one poolSet storage.pool.name
Volume script exits 1: cluster could not be readWinRM is not reachable, or the account has no rights on the clusterTest port 5985, or use -ComputerName with one node, or pass -Credential
Storage path script exits 1: not signed in or wrong tenantNo Connect-AzAccount session, or a session for another tenantConnect-AzAccount -Tenant <azure.tenant_id>
Storage path script exits 2: path on the infrastructure volumeThe path starts with C:\ClusterStorage\Infrastructure_<n>Put the path on a workload volume
An existing volume is not the size or type in the fileThe script never changes an existing volumeChange it by hand, following the Learn volume articles
Storage pool HealthStatus shows DegradedOne or more physical disks are unhealthy or missingCheck disk health: Get-PhysicalDisk | Where-Object HealthStatus -ne Healthy; replace failed disks and initiate repair: Repair-VirtualDisk
CSV volume shows Offline or RedirectedNode owning the volume is offline or network partitionVerify cluster node status: Get-ClusterNode; move CSV ownership: Move-ClusterSharedVolume -Name <csv> -Node <healthy-node>
Storage path creation fails in AzureArc resource bridge unhealthy or missing permissionsVerify bridge: az arcappliance show; ensure the identity can create resources in the resource group


Alternatives​

The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.


SAN Workload LUN Configuration​

This section applies to SAN disaggregated deployments. For a hybrid cluster use Task 10, which also covers the host-side MPIO, vendor registration and iSCSI configuration that must be in place first. Skip this section if using Storage Spaces Direct only — use Sections 1–3 above instead.

After the cluster deployment wizard completes, the infrastructure and performance history LUNs are already claimed by the cluster. This section covers adding workload LUNs as Cluster Shared Volumes. It follows steps 7 to 10 of Microsoft's Connect an external storage array to Azure Local article.

Workload LUNs only

Do not initialize the infrastructure volume or performance history LUN — those were claimed by the deployment wizard. Only initialize and add LUNs designated for VM workload storage.

SAN rules that apply to every LUN you add
  • Present each LUN to all nodes with the same LUN ID; partial presentation is not supported.
  • SAN LUNs are Offline by default (the OfflineShared policy). Disk numbers can differ between nodes, so use UniqueId as the identifier.
  • Format with NTFS and a 64 KB allocation unit for CSV. ReFS is not supported for SAN-backed volumes.
  • Initialize and format on one node only. The cluster then manages multi-node access.
  • Each LUN is dedicated to one CSV and is not shared across clusters. The array must support SCSI-3 Persistent Reservations.

Step 1: Rescan and Verify the SAN Disks on Every Node​

Rescan, list SAN disks and compare UniqueId — run on EVERY cluster node
Invoke-Command -ComputerName "<cluster-node>" -ScriptBlock {
Update-HostStorageCache

# SAN LUNs appear with BusType 'Fibre Channel' or 'iSCSI' (the FC string contains a space)
Get-Disk | Where-Object { $_.BusType -in 'Fibre Channel','iSCSI' } |
Select-Object Number, FriendlyName, Size, OperationalStatus, PartitionStyle, BusType |
Format-Table -AutoSize

# Compare these across all nodes: every node must report the same set of UniqueId values
Get-Disk | Where-Object { $_.BusType -in 'Fibre Channel','iSCSI' } |
Select-Object Number, SerialNumber, UniqueId | Format-Table -AutoSize

# Path count per disk
mpclaim -s -d
}

Identify the workload LUNs by UniqueId and size: PartitionStyle = RAW, not the infrastructure or performance history disks.

Step 2: Initialize and Format Workload LUNs (one node only)​

Initialize and format each workload LUN — run on ONE cluster node
Invoke-Command -ComputerName "<cluster-node>" -ScriptBlock {
$sanDisks = Get-Disk | Where-Object {
$_.BusType -in 'Fibre Channel','iSCSI' -and $_.PartitionStyle -eq 'RAW'
}
foreach ($disk in $sanDisks) {
# SAN LUNs are Offline by default (OfflineShared policy)
Set-Disk -Number $disk.Number -IsOffline $false
Set-Disk -Number $disk.Number -IsReadOnly $false
Initialize-Disk -Number $disk.Number -PartitionStyle GPT
New-Partition -DiskNumber $disk.Number -UseMaximumSize -AssignDriveLetter |
Format-Volume -FileSystem NTFS -AllocationUnitSize 65536 `
-NewFileSystemLabel "SAN-LUN-$($disk.Number)" -Confirm:$false
}
}
Check the list first

The filter takes every RAW SAN disk. If the infrastructure or performance history LUN is somehow still RAW or you have LUNs that are not meant for this cluster, list $sanDisks first and restrict it by UniqueId.

Step 3: Add Workload LUNs to the Cluster and Create CSVs​

Add cluster disk and convert to CSV — run on a cluster node
Invoke-Command -ComputerName "<cluster-node>" -ScriptBlock {
# Add the SAN disks to the failover cluster
Get-ClusterAvailableDisk | Add-ClusterDisk

# Convert only the newly added disks (Available Storage) to CSVs.
# Do not pipe every Physical Disk resource: the infrastructure and
# performance history disks are already CSVs or are cluster-managed.
Get-ClusterResource |
Where-Object { $_.ResourceType -eq 'Physical Disk' -and $_.OwnerGroup -eq 'Available Storage' } |
Add-ClusterSharedVolume

# Verify CSVs and their paths
Get-ClusterSharedVolume | Select-Object Name, State, OwnerNode | Format-Table -AutoSize
Get-ClusterSharedVolume | Select-Object -ExpandProperty SharedVolumeInfo |
Select-Object FriendlyVolumeName
}

# Storage validation (SCSI-3 Persistent Reservation, consistent LUN IDs)
Test-Cluster -Include Storage

Step 4: Register SAN Storage Paths in Azure​

After CSVs are online, create Azure storage paths for them. Create paths for SAN CSVs only — Azure Local manages its own volumes (Infrastructure, UserStorage) automatically. The procedure is the same as Section 3 (Storage Paths) above: it does not depend on the storage topology.

List each SAN CSV folder in storage.paths of your infrastructure.yml and run New-StoragePath.ps1 (Section 3, Toolkit Script tab). The script does not care what is behind the cluster shared volume. It refuses a path on the infrastructure volume.

infrastructure.yml (a storage path on a SAN CSV)
storage:
paths:
- name: "sp-san-01"
path: "C:\\ClusterStorage\\Volume1\\vms"

Portal alternative: the Azure Local resource, Storage paths, + Create storage path, then enter the CSV folder (for example C:\ClusterStorage\Volume1\vms).

The script that creates the SAN volumes themselves does not exist yet. Formatting the LUNs and adding them as CSVs stays manual (Steps 1 to 3 above).

SAN Storage Validation​

Validate SAN storage state
Invoke-Command -ComputerName "<cluster-node>" -ScriptBlock {
# SAN disk health (FC or iSCSI)
Get-PhysicalDisk | Where-Object { $_.BusType -in 'Fibre Channel','iSCSI' } |
Select-Object FriendlyName, HealthStatus, OperationalStatus, Size

# CSV volumes
Get-ClusterSharedVolume | Select-Object Name, State,
@{N='Path'; E={ $_.SharedVolumeInfo.FriendlyVolumeName }}

# MPIO path count
mpclaim -s -d
}

Expected:

CheckExpected
SAN disks HealthStatusHealthy
Get-ClusterSharedVolume StateOnline for all workload volumes
mpclaim -s -d path count≥2 per LUN (2 HBAs, one per fabric, or two iSCSI paths)
UniqueId valuesIdentical set on every node
Test-Cluster -Include StoragePasses (SCSI-3 Persistent Reservations supported)
Azure storage pathsprovisioningState = Succeeded

References:

PreviousUpNext
Task 04: SSH ConnectivityPhase 06 IndexTask 06: Image Downloads

Version Control​

VersionDateAuthorChanges
1.0.02025-03-25Azure Local CloudInitial release
1.1.02026-11-08Azure Local CloudSAN section aligned to Learn 2610 steps 7 to 10 (UniqueId compare, OfflineShared, 64 KB NTFS, one-node initialize, Available Storage filter, Test-Cluster storage, iSCSI)
2.0.02026-11-13Azure Local CloudSections 1 to 3 rewritten for the two toolkit scripts New-StorageVolume.ps1 and New-StoragePath.ps1 and the storage.volumes, storage.paths, storage.pool and storage.csv keys. Removed the six older scripts and the cluster_shared_volumes block. SAN Step 4 uses storage.paths