-
Notifications
You must be signed in to change notification settings - Fork 52
Disk
| Parameter | Attribute | DataType | Description | Allowed Values |
|---|---|---|---|---|
| DriveLetter | Key | String | Specifies the identifier for which disk to modify. | |
| DiskId | Required | String | Specifies the disk identifier for the disk to modify. | |
| DiskIdType | Write | String | Specifies the identifier type the DiskId contains. Defaults to Number. |
Number, UniqueId, Guid, Location, FriendlyName, SerialNumber
|
| PartitionStyle | Write | String | Specifies the partition style of the disk. Defaults to GPT. |
MBR, GPT
|
| Size | Write | UInt64 | Specifies the size of new volume. Leave empty to use the remaining free space. | |
| FSLabel | Write | String | Define volume label if required. | |
| AllocationUnitSize | Write | UInt32 | Specifies the allocation unit size to use when formatting the volume. | |
| FSFormat | Write | String | Specifies the file system format of the new volume. |
NTFS, ReFS
|
| AllowDestructive | Write | Boolean | Specifies if potentially destructive operations may occur. | |
| ClearDisk | Write | Boolean | Specifies if the disks partition schema should be removed entirely, even if data and OEM partitions are present. Only possible with AllowDestructive enabled. | |
| DevDrive | Write | Boolean | Specifies if the volume should be formatted as a Dev Drive. |
The resource is used to initialize, format and mount the partition/volume as a drive letter. The disk to add the partition/volume to is selected by specifying the DiskId and optionally DiskIdType. The DiskId value can be a Disk Number, Unique Id, Guid, Location, FriendlyName or SerialNumber.
Important: The Disk Number is not a reliable method of selecting a disk because it has been shown to change between reboots in some environments. It is recommended to use the Unique Id if possible.
The Disk Number, Unique Id, Guid, Location, FriendlyName and SerialNumber can be identified for a disk by using the PowerShell command:
Get-Disk | Select-Object -Property FriendlyName,DiskNumber,UniqueId,Guid,Location,SerialNumberNote: The Guid identifier method of specifying disks is only supported as an
identifier for disks with GPT partition table format. If the disk is RAW
(e.g. the disk has been initialized) then the Guid identifier method can not
be used. This is because the Guid for a disk is only assigned once the partition
table for the disk has been created.
The Dev Drive feature is currently available on Windows 11 in builds 10.0.22621.2338 or later. See the Dev Drive documentation for the latest in formation.
Dev Drive volumes from a storage perspective are just like regular ReFS volumes on a Windows machine. The difference However, is that most of the filter drivers except the antivirus filter will not attach to the volume at boot time by default. This is a low-level concept that most users will never need to interact with but for further reading, see the documentation here for further reading.
By default, the Dev Drive flag is set to false. This means that a Dev Drive volume will not be created with the inputted parameters. This is used to create/reconfigure non Dev Drive volumes. Setting the flag to true will attempt to create/reconfigure a volume as a Dev Drive volume using the users' inputted parameters.
Yes, more than one Dev Drive volume can be mounted at a time. You can have as
many Dev Drive volumes as the physical storage amount on the disk permits.
Though, it should be noted, that the minimum size for a single Dev Drive volume
is 50 Gb.
Yes, since the Dev Drive volume is just like any other volume storage wise to the Windows operating system, a non Dev Drive ReFS volume can be reformatted as a Dev Drive volume. An NTFS volume can also be reformatted as a Dev Drive volume. Note, the Disk resource will throw an exception, should you also attempt to resize a ReFS volume while attempting to reformat it as a Dev Drive volume since ReFS volumes cannot be resized. As Dev Drive volumes are also ReFS volumes, they carry the same restrictions, see: Resilient File System (ReFS) overview | Microsoft Learn
The Disk resource uses the Get-PartitionSupportedSize cmdlet to know which volume can be be resized to a safe size to create enough unallocated space for the Dev Drive volume to be created. As long as the size parameter is used, the Disk resource will shrink the first non ReFS Drive whose (MaxSize - MinSize) is greater than or equal to the size entered in the size parameter.
If unallocated space exists but isn't enough to create a Dev Drive volume with, the Disk Resource will only shrink the volume noted above by the minimum size needed, to add to the existing unallocated space so it can be equal to the size parameter. For example, if you wanted to create a new 50 Gb Dev Drive volume on disk 0, and let's say on disk 0 there was only a 'C' drive that was 800 Gb in size. Next to the 'C' drive there was only 40 Gb of free contiguous unallocated space. The Disk resource would shrink the 'C' drive by 10 Gb, creating an addition 10 Gb of unallocated space. Now the unallocated space would be 50 Gb in size. The disk resource would then create a new partition and create the Dev Drive volume into this new partition.
Note: if no size is entered the disk resource will throw an error stating that size is 0 gb, so no partitions can be resized.
There are only five requirements:
- The Dev Drive feature must be available on the machine. We assert that this is true in order to format a Dev Drive volume onto a partition.
- The Dev Drive feature is enabled on the machine.
Note: the feature could be disabled by either a group or system policy, so if ran in an enterprise environment this should be checked. Note, once a Dev Drive volume is created, its functionality will not change and will not be affected should the feature become disabled afterwards. Disablement would only prevent new Dev Drive volumes from being created. However, this could affect the
idempotencefor the Drive. For example, changes to this drive after disablement (e.g., reformatting the volume as an NTFS volume) would not be corrected by rerunning the configuration. Since the feature is disabled, attempting reformat the volume as a Dev Drive volume will throw an error advising you that it is not possible due to the feature being disabled. - If the
sizeparameter is entered, the value must be greater than or equal to 50 Gb in size. We assert that this is true in order to format a Dev Drive volume onto a partition. - Currently today, if the
sizeparameter is not entered then the Disk resource will use the maximum space available on the Disk. When theDevDriveflag is set to$true, then we assert that the maximum available free unallocated space on the Disk should be50 Gb or more in size. This assertion only comes into play if the volume doesn't already exist. - The
FSformatparameter must be set to 'ReFS', when theDevDriveflag is set to true. We assert that this is true and throw an exception if it is not.
Note: Integration tests are not run for the Disk resource when SerialNumber is used since the virtual disk that is created does not have a serial number.
There are no Dev Drive integration tests as the feature is not available in Server 2019 and 2022.
The 'defragsvc' service ('Optimize Drives') may cause the following errors when enabled with this resource. The following error may occur when testing the state of the resource:
PartitionSupportedSize
+ CategoryInfo : NotSpecified: (StorageWMI:) [], CimException
+ FullyQualifiedErrorId : StorageWMI 4,Get-PartitionSupportedSize
+ PSComputerName : localhost
The 'defragsvc' service should be stopped and set to manual start up to prevent
this error. Use the Service resource in either the 'xPSDesiredStateConfgiuration'
or 'PSDSCResources' resource module to set the 'defragsvc' service is always
stopped and set to manual start up.
The Location for a disk may be null for some types of disk,
e.g. file-based virtual disks. Physical disks or Virtual disks provided via a
hypervisor or other hardware virtualization platform should not be affected.
On some disks the maximum supported partition size may differ from the actual size of a partition created when specifying the maximum size. This difference in reported size is always less than 1MB, so if the reported maximum supported partition size is less than 1MB then the partition will be considered to be in the correct state. This is a work around for this issue that has been reported on user voice and also discussed in issue #181.
On Windows Server 2019 (build 17763 and above), Format-Volume throws an
'Invalid Parameter' exception when called with ReFS as the FileSystem
parameter. This results in an 'Invalid Parameter' exception being thrown
in the Set in the 'Disk' resource.
There is currently no known work around for this issue. It is being tracked
in issue #227.
This configuration will wait for disk 2 to become available, and then make the disk available as two new formatted volumes, 'G' and 'J', with 'J' using all available space after 'G' has been created. It also creates a new ReFS formated volume on disk 3 attached as drive letter 'S'.
Configuration Disk_InitializeDataDisk
{
Import-DSCResource -ModuleName StorageDsc
Node localhost
{
WaitForDisk Disk2
{
DiskId = 2
RetryIntervalSec = 60
RetryCount = 60
}
Disk GVolume
{
DiskId = 2
DriveLetter = 'G'
Size = 10737418240
DependsOn = '[WaitForDisk]Disk2'
}
Disk JVolume
{
DiskId = 2
DriveLetter = 'J'
FSLabel = 'Data'
DependsOn = '[Disk]GVolume'
}
WaitForDisk Disk3
{
DiskId = 3
RetryIntervalSec = 60
RetryCount = 60
}
Disk SVolume
{
DiskId = 3
DriveLetter = 'S'
Size = 107374182400
FSFormat = 'ReFS'
AllocationUnitSize = 64KB
DependsOn = '[WaitForDisk]Disk3'
}
}
}This configuration will wait for disk 2 with Unique Id '5E1E50A401000000001517FFFF0AEB84' to become available, and then make the disk available as two new formatted volumes, 'G' and 'J', with 'J' using all available space after 'G' has been created. It also creates a new ReFS formated volume on disk 3 with Unique Id '5E1E50A4010000000029AB39450AC9A5' attached as drive letter 'S'.
Configuration Disk_InitializeDataDiskUsingUniqueId
{
Import-DSCResource -ModuleName StorageDsc
Node localhost
{
WaitForDisk Disk2
{
DiskId = '5E1E50A401000000001517FFFF0AEB84' # Disk 2
DiskIdType = 'UniqueId'
RetryIntervalSec = 60
RetryCount = 60
}
Disk GVolume
{
DiskId = '5E1E50A401000000001517FFFF0AEB84' # Disk 2
DiskIdType = 'UniqueId'
DriveLetter = 'G'
Size = 10GB
DependsOn = '[WaitForDisk]Disk2'
}
Disk JVolume
{
DiskId = '5E1E50A401000000001517FFFF0AEB84' # Disk 2
DiskIdType = 'UniqueId'
DriveLetter = 'J'
FSLabel = 'Data'
DependsOn = '[Disk]GVolume'
}
WaitForDisk Disk3
{
DiskId = '5E1E50A4010000000029AB39450AC9A5' # Disk 3
DiskIdType = 'UniqueId'
RetryIntervalSec = 60
RetryCount = 60
}
Disk SVolume
{
DiskId = '5E1E50A4010000000029AB39450AC9A5' # Disk 3
DiskIdType = 'UniqueId'
DriveLetter = 'S'
Size = 100GB
FSFormat = 'ReFS'
AllocationUnitSize = 64KB
DependsOn = '[WaitForDisk]Disk3'
}
}
}For this scenario we want to create two 60 Gb Dev Drive volumes. We know that disk 2 has 3 existing NTFS volumes and we prefer not to remove them. At most we only want the disk DSC resource to shrink any of them should there not be enough space for any of the Dev Drive volumes to be created. We also know that the the 3 existing volumes are 100Gb, 200Gb and 300Gb in size and disk 2 is 600 Gb in size. Since all the space is being used by the existing volumes, The Disk Dsc resource will resize the existing volumes to create space for our new Dev Drive volumes. An example of what could happen is the Disk resource could resize the 300Gb volume to 240Gb for the first Dev Drive volume and then resize the 240Gb volume again to 180Gb for the second. Thats just one combination, the disk Dsc resource uses the Get-PartitionSupportedSize cmdlet to know which volume can be be resized to a safe size to create enough unallocated space for the Dev Drive volume to be created. Note: ReFS volumes cannot be resized, so if the existing volumes were all ReFS volumes, the Disk Dsc resource would not be able to resize any volumes and would instead throw an exception.
This configuration below will wait for disk 2 to become available, and then create two new 60 Gb Dev Drive volumes, 'E' and 'F'. The volumes will be formatted as ReFS volumes and labeled 'Dev Drive 1' and 'Dev Drive 2' respectively. Note: setting 'AllowDestructive' to $true will not cause the disk to be cleared, as the flag is only used when there is a need to resize an existing partition. It is used as confirmation that you agree to the resizing which will create the necessary space for the Dev Drive volume. This flag is NOT needed if you already know there is enough unallocated space on the disk to create the Dev Drive volume. If this flag is not used and there is not enough space to create the Dev Drive volume an error will be thrown and the Dev Drive will not be created. Its important to be very careful not to add the 'ClearDisk' flag while using the 'AllowDestructive' flag, as this will cause the disk to be cleared, and all data lost on the disk (even existing volumes).
Configuration Disk_CreateDevDriveOnDiskWithExistingPartitions
{
Import-DSCResource -ModuleName StorageDsc
Node localhost
{
WaitForDisk Disk2
{
DiskId = '5E1E50A401000000001517FFFF0AEB84' # Disk 2
DiskIdType = 'UniqueId'
RetryIntervalSec = 60
RetryCount = 60
}
# Will create a Dev Drive volume of 60 Gb called Dev Drive 1.
Disk DevDrive1
{
DiskId = '5E1E50A401000000001517FFFF0AEB84'
DiskIdType = 'UniqueId'
DriveLetter = 'E'
FSFormat = 'ReFS'
FSLabel = 'DevDrive 1'
DevDrive = $true
AllowDestructive = $true
Size = 60Gb
DependsOn = '[WaitForDisk]Disk2'
}
# Will create a Dev Drive volume of 60 Gb called Dev Drive 2.
Disk DevDrive2
{
DiskId = '5E1E50A401000000001517FFFF0AEB84'
DiskIdType = 'UniqueId'
DriveLetter = 'F'
FSFormat = 'ReFS'
FSLabel = 'DevDrive 2'
DevDrive = $true
AllowDestructive = $true
Size = 60Gb
DependsOn = '[Disk]DevDrive1'
}
}
}For this scenario we want to create 2 Non Dev Drive volumes and 2 Dev Drive volumes on a new 1 Tb disk (disk 1) with no partitions. The first non Dev Drive volume will be an NTFS volume of 100 Gb called 'Data'. The second non Dev Drive volume will be a ReFS volume of 200 Gb called 'Logs'. The first Dev Drive volume will be a ReFS volume of 300 Gb called 'Dev Drive 1'. The second Dev Drive volume will be a ReFS volume of 400 Gb called 'Dev Drive 2'. Note: The Dev Drive volumes will be created after the non Dev Drive volumes are created but the order does not matter, we could have created the Dev Drive volumes first and then the non Dev Drive volumes or even interleave them. Since this is a new disk and we know there are no existing partitions, we do not need to set the 'AllowDestructive' flag for the Dev Drive volumes like in 3-Disk_CreateDevDriveOnDiskWithExistingPartitions.ps1.
This configuration below will wait for disk 1 to become available, and then create two new non Dev Drive volumes called Data and Logs with Drive letters G and J respectively. The D drive is an NTFS drive and the J drive is an ReFS drive. It also create two new Dev Drive volumes which are assigned drive letters K and L respectively. The Dev Drive volumes are formatted as ReFS volumes and labeled 'Dev Drive 1' and 'Dev Drive 2' respectively.
Configuration Disk_InitializeDiskWithMultipleDrivesIncludingDevDrives
{
Import-DSCResource -ModuleName StorageDsc
Node localhost
{
WaitForDisk Disk1
{
DiskId = '5E1E50A401000000001517FFFF0AEB81' # Disk 1
DiskIdType = 'UniqueId'
RetryIntervalSec = 60
RetryCount = 60
}
# Will create a NTFS volume of 100 Gb called Data.
Disk DataVolume
{
DiskId = '5E1E50A401000000001517FFFF0AEB81'
DiskIdType = 'UniqueId'
DriveLetter = 'G'
FSFormat = 'NTFS'
FSLabel = 'Data'
Size = 100Gb
DependsOn = '[WaitForDisk]Disk1'
}
# Will create a ReFS volume of 200 Gb called Logs.
Disk LogsVolume
{
DiskId = '5E1E50A401000000001517FFFF0AEB81'
DiskIdType = 'UniqueId'
DriveLetter = 'J'
FSFormat = 'ReFS'
FSLabel = 'Logs'
Size = 200Gb
DependsOn = '[Disk]DataVolume'
}
# Will create a Dev Drive volume of 300 Gb called Dev Drive 1.
Disk DevDrive1
{
DiskId = '5E1E50A401000000001517FFFF0AEB81'
DiskIdType = 'UniqueId'
DriveLetter = 'K'
FSFormat = 'ReFS'
FSLabel = 'DevDrive 1'
DevDrive = $true
Size = 300Gb
DependsOn = '[Disk]LogsVolume'
}
# Will create a Dev Drive volume of 400 Gb called Dev Drive 2.
Disk DevDrive2
{
DiskId = '5E1E50A401000000001517FFFF0AEB81'
DiskIdType = 'UniqueId'
DriveLetter = 'L'
FSFormat = 'ReFS'
FSLabel = 'DevDrive 2'
DevDrive = $true
Size = 400Gb
DependsOn = '[Disk]DevDrive1'
}
}
}