DSCResources/DSC_Disk/en-US/about_Disk.help.txt
|
.NAME
Disk .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: `powershell 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. # 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. ## 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: `text 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 https://windowsserver.uservoice.com/forums/301869-powershell/suggestions/36967870-get-partitionsupportedsize-and-msft-partition-clas that has been reported on user voice and also discussed in https://github.com/dsccommunity/StorageDsc/issues/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 https://github.com/dsccommunity/StorageDsc/issues/227. .PARAMETER DriveLetter Key - String Specifies the identifier for which disk to modify. .PARAMETER DiskId Required - String Specifies the disk identifier for the disk to modify. .PARAMETER DiskIdType Write - String Allowed values: Number, UniqueId, Guid, Location, FriendlyName, SerialNumber Specifies the identifier type the DiskId contains. Defaults to Number. .PARAMETER PartitionStyle Write - String Allowed values: MBR, GPT Specifies the partition style of the disk. Defaults to GPT. .PARAMETER Size Write - UInt64 Specifies the size of new volume. Leave empty to use the remaining free space. .PARAMETER FSLabel Write - String Define volume label if required. .PARAMETER AllocationUnitSize Write - UInt32 Specifies the allocation unit size to use when formatting the volume. .PARAMETER FSFormat Write - String Allowed values: NTFS, ReFS Specifies the file system format of the new volume. .PARAMETER AllowDestructive Write - Boolean Specifies if potentially destructive operations may occur. .PARAMETER 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. .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' } } } |