VirtualHardDisk

VirtualHardDisk

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
FilePath	Key	String	Specifies the full path to the virtual hard disk file that will be created and attached. This must include the extension, and the extension must match the disk format.
DiskSize	Write	UInt64	Specifies the size of virtual hard disk to create if it doesn't exist and Ensure is present.
DiskType	Write	String	Specifies the disk type of virtual hard disk to create if it doesn't exist and Ensure is present.	Fixed, Dynamic
DiskFormat	Write	String	Specifies the disk format the virtual hard disk should use or create if it does not exist and Ensure is present. Defaults to Vhdx.	Vhd, Vhdx
Ensure	Write	String	Determines whether the virtual hard disk should be created and attached or should be detached if it exists.	Present, Absent
Attached	Read	Boolean	Returns whether or not the virtual hard disk is mounted to the system.
DiskNumber	Read	UInt32	Returns the disk number of the virtual hard disk if it is mounted to the system.

Description

The resource is used to create a virtual hard disk and attach it to the system.

There are 2 high level scenarios, one where the user uses the 'Present' flag and the second when the user uses the 'Absent' flag in the resource.

1. When the 'Present' flag is used the resource checks if the virtual hard disk is on the machine using the file path that is entered.
   1. If the parameters are valid but the file path does not exist. The resource will attempt to create and attach the virtual hard disk to the system. Note: only paths with drive letters are accepted e.g C:\Myfolder\newVirtFile.vhdx, or D:\newVirtFile.vhd, etc.
   2. If the file path is confirmed to be the location of a real virtual hard disk file, and it is attached to the system the resource will do nothing.
   3. If the file path is confirmed to be the location of a real virtual hard disk file, but is not attached, the resource will attach the virtual hard disk to the system.
   4. If the file path does exist but is not a real file path to a virtual hard disk file, the resource will throw an error.
2. When the 'Absent' flag is used the resource checks if the virtual disk is on the machine using the file path that is entered.
   1. If the file path is confirmed to be the location of a real virtual hard disk file. The resource will check if the virtual hard disk is attached. If it is attached, the resource will detach the virtual hard disk from the system.
   2. If the location is a real virtual hard disk but the virtual hard disk is detached from the system, the resource will do nothing.
   3. If the parameters are valid but the file path is a path to a virtual hard disk file that doesn't exist, the resource will do nothing.
   4. The resource does not delete a virtual hard disk file, that already exists on the system prior to the Set-TargetResource function being called. It will only detach the virtual hard disk from the system. The file will remain, this is to prevent accidental deletions.

Note: If the file path to the .vhd or .vhdx file is real and exists but is not attached. The resource will simply attach it. Even if the DiskSize and DiskType parameters are different. These values are currently only useful for creation. Additional functionality would need to be added to resize or change the virtual disk's type after creation.

See the Limitations section for more limitations.

How does this differ from the DSC_VHD in the Hyper-V Dsc?

This DSC_VirtualHardDisk resource does not rely on the Hyper-V Windows feature being enabled to allow users to use the resource. Unlike the DSC_VHD, users can use this resource right out of the box assuming they are running at least Windows 8.1 / Windows Server 2008 R2 or later. The resource uses the publicly available Win32 virtual disk apis, to create and attach a virtual hard disk file (.vhd and .vhdx) to the system. See more information about the apis here.

Warning: Using both the DSC_VirtualHardDisk and DSC_VHD resources in the same config/machine could result in an invalid config.

Limitations

1. The resource only supports .vhd and .vhdx files. No other virtual hard disk file extension is supported at this time.
2. The ability to expand the max size of the virtual hard disk after its creation is not currently included in this resource.
3. The ability to shrink the max size of the virtual hard disk after its creation is not currently included in this resource.
4. The resource uses default values internally to create the virtual hard disk file that are not provided in the Get\Test\Set Methods. Values such as:
   1. The ability to set the block size of the virtual hard disk in bytes.
   2. The ability to set the sector size of the virtual hard disk in bytes.
   3. The ability to associate the new virtual hard disk with an existing virtual hard disk.
   4. The ability to specify a resiliency guid for the virtual hard disk.
   5. The ability to set a unique Id for the virtual hard disk and not use one generated by the system.
   6. The ability to prepopulate a new virtual disk with data from an existing virtual disk.

See virtdisk.h to read about what the Win32 api supports. This resource could in theory support all of these, as the parameters just need to be passed to the the CreateVirtualDisk Win32 function call in the resource. So additional help from the community if any of these are wanted, is welcomed.

Examples

Example 1

This configuration will create a fixed sized virtual disk that is 40Gb in size and will format a NTFS volume named 'new volume' that uses the drive letter E. If the folder path in the FilePath property does not exist, it will be created.

Configuration VirtualHardDisk_CreateFixedSizedVirtualDisk
{
    Import-DSCResource -ModuleName StorageDsc

    Node localhost
    {
          # Create new virtual disk
          VirtualHardDisk newVhd
          {
            FilePath = 'C:\myVhds\virtDisk1.vhd'
            DiskSize = 40Gb
            DiskFormat = 'Vhd'
            DiskType = 'Fixed'
            Ensure = 'Present'
          }

          # Create new volume onto the new virtual disk
          Disk Volume1
          {
            DiskId = 'C:\myVhds\virtDisk1.vhd'
            DiskIdType = 'Location'
            DriveLetter = 'E'
            FSLabel = 'new volume'
            Size = 20Gb
            DependsOn = '[VirtualHardDisk]newVhd'
          }
    }
}

Example 2

This configuration will create a dynamically sized virtual hard disk that has a max size of 80Gb and will format a RefS volume named 'new volume 2' that uses the drive letter F, onto the newly created virtual hard disk. If the folder path in the FilePath property does not exist, it will be created.

Configuration VirtualHardDisk_CreateDynamicallyExpandingVirtualDisk
{
    Import-DSCResource -ModuleName StorageDsc

    Node localhost
    {
          # Create new virtual disk
          VirtualHardDisk newVhd2
          {
            FilePath = 'C:\myVhds\virtDisk2.vhdx'
            DiskSize = 80Gb
            DiskFormat = 'Vhdx'
            DiskType = 'Dynamic'
            Ensure = 'Present'
          }

          # Create new volume onto the new virtual disk
          Disk Volume1
          {
            DiskId = 'C:\myVhds\virtDisk2.vhdx'
            DiskIdType = 'Location'
            DriveLetter = 'F'
            FSLabel = 'new volume 2'
            FSFormat = 'ReFS'
            Size = 20Gb
            DependsOn = '[VirtualHardDisk]newVhd2'
          }
    }
}