/xHyper-V

Primary LanguagePowerShellMIT LicenseMIT

xHyper-V

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.

Branches

master

Build status codecov

This is the branch containing the latest release - no contributions should be made directly to this branch.

dev

Build status codecov

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.

Contributing

Please check out common DSC Resources 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.
  • 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.
  • 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

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

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.

Read-Only Properties from Get-TargetResource for xVMHost

None

Examples xVMHost

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'.
  • [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 }.

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

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] Ensure (Write): Ensures that the VM Switch is Present or Absent. The default value is Present. { Present | Absent }.

Read-Only Properties from Get-TargetResource for xVMSwitch

  • [String] Id (Read): Unique ID for the switch.
  • [String] NetAdapterInterfaceDescription (Read): Description of the network interface.

Examples xVMSwitch