DSC Resource 'HyperV'

HyperV contains DSC resources for the management and configuration of Hyper-V.

Source	https://github.com/dsccommunity/CommonTasks/tree/main/source/DSCResources/HyperV
DSC Resource	https://github.com/dsccommunity/xHyper-V
Documentation	xHyper-V

Table 1. Attributes of category 'HyperV'

Parameter

Attribute

DataType

Description

Allowed Values

HostOS

String

Host Operating System

Supported are Windows Server and Windows 10

Server (default)
Client

EnableEnhancedSessionMode

Boolean

Indicates whether users can use enhanced mode when they connect to virtual machines on this server by using Virtual Machine Connection.

True
False (default)

VirtualHardDiskPath

String

Specifies the default folder to store virtual hard disks on the Hyper-V host.

VirtualMachinePath

String

Specifies the default folder to store virtual machine configuration files on the Hyper-V host.

VMSwitches

Hashtable[]

Set of virtual switches

VMMachines

Hashtable[]

Set of virtual machines

Important

Only Generation 2 machines are supported!

Table 2. Attributes of category 'HyperV/VMSwitches'

Parameter Attribute DataType Description Allowed Values

Name

Key

String

The desired VM Switch name.

Type

Key

String

The desired type of switch.

Note	Only one NAT switch is supported on a Hyper-V host.

External
Internal
Private
NAT

NetAdapterName

String[]

Network adapter name(s) for external switch type.

AllowManagementOS

Boolean

Specify if the VM host has access to the physical NIC.

True
False (default)

EnableEmbeddedTeaming

Boolean

Should embedded NIC teaming be used (Windows Server 2016 only).

True
False (default)

BandwidthReservationMode

String

Specify the QoS mode used (options other than NA are only supported on Hyper-V 2012+).

Default
Weight
Absolute
None
NA (default)

LoadBalancingAlgorithm

String

Specify the Load Balancing algorithm which should be used for the embedded NIC teaming.

Dynamic
HyperVPort

Id

Boolean

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)

AddressSpace

String

Address space of virtual network defined in the format '192.168.10.0/24'

Note	Mandatory attribute for a NAT switch!

IpAddress

String

The desired IP address of the network adapter which is connected to the Hyper-V switch.

Note	Not applicable for `Private` switches!

Note	Mandatory attribute for a NAT switch and is used as default gateway for the virtual network.

Gateway

String

The desired default gateway address.

InterfaceMetric

UInt32

Specifies the metric for an IP interface (IPv4 and IPv6).

Note	Typically, the interface metric gives preference to a particular interface, such as using wired if both wired and wireless are available. The default (empty) value is automatic.

NetworkCategory

String

Specifies the category of the network.

The category is set at the host network adapter connected to the switch.

Note	Not applicable for `Private` switches!

You cannot set the category to DomainAuthenticated (only test is supported). The server automatically sets the value of DomainAuthenticated when the network is authenticated to a domain controller.

The acceptable values for this parameter are:

Public - Networks in a public place such as an airport or coffee shop. Your PC is hidden from other devices on the network and can’t be used for printer and file sharing.
Private - Networks at home or work, where you know and trust the people and devices on the network. Your PC is discoverable and can be used for printer and file sharing if you set it up.
DomainAuthenticated - Networks at a workplace that are joined to a domain.

Public
Private
DomainAuthenticated

Ensure

String

Ensures that the VM Switch is Present or Absent.

Present (default)
Absent

Table 3. Attributes of category 'HyperV/VMMachines'

Parameter	Attribute	DataType	Description	Allowed Values
Name	Key	String	The desired VM name.
VhdPath	Required	String	The desired VHD associated with the VM.
SwitchName		String[]	Virtual switch(es) associated with the VM. Multiple NICs can now be assigned.
NetworkAdapters		Hashtable[]	Assigned network adapters. Use this section to specify network adapters with additional properties.
State		String	State of the VM.	Running Paused Off
Path		String	Folder where the VM data will be stored.
SecureBoot		Boolean	Enables or disables secure boot only on generation 2 virtual machines.	True (default) False
StartupMemory		Uint64	Startup RAM for the VM. If neither MinimumMemory nor MaximumMemory is specified, dynamic memory will be disabled.
MinimumMemory		Uint64	Minimum RAM for the VM. Setting this property enables dynamic memory. Exception: If MinimumMemory, MaximumMemory and StartupMemory is equal, dynamic memory will be disabled.
MaximumMemory		Uint64	Maximum RAM for the VM. Setting this property enables dynamic memory. Exception: If MinimumMemory, MaximumMemory and StartupMemory is equal, dynamic memory will be disabled.
MACAddress		String[]	MAC address(es) of the VM. Multiple MAC addresses can now be assigned.
ProcessorCount		Uint32	Processor count for the VM.
WaitForIP		Boolean	If specified, waits for the VM to get valid IP address.
RestartIfNeeded		Boolean	If specified, will shutdown and restart the VM as needed for property changes.
CheckpointType		String	Allows you to configure the type of checkpoints created by Hyper-V. The acceptable values for this parameter are: Disabled → Block creation of checkpoints. Standard → Create standard checkpoints. Production → Create production checkpoints if supported by guest operating system. Otherwise, create standard checkpoints. ProductionOnly → Create production checkpoints if supported by guest operating system. Otherwise, the operation fails.	Disabled Standard ProductionOnly Production
AutomaticCheckpointsEnabled		Boolean	Specifies whether automatic checkpoints are enabled.	True False
AutomaticStartAction		String	Specifies the action the virtual machine is to take upon start.	Nothing StartIfRunning Start
AutomaticStartDelay		Int32	Specifies the number of seconds by which the virtual machine’s start should be delayed.
AutomaticStopAction		String	Specifies the action the virtual machine is to take when the virtual machine host shuts down.	TurnOff Save ShutDown
TpmEnabled		Boolean	Enables the Trusted Platform Module (TPM) functionality on the virtual machine.	True False
EncryptStateAndVmMigrationTraffic		Boolean	Indicates that this cmdlet enables encryption of virtual machine state and migration traffic.	True False
Ensure		String	Ensures that the VM is Present or Absent.	Present (default) Absent
Notes		String	Notes about the VM.
EnableGuestService		Boolean	Enable Guest Service Interface for the VM.	True False (default)
EnableTimeSyncService		Boolean	Enable Time Synchronisation Service for the VM.	True False
Disks		Disk[]	Assigned virtual disks. Disks will be created in `VMMachine.Path\VMMachine.Name\Disks`. The first entry will be the OS disk (C:\).
Drives		Drive[]	Assigned virtual drives.

Table 4. Attributes of 'HyperV/VMMachines/NetworkAdapters'

Parameter Attribute DataType Description Allowed Values

Name

Key

String

Interface Name of the network adapter

SwitchName

Mandatory

String

Name of the connected switch

MacAddress

String

MAC-Address of the network adapter

IgnoreNetworkSetting

Boolean

Specifies whether the IpAddress information for the network adapter is set or ignored

True (default)
False

NetworkSetting

Hashtable

Network settings

Note	If `IgnoreNetworkSetting` is set to `True` the network settings are ignored.

Important

If network settings are not specified and parameter IgnoreNetworkSetting is set to False DHCP will be enabled on the network adapter.

VlanId

String

DhcpGuard

String

Specifies whether to drop DHCP messages from a virtual machine claiming to be a DHCP server.

Allowed values are On, which drops DHCP messages because the virtualized DHCP server is considered untrusted) or Off, which allows the message to be received because the virtualized DHCP server is considered to be trustworthy.

On
Off

RouterGuard

String

Specifies whether to drop Router Advertisement and Redirection messages from unauthorized virtual machines.

The value can be either On or Off. If On is specified, such messages are dropped. If Off is specified, such messages are sent.

On
Off

Table 5. Attributes of 'HyperV/VMMachines/NetworkAdapters/NetworkSetting'

Parameter	DataType	Description
IpAddress	String	The desired IP address.
Subnet	String	Subnet mask for the scope specified in IP address format
DefaultGateway	String	The desired default gateway address.
DnsServer	String	The desired DNS Server address.

Table 6. Attributes of 'HyperV/VMMachines/Disks'

Parameter	Attribute	DataType	Description
Name	Key	String	The VHD drive letter. The complete VHD file name is composed of `[VMMachine.Path]\[VMMachine.Name]\Disks\[VMMachine.Name_Disk.Name].vhdx`.
Path		String	The path of the VHD file. If Path is specified the complete VHD file name is composed of `[Path]\[VMMachine.Name_Disk.Name].vhdx`.
Size		String	The size of the VHD in GB.
CopyFrom		String	The file name of an existing VHD. This VHD will be copied to `[VMMachine.Path]\[VMMachine.Name]\Disks\[VMMachine.Name_Disk.Name].vhdx`.
CopyOnce		Hashtable[]	Copy files from host to VM system disk before first start of VM

Table 7. Attributes of 'HyperV/VMMachines/Disks/CopyOnce'

Parameter Attribute DataType Description Allowed Values

Sources

String[]

Specifies the path to the items on host computer to copy to VM system drive.

Wildcard characters are permitted.

Destination

String

Target directory on VM system drive.

Note	Attribute shall be specified without drive letter (e.g: `Users\Default\Documents\`).

Excludes

String[]

Specifies a items that are excluded from the copy operation.

The value of this attributes qualifies the Source attribute. Enter a path element or pattern, such as *.txt. Wildcard characters are permitted.

The attribute is effective only when the command includes the contents of an item, such as C:\Windows\*`, where the wildcard character specifies the contents of the C:\Windows directory.

PrepareScripts

String[]

Specifies single line Powershell script blocks which are executed on host computer before starting the copy actions.

These scripts can be used to create customized files for the target VM.

Important

The first disk must be the system drive.

Table 8. Attributes of 'HyperV/VMMachines/Drives'

Parameter	Attribute	DataType	Description
Name	Key	String	The VHD drive letter. The complete VHD file name is composed of `[VMMachine.Path]\[VMMachine.Name]\Disks\[VMMachine.Name_Disk.Name].vhdx`.
Path		String	The path of the VHD file. If Path is specified the complete VHD file name is composed of `[Path]\[VMMachine.Name_Disk.Name].vhdx`.
Size		String	The size of the VHD in GB.
CopyFrom		String	The file name of an existing VHD. This VHD will be copied to `[VMMachine.Path]\[VMMachine.Name]\Disks\[VMMachine.Name_Disk.Name].vhdx`.

Important

The last drive must be the OS installation drive.

Example

HyperV:
  HostOS: Server  # Client -> for Windows 10 Hyper-V Hosts

  VMSwitches:
    - Name: VMSwitchInt
      Type: Internal
      NetworkCategory: Private
      InterfaceMetric: 50

    - Name: VMSwitchExt
      Type: External
      NetAdapterName: Ethernet2

    - Name: VMSwitchNat
      Type: NAT
      AddressSpace: 192.168.0.0/24
      IpAddress: 192.168.0.1

  VMMachines:
    - Name: XXXADC
      Path: C:\VServer
      State: Running
      ProcessorCount: 2
      StartupMemory: 4GB
      Notes: "Active Directory Controller"
      CheckpointType: Standard
      AutomaticCheckpointsEnabled: True
      AutomaticStartAction: Start
      AutomaticStartDelay: 30
      AutomaticStopAction: Save
      TpmEnabled: True
      EncryptStateAndVmMigrationTraffic: True
      EnableGuestService:    True
      EnableTimeSyncService: True
      NetworkAdapters:
        - Name: Ethernet
          SwitchName: VMSwitchExt
          MacAddress: 00-17-FB-00-00-07
          VlanId: 100
          NetworkSetting:
            IpAddress: 192.168.0.10
            Subnet: 255.255.255.255
            DefaultGateway: 192.168.0.1
            DnsServer: 192.168.0.1
        - Name: HostNet
          SwitchName:  VMSwitchInt
          DhcpGuard:   On
          RouterGuard: Off
      Disks:
        - Name: C
          Size: 100GB
      Drives:
        - Name: S
          Path: T:\ISOs\SoftwarePackages.iso
        - Name: Z
          Path: T:\ISOs\WinSrv_IoT_2019_Standard.iso

    - Name: XXXAPP
      Path: C:\VServer
      State: Running
      ProcessorCount: 4
      StartupMemory: 4GB
      SwitchName:
        - HostNet
        - PublicNet
      Notes: "APP Server"
      Disks:
        - Name: C
          Size: 100GB
          CopyFrom: T:\Disks\System.vhdx  # Copy prepared VHDX
          CopyOnce:  # Copy Files from Host into VHDX before VM starts at first time
            - Sources:
                - D:\DSC_Config\Push\CompressedModules\*
                - D:\DSC_Config\Push\MOF\*
                - D:\DSC_Config\Push\MetaMOF\*
                - D:\DSC_Config\Push\dnsservers.txt
              Destination: DSC_Config\
              Excludes:
                - '*.txt'
                - '*.log'
              PrepareScripts:
                - '"192.168.0.1" | Set-Content -Path "D:\DSC_Config\Push\dnsservers.txt" -Force'
            - Sources: D:\DSC_Config\Pull\*
              Destination: DSCPullserver_Config\
        - Name: D
          Size: 500GB
          Path: C:\VirtualDisks  # VHD will be created in the specified path
        - Name: E
          CopyFrom: T:\Disks\Backup.vhdx
      Drives:
        - Name: S
          Path: T:\ISOs\SoftwarePackages.iso

    - Name: XXXHLP
      Path: C:\VServer
      State: Running
      ProcessorCount: 4
      StartupMemory: 4GB
      SwitchName:
        - HostNet
        - PublicNet
      Notes: "HELP Server"
      Disks:
        - Name: C
          Size: 100GB
          CopyFrom: T:\Disks\System.vhdx  # Copy prepared VHDX
          CopyOnce:  # Copy Files from Host into VHDX before VM starts at first time
            Sources: D:\DSC_Config\Push\*
            Destination: DSC_Config\
      Drives:
        - Name: S
          Path: T:\ISOs\SoftwarePackages.iso

Recommended Lookup Options in Datum.yml (Excerpt)

lookup_options:

  HyperV:
    merge_hash: deep
  HyperV\VMSwitches:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - Name
  HyperV\VMMachines:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - Name

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HyperV.adoc

HyperV.adoc

DSC Resource 'HyperV'

Files

HyperV.adoc

Latest commit

History

HyperV.adoc

File metadata and controls

DSC Resource 'HyperV'