Skip to content

Disk

Jump to bottom
dscbot edited this page Mar 16, 2024 · 10 revisions

Disk

Parameters

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.

Description

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,SerialNumber

Note: 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.

Dev Drive

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.

What is a Dev Drive volume and how is it different from regular volumes?

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.

What is the default state of the Dev Drive flag in this resource?

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.

Can more than one Dev Drive be mounted at a time?

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.

If I have a non Dev Drive volume that is 50 Gb or more can it be reformatted as a Dev Drive volume?

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

If I don't have any unallocated space available to create a Dev Drive volume, what will happen?

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.

Dev Drive requirements for this resource

There are only five requirements:

  1. 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.
  2. 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 idempotence for 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.

  3. If the size parameter 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.
  4. Currently today, if the size parameter is not entered then the Disk resource will use the maximum space available on the Disk. When the DevDrive flag is set to $true, then we assert that the maximum available free unallocated space on the Disk should be 50 Gb or more in size. This assertion only comes into play if the volume doesn't already exist.
  5. The FSformat parameter must be set to 'ReFS', when the DevDrive flag is set to true. We assert that this is true and throw an exception if it is not.

Testing

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.

Known Issues

Defragsvc Conflict

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.

Null Location

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.

Maximum Supported Partition Size

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.

ReFS on Windows Server 2019

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.

Examples

Example 1

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'
        }
    }
}

Example 2

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'
        }
    }
}

Example 3

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'
        }
    }
}

Example 4

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'
        }
    }
}

Home

General

Clone this wiki locally