The xHyper-V module contains DSC resources for deployment and configuration of Hyper-V hosts, virtual machines and related resources.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This is the branch containing the latest release - no contributions should be made directly to this branch.
This is the development branch to which contributions should be proposed by contributors as pull requests. This development branch will periodically be merged to the master branch, and be released to PowerShell Gallery.
Please check out common DSC Resources contributing guidelines.
A full list of changes in each version can be found in the change log.
- 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.
Manages VHDs in a Hyper-V host.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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 }.
[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.
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.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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 }.
[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 }.
None
Manages DVD drives attached to a Hyper-V virtual machine.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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 }.
None
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.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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 }.
None
- Create a VM, with an OS drive and an additional data drive
- Create a VM, with an OS drive and 4 data drives
Manages Hyper-V host settings.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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.
None
Manages VMs in a Hyper-V host.
The following properties cannot be changed after VM creation:
- VhdPath
- Path
- Generation
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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.
[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".
- Create a VM (Simple)
- Create a VM with dynamic memory
- Create a VM (Complete)
- Create a VM with multiple NICs attached to multiple switches
Manages VMNetadapters attached to a Hyper-V virtual machine or the management OS.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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'.[String]MacAddress (Write): Use this to specify a Static MAC Address. If this parameter is not specified, dynamic MAC Address will be set.[String]Ensure (Write): Ensures that the VM Network Adapter is Present or Absent. The default value is Present. { Present | Absent }.
[Boolean]DynamicMacAddress (Read): Does the VMNetworkAdapter use a Dynamic MAC Address.
- Add a new VM Network adapter in the management OS
- Add multiple VM Network adapters to a VM
- Add a couple of VM Network adapters in the management OS
- Add multiple VM Network adapters to a VM using status MAC addresses
Manages Hyper-V virtual machine processor options.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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.
None
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.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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 }.
None
Manages virtual switches in a Hyper-V host.
- The Hyper-V Role has to be installed on the machine.
- The Hyper-V PowerShell module has to be installed on the machine.
[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 }.
[String]NetAdapterInterfaceDescription (Read): Description of the network interface.