xHyper-V

The xHyper-V module contains DSC resources for deployment and configuration of Hyper-V hosts, virtual machines and related resources.

Code of Conduct

This project has adopted this Code of Conduct.

Releases

For each merge to the branch master a preview release will be deployed to PowerShell Gallery. Periodically a release version tag will be pushed which will deploy a full release to PowerShell Gallery.

Contributing

Please check out common DSC Community contributing guidelines.

Change log

A full list of changes in each version can be found in the change log.

Resources

xVHD manages VHDs in a Hyper-V host.
xVhdFile manages files or directories in a VHD. You can use it to copy files/folders to the VHD, remove files/folders from a VHD, and change attributes of a file in a VHD (e.g. change a file attribute to 'ReadOnly' or 'Hidden'). This resource is particularly useful when bootstrapping DSC Configurations into a VM.
xVMDvdDrive manages DVD drives attached to a Hyper-V virtual machine.
xVMHardDiskDrive manages VHD(X)s attached to a Hyper-V virtual machine.
xVMHost manages Hyper-V host settings.
xVMHyperV manages VMs in a Hyper-V host.
xVMNetworkAdapter manages VMNetadapters attached to a Hyper-V virtual machine or the management OS.
xVMProcessor manages Hyper-V virtual machine processor options.
xVMScsiController manages the SCSI controllers attached to a Hyper-V virtual machine.
xVMSwitch manages virtual switches in a Hyper-V host.

xVHD

Manages VHDs in a Hyper-V host.

Requirements for xVHD

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVHD

[String] Name (Key): The desired VHD file name.
[String] Path (Key): The desired Path where the VHD will be created.
[String] ParentPath (Write): Parent VHD file path, for differencing disk.
[Uint64] MaximumSizeBytes (Write): Maximum size of VHD to be created.
[String] Generation (Write): Virtual disk format. The default value is Vhd. { Vhd | Vhdx }.
[String] Type (Write): Virtual disk type. The default value is Dynamic. { Dynamic | Fixed | Differencing }.
[String] Ensure (Write): Ensures that the VHD is Present or Absent. The default value is Present. { Present | Absent }.

Read-Only Properties from Get-TargetResource for xVHD

[String] ID (Read): Virtual Disk Identifier.
[String] Type (Read): Type of Vhd - Dynamic, Fixed, Differencing.
[Uint64] FileSizeBytes (Read): Current size of the VHD.
[Boolean] IsAttached (Read): Is the VHD attached to a VM or not.

Examples xVHD

xVhdFile

Manages files or directories in a VHD. You can use it to copy files/folders to the VHD, remove files/folders from a VHD, and change attributes of a file in a VHD (e.g. change a file attribute to 'ReadOnly' or 'Hidden'). This resource is particularly useful when bootstrapping DSC Configurations into a VM.

Requirements for xVhdFile

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVhdFile

[String] VhdPath (Key): Path to the VHD.
[MSFT_xFileDirectory[]] FileDirectory (Required): The FileDirectory objects to copy to the VHD (as used in the "File" resource). Please see the Examples section for more details.
[String] CheckSum (Write): Indicates the checksum type to use when determining whether two files are the same. The default value is ModifiedDate. { ModifiedDate | SHA-1 | SHA-256 | SHA-512 }.

MSFT_xFileDirectory Class

[String] DestinationPath (Required): Indicates the location where you want to ensure the state for a file or directory.
[String] SourcePath (Write): Indicates the path from which to copy the file or folder resource.
[String] Ensure (Write): Indicates if the file or directory exists. Set this property to "Absent" to ensure that the file or directory does not exist. Set it to "Present" to ensure that the file or directory does exist. { Present | Absent }.
[String] Type (Write): Indicates if the resource being configured is a directory or a file. Set this property to "Directory" to indicate that the resource is a directory. Set it to "File" to indicate that the resource is a file. { File | Directory }.
[Boolean] Recurse (Write): Indicates if subdirectories are included. Set this property to $true to indicate that you want subdirectories to be included.
[Boolean] Force (Write): Certain file operations (such as overwriting a file or deleting a directory that is not empty) will result in an error. Using the Force property overrides such errors.
[String] Content (Write): Specifies the contents of a file, such as a particular string.
[String[]] Attributes (Write): Specifies the desired state of the attributes for the targeted file or directory. { ReadOnly | Hidden | System | Archive }.

Read-Only Properties from Get-TargetResource for xVhdFile

None

Examples xVhdFile

Multiple examples

xVMDvdDrive

Manages DVD drives attached to a Hyper-V virtual machine.

Requirements for xVMDvdDrive

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMDvdDrive

[String] VMName (Key): Specifies the name of the virtual machine to which the DVD drive is to be added.
[Uint32] ControllerNumber (Key): Specifies the number of the controller to which the DVD drive is to be added.
[Uint32] ControllerLocation (Key): Specifies the number of the location on the controller at which the DVD drive is to be added.
[String] Path (Write): Specifies the full path to the virtual hard disk file or physical hard disk volume for the added DVD drive.
[String] Ensure (Write): Specifies if the DVD Drive should exist or not. The default value is Present. { Present | Absent }.

Read-Only Properties from Get-TargetResource for xVMDvdDrive

None

Examples xVMDvdDrive

Create a VM, given a VHDX and add a DVD Drives

xVMHardDiskDrive

Manages VHD(X)s attached to a Hyper-V virtual machine. When ControllerNumber or ControllerLocation is not provided, the same logic as Set-VMHardDiskDrive cmdlet is used.

Requirements for xVMHardDiskDrive

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMHardDiskDrive

[String] VMName (Key): Specifies the name of the virtual machine whose hard disk drive is to be manipulated.
[String] VhdPath (Key): Specifies the full path of the VHD file to be manipulated.
[String] ControllerType (Write): Specifies the type of controller to which the hard disk drive is to be set. The default value is SCSI. { SCSI | IDE }.
[Uint32] ControllerNumber (Write): Specifies the number of the controller to which the hard disk drive is to be set. For IDE: { 0, 1 }, for SCSI: { 0 | 1 | 2 | 3 }. Defaults to 0.
[Uint32] ControllerLocation (Write): Specifies the number of the location on the controller at which the hard disk drive is to be set. For IDE: { 0 | 1 }, for SCSI: { 0 .. 63 }. Defaults to 0.
[String] Ensure (Write): Specifies if the hard disk drive should exist or not. The default value is Present. { Present | Absent }.

Read-Only Properties from Get-TargetResource for xVMHardDiskDrive

None

Examples xVMHardDiskDrive

xVMHost

Manages Hyper-V host settings.

Requirements for xVMHost

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMHost

[String] IsSingleInstance (Key): Specifies the resource is a single instance, the value must be 'Yes'. { Yes }.
[Boolean] EnableEnhancedSessionMode (Write): Indicates whether users can use enhanced mode when they connect to virtual machines on this server by using Virtual Machine Connection.
[String] FibreChannelWwnn (Write): Specifies the default value of the World Wide Node Name on the Hyper-V host.
[String] FibreChannelWwpnMaximum (Write): Specifies the maximum value that can be used to generate World Wide Port Names on the Hyper-V host. Use with the FibreChannelWwpnMinimum parameter to establish a range of WWPNs that the specified Hyper-V host can assign to virtual Fibre Channel adapters.
[String] FibreChannelWwpnMinimum (Write): Specifies the minimum value that can be used to generate the World Wide Port Names on the Hyper-V host. Use with the FibreChannelWwpnMaximum parameter to establish a range of WWPNs that the specified Hyper-V host can assign to virtual Fibre Channel adapters.
[String] MacAddressMaximum (Write): Specifies the maximum MAC address using a valid hexadecimal value. Use with the MacAddressMinimum parameter to establish a range of MAC addresses that the specified Hyper-V host can assign to virtual machines configured to receive dynamic MAC addresses.
[String] MacAddressMinimum (Write): Specifies the minimum MAC address using a valid hexadecimal value. Use with the MacAddressMaximum parameter to establish a range of MAC addresses that the specified Hyper-V host can assign to virtual machines configured to receive dynamic MAC addresses.
[Uint32] MaximumStorageMigrations (Write): Specifies the maximum number of storage migrations that can be performed at the same time on the Hyper-V host.
[Uint32] MaximumVirtualMachineMigrations (Write): Specifies the maximum number of live migrations that can be performed at the same time on the Hyper-V host.
[Boolean] NumaSpanningEnabled (Write): Specifies whether virtual machines on the Hyper-V host can use resources from more than one NUMA node.
[Uint32] ResourceMeteringSaveIntervalMinute (Write): Specifies how often the Hyper-V host saves the data that tracks resource usage. The range is a minimum of 60 minutes to a maximum 1440 minutes (24 hours).
[Boolean] UseAnyNetworkForMigration (Write): Specifies how networks are selected for incoming live migration traffic. If set to $True, any available network on the host can be used for this traffic. If set to $False, incoming live migration traffic is transmitted only on the networks specified in the MigrationNetworks property of the host.
[String] VirtualHardDiskPath (Write): Specifies the default folder to store virtual hard disks on the Hyper-V host.
[String] VirtualMachineMigrationAuthenticationType (Write): Specifies the type of authentication to be used for live migrations. { Kerberos | CredSSP }.
[String] VirtualMachineMigrationPerformanceOption (Write): Specifies the performance option to use for live migration. { TCPIP | Compression | SMB }.
[String] VirtualMachinePath (Write): Specifies the default folder to store virtual machine configuration files on the Hyper-V host.
[Boolean] VirtualMachineMigrationEnabled (Write): Indicates whether Live Migration should be enabled or disabled on the Hyper-V host.

Read-Only Properties from Get-TargetResource for xVMHost

None

Examples xVMHost

Change VM Host paths

xVMHyperV

Manages VMs in a Hyper-V host.

The following properties cannot be changed after VM creation:

VhdPath
Path
Generation

Requirements for xVMHyperV

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMHyperV

[String] Name (Key): The desired VM name.
[String] VhdPath (Required): The desired VHD associated with the VM.
[String[]] SwitchName (Write): Virtual switch(es) associated with the VM. Multiple NICs can now be assigned.
[String] State (Write): State of the VM: { Running | Paused | Off }.
[String] Path (Write): Folder where the VM data will be stored.
[Uint32] Generation (Write): Virtual machine generation. Generation 2 virtual machines only support VHDX files. The default value is 1. { 1 | 2 }.
[Boolean] SecureBoot (Write): Enables or disables secure boot only on generation 2 virtual machines. The default value is $true.
[Uint64] StartupMemory (Write): Startup RAM for the VM. If neither MinimumMemory nor MaximumMemory is specified, dynamic memory will be disabled.
[Uint64] MinimumMemory (Write): Minimum RAM for the VM. Setting this property enables dynamic memory. Exception: If MinimumMemory, MaximumMemory and StartupMemory is equal, dynamic memory will be disabled.
[Uint64] MaximumMemory (Write): Maximum RAM for the VM. Setting this property enables dynamic memory. Exception: If MinimumMemory, MaximumMemory and StartupMemory is equal, dynamic memory will be disabled.
[String[]] MACAddress (Write): MAC address(es) of the VM. Multiple MAC addresses can now be assigned.
[Uint32] ProcessorCount (Write): Processor count for the VM.
[Boolean] WaitForIP (Write): If specified, waits for the VM to get valid IP address.
[Boolean] RestartIfNeeded (Write): If specified, will shutdown and restart the VM as needed for property changes.
[String] Ensure (Write): Ensures that the VM is Present or Absent. The default value is Present. { Present | Absent }.
[String] Notes (Write): Notes about the VM.
[Boolean] EnableGuestService (Write): Enable Guest Service Interface for the VM. The default value is $false.

Read-Only Properties from Get-TargetResource for xVMHyperV

[String] ID (Read): VM unique ID.
[String] Status (Read): Status of the VM.
[Uint32] CPUUsage (Read): CPU Usage of the VM.
[Uint64] MemoryAssigned (Read): Memory assigned to the VM.
[String] Uptime (Read): Uptime of the VM.
[DateTime] CreationTime (Read): Creation time of the VM.
[Boolean] HasDynamicMemory (Read): Does VM has dynamic memory enabled.
[String[]] NetworkAdapters (Read): Network adapters' IP addresses of the VM".

Examples xVMHyperV

xVMNetworkAdapter

Manages VMNetadapters attached to a Hyper-V virtual machine or the management OS.

Requirements for xVMNetworkAdapter

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMNetworkAdapter

[String] Id (Key): Unique string for identifying the resource instance.
[String] Name (Required): Name of the network adapter as it appears either in the management OS or attached to a VM.
[String] SwitchName (Required): Virtual Switch name to connect to.
[String] VMName (Required): Name of the VM to attach to. If you want to attach new VM Network adapter to the management OS, set this property to 'Management OS'.
[xNetworkSettings] NetworkSetting (Write): Network Settings of the network adapter. If this parameter is not supplied, DHCP will be used.
[String] MacAddress (Write): Use this to specify a Static MAC Address. If this parameter is not specified, dynamic MAC Address will be set.
[String] VlanId (Write): Use this to specify a Vlan id on the
Network Adapter.
[String] Ensure (Write): Ensures that the VM Network Adapter is Present or Absent. The default value is Present. { Present | Absent }.

xNetworkSettings Class

[String] IpAddress (Write): IpAddress to give the network adapter. Only used if not Dhcp. Required if not Dhcp.
[String] Subnet (Write): Subnet to give the network adapter. Only used if not Dhcp. Required if not Dhcp.
[String] DefaultGateway (Write): DefaultGateway to give the network adapter. Only used if not Dhcp.
[String] DnsServer (Write): DNSServer to give the network adapter. Only used if not Dhcp.

Read-Only Properties from Get-TargetResource for xVMNetworkAdapter

[Boolean] DynamicMacAddress (Read): Does the VMNetworkAdapter use a Dynamic MAC Address.

Examples xVMNetworkAdapter

xVMProcessor

Manages Hyper-V virtual machine processor options.

Requirements for xVMProcessor

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMProcessor

[String] VMName (Key): Specifies the name of the virtual machine on which the processor is to be configured.
[Boolean] EnableHostResourceProtection (Write): Specifies whether to enable host resource protection. NOTE: Only supported on Windows 10 and Server 2016.
[Boolean] ExposeVirtualizationExtensions (Write): Specifies whether nested virtualization is enabled. NOTE: Only supported on Windows 10 and Server 2016.
[Uint64] HwThreadCountPerCore (Write): Specifies the maximum thread core per processor core. NOTE: Only supported on Windows 10 and Server 2016.
[Uint64] Maximum (Write): Specifies the maximum percentage of resources available to the virtual machine processor to be configured. Allowed values range from 0 to 100.
[Uint32] MaximumCountPerNumaNode (Write): Specifies the maximum number of processors per NUMA node to be configured for the virtual machine.
[Uint32] MaximumCountPerNumaSocket (Write): Specifies the maximum number of sockets per NUMA node to be configured for the virtual machine.
[Unit32] RelativeWeight (Write): Specifies the priority for allocating the physical computer's processing power to this virtual machine relative to others. Allowed values range from 1 to 10000.
[Uint64] Reserve (Write): Specifies the percentage of processor resources to be reserved for this virtual machine. Allowed values range from 0 to 100.
[String] ResourcePoolName (Write): Specifies the name of the processor resource pool to be used.
[Boolean] CompatibilityForMigrationEnabled (Write): Specifies whether the virtual processors features are to be limited for compatibility when migrating the virtual machine to another host.
[Boolean] CompatibilityForOlderOperatingSystemsEnabled (Write): Specifies whether the virtual processor’s features are to be limited for compatibility with older operating systems.
[Boolean] RestartIfNeeded (Write): If specified, shutdowns and restarts the VM if needed for property changes.

Read-Only Properties from Get-TargetResource for xVMProcessor

None

Examples xVMProcessor

Create a secure boot gen 2 VM for a given VHD with nested virtualisation enabled

xVMScsiController

Manages the SCSI controllers attached to a Hyper-V virtual machine. When removing a controller, all the disks still connected to the controller will be detached.

Requirements for xVMScsiController

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMScsiController

[String] VMName (Key): Specifies the name of the virtual machine whose SCSI controller is to be manipulated.
[Uint32] ControllerNumber (Key): Specifies the number of the controller to be set: { 0 | 1 | 2 | 3 }.
[String] Ensure (Write): Specifies if the SCSI controller should exist or not. The default value is Present. { Present | Absent }.

Read-Only Properties from Get-TargetResource for xVMScsiController

None

Examples xVMScsiController

Add a secondary SCSI controller

xVMSwitch

Manages virtual switches in a Hyper-V host.

Requirements for xVMSwitch

The Hyper-V Role has to be installed on the machine.
The Hyper-V PowerShell module has to be installed on the machine.

Parameters for xVMSwitch

[String] Name (Key): The desired VM Switch name.
[String] Type (Key): The desired type of switch. { External | Internal | Private }
[String[]] NetAdapterName (Write): Network adapter name(s) for external switch type.
[Boolean] AllowManagementOS (Write): Specify if the VM host has access to the physical NIC. The default value is $false.
[Boolean] EnableEmbeddedTeaming (Write): Should embedded NIC teaming be used (Windows Server 2016 only). The default value is $false.
[String] BandwidthReservationMode (Write): Specify the QoS mode used (options other than NA are only supported on Hyper-V 2012+). The default value is NA. { Default | Weight | Absolute | None | NA }.
[String] LoadBalancingAlgorithm (Write): Specify the Load Balancing algorithm which should be used for the embedded NIC teaming. { Dynamic | HyperVPort }.
[Boolean] Id (Write): Specify the desired Unique ID of the Hyper-V switch. If not specified the ID will be generated by the system every time the Hyper-V Switch is created. (Windows Server 2016 only)
[String] Ensure (Write): Ensures that the VM Switch is Present or Absent. The default value is Present. { Present | Absent }.