Skip to content

VMHyperV

Jump to bottom
dscbot edited this page Jun 12, 2022 · 3 revisions

VMHyperV

Parameters

Parameter Attribute DataType Description Allowed Values
Name Key String The desired name of the VM.
VhdPath Required String The desired VHD associated with the VM.
SwitchName Write StringArray[] Virtual switch(es) associated with the VM. Multiple NICs can now be assigned.
State Write String State of the VM. Running, Paused, Off
Path Write String Folder where the VM data will be stored.
Generation Write UInt32 Virtual machine's generation. Generation 2 virtual machines only support VHDX files. The default value is 1.
StartupMemory Write UInt64 Startup RAM for the VM. If neither MinimumMemory nor MaximumMemory is specified, dynamic memory will be disabled.
MinimumMemory Write UInt64 Minimum RAM for the VM. Setting this property enables dynamic memory, with the exception; If MinimumMemory, MaximumMemory and StartupMemory is equal, dynamic memory will be disabled.
MaximumMemory Write UInt64 Maximum RAM for the VM. Setting this property enables dynamic memory, with the exception; If MinimumMemory, MaximumMemory and StartupMemory is equal, dynamic memory will be disabled.
MACAddress Write StringArray[] MAC address(es) of the VM NICs. Multiple MAC addresses can now be assigned.
ProcessorCount Write UInt32 Processor count for the VM.
WaitForIP Write Boolean If specified, waits for the VM to get valid IP address.
RestartIfNeeded Write Boolean If specified, will shutdown and restart the VM as needed for property changes.
Ensure Write String Specifies if the VM should be Present (created) or Absent (removed). The default value is Present. Present, Absent
Notes Write String Notes about the VM.
SecureBoot Write Boolean Specifies if Secure Boot should be enabled for Generation 2 virtual machines. Only supports generation 2 virtual machines. Default value is $true.
EnableGuestService Write Boolean Enable Guest Service Interface for the VM. The default value is $false.
AutomaticCheckpointsEnabled Write Boolean Enable AutomaticCheckpoints for the VM.
ID Read String Returns the unique ID for the VM.
Status Read String Returns the current status of the VM.
CPUUsage Read UInt32 Returns the current CPU usage of the VM.
MemoryAssigned Read UInt64 Returns the current memory assigned to the VM.
Uptime Read String Returns the uptime of the VM.
CreationTime Read DateTime Returns the creation time of the VM.
HasDynamicMemory Read Boolean Returns $true if the VM has dynamic memory enabled.
NetworkAdapters Read StringArray[] Returns the IP addresses of the virtual machine's network adapters.

Description

Manages VMs in a Hyper-V host.

The following properties cannot be changed after VM creation:

  • VhdPath
  • Path
  • Generation

Requirements

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

Examples

Example 1

Create a new VM.

configuration Example
{
    param
    (
        [System.String[]]
        $NodeName = 'localhost',

        [Parameter(Mandatory = $true)]
        [System.String]
        $VMName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $VhdPath
    )

    Import-DscResource -ModuleName 'HyperVDsc'

    Node $NodeName
    {
        # Install HyperV feature, if not installed - Server SKU only
        WindowsFeature HyperV
        {
            Ensure = 'Present'
            Name   = 'Hyper-V'
        }

        # Ensures a VM with default settings
        VMHyperV NewVM
        {
            Ensure    = 'Present'
            Name      = $VMName
            VhdPath   = $VhdPath
            Generation = 2
            DependsOn = '[WindowsFeature]HyperV'
        }
    }
}

Example 2

Create a VM with DVD drive attached to it.

configuration Example
{
    param
    (
        [System.String[]]
        $NodeName = 'localhost',

        [Parameter(Mandatory = $true)]
        [System.String]
        $VMName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $VhdPath,

        [System.String]
        $ISOPath
    )

    Import-DscResource -ModuleName 'HyperVDsc'

    Node $NodeName
    {
        # Install HyperV feature, if not installed - Server SKU only
        WindowsFeature HyperV
        {
            Ensure = 'Present'
            Name   = 'Hyper-V'
        }

        # Ensures a VM with default settings
        VMHyperV NewVM
        {
            Ensure    = 'Present'
            Name      = $VMName
            VhdPath   = $VhdPath
            Generation = $VhdPath.Split('.')[-1]
            DependsOn = '[WindowsFeature]HyperV'
        }

        # Adds DVD Drive with ISO
        VMDvdDrive NewVMDvdDriveISO
        {
            Ensure             = 'Present'
            VMName               = $VMName
            ControllerNumber   = 0
            ControllerLocation = 0
            Path               = $ISOPath
            DependsOn          = '[VMHyperV]NewVM'
        }
    }
}

Example 3

Create a VM with nested virtualization.

configuration Example
{
    param
    (
        [Parameter()]
        [System.String[]]
        $NodeName = 'localhost',

        [Parameter(Mandatory = $true)]
        [System.String]
        $VMName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $VhdPath,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $Memory
    )

    Import-DscResource -ModuleName 'HyperVDsc'

    Node $NodeName
    {
        # Install HyperV feature, if not installed - Server SKU only
        WindowsFeature HyperV
        {
            Ensure = 'Present'
            Name   = 'Hyper-V'
        }

        # Ensures a VM with default settings
        VMHyperV NewVM
        {
            Ensure        = 'Present'
            Name          = $VMName
            VhdPath       = $VhdPath
            Generation    = 2
            StartupMemory = $Memory
            MinimumMemory = $Memory
            MaximumMemory = $Memory
            DependsOn     = '[WindowsFeature]HyperV'
        }

        # Set the VM options
        VMProcessor NestedVirtualization
        {
            VMName                         = $VMName
            ExposeVirtualizationExtensions = $true
            DependsOn                      = '[VMHyperV]NewVM'
        }
    }
}

Example 4

Complete example.

configuration Example
{
    param
    (
        [System.String[]]
        $NodeName = 'localhost',

        [Parameter(Mandatory = $true)]
        [System.String]
        $VMName,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $VhdSizeBytes,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $StartupMemory,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $MinimumMemory,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $MaximumMemory,

        [Parameter(Mandatory = $true)]
        [System.String]
        $SwitchName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter(Mandatory = $true)]
        [System.UInt32]
        $ProcessorCount,

        [ValidateSet('Off','Paused','Running')]
        [System.String]
        $State = 'Off',

        [Switch]
        $WaitForIP,

        [System.Boolean]
        $AutomaticCheckpointsEnabled
    )

    Import-DscResource -ModuleName 'HyperVDsc'

    Node $NodeName
    {
        # Logic to handle both Client and Server OS
        # Configuration needs to be compiled on target server
        $Operatingsystem = Get-CimInstance -ClassName Win32_OperatingSystem
        if ($Operatingsystem.ProductType -eq 1)
        {
            # Client OS, install Hyper-V as OptionalFeature
            $HyperVDependency = '[WindowsOptionalFeature]HyperV'
            WindowsOptionalFeature HyperV
            {
                Ensure = 'Enable'
                Name = 'Microsoft-Hyper-V-All'
            }
        }
        else {
            # Server OS, install HyperV as WindowsFeature
            $HyperVDependency = '[WindowsFeature]HyperV','[WindowsFeature]HyperVPowerShell'
        WindowsFeature HyperV
        {
            Ensure = 'Present'
            Name   = 'Hyper-V'
        }
            WindowsFeature HyperVPowerShell
            {
                Ensure = 'Present'
                Name   = 'Hyper-V-PowerShell'
            }
        }

        # Create new VHD
        Vhd NewVhd
        {
            Ensure           = 'Present'
            Name             = "$VMName-OSDisk.vhdx"
            Path             = $Path
            Generation       = 'vhdx'
            MaximumSizeBytes = $VhdSizeBytes
            DependsOn        = $HyperVDependency
        }

        # Ensures a VM with all the properties
        VMHyperV NewVM
        {
            Ensure          = 'Present'
            Name            = $VMName
            VhdPath         = (Join-Path -Path $Path -ChildPath "$VMName-OSDisk.vhdx")
            SwitchName      = $SwitchName
            State           = $State
            Path            = $Path
            Generation      = 2
            StartupMemory   = $StartupMemory
            MinimumMemory   = $MinimumMemory
            MaximumMemory   = $MaximumMemory
            ProcessorCount  = $ProcessorCount
            MACAddress      = $MACAddress
            RestartIfNeeded = $true
            WaitForIP       = $WaitForIP
            AutomaticCheckpointsEnabled = $AutomaticCheckpointsEnabled
            DependsOn       = '[Vhd]NewVhd'
        }
    }
}

Example 5

VM using dynamic memory.

configuration Example
{
    param
    (
        [System.String[]]
        $NodeName = 'localhost',

        [Parameter(Mandatory = $true)]
        [System.String]
        $VMName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $VhdPath,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $StartupMemory,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $MinimumMemory,

        [Parameter(Mandatory = $true)]
        [System.UInt64]
        $MaximumMemory
    )

    Import-DscResource -ModuleName 'HyperVDsc'

    Node $NodeName
    {
        # Install HyperV feature, if not installed - Server SKU only
        WindowsFeature HyperV
        {
            Ensure = 'Present'
            Name   = 'Hyper-V'
        }

        # Ensures a VM with dynamic memory
        VMHyperV NewVM
        {
            Ensure        = 'Present'
            Name          = $VMName
            VhdPath       = $VhdPath
            Generation    = 2
            StartupMemory = $StartupMemory
            MinimumMemory = $MinimumMemory
            MaximumMemory = $MaximumMemory
            DependsOn     = '[WindowsFeature]HyperV'
        }
    }
}

Example 6

Description not yet written.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String[]]
        $NodeName = 'localhost',

        [Parameter()]
        [System.String]
        $VMName = 'TestVM',

        [Parameter()]
        [System.String]
        $VhdPath = 'C:\temp\disk.vhdx',

        [Parameter()]
        [System.String[]]
        $SwitchName = @('MySwitch'),

        [Parameter()]
        [System.String[]]
        $MACAddress = '0000000'
    )

    Import-DscResource -ModuleName 'HyperVDsc'

    Node $NodeName
    {
        # Install HyperV features, if not installed - Server SKU only
        WindowsFeature HyperV
        {
            Ensure = 'Present'
            Name   = 'Hyper-V'
        }

        WindowsFeature HyperVPowerShell
        {
            Ensure = 'Present'
            Name   = 'Hyper-V-PowerShell'
        }

        # Dynamically build the 'DependsOn' array for the 'VMHyperV' feature
        # based on the number of virtual switches specified
        $VMHyperVDependsOn = @('[WindowsFeature]HyperV','[WindowsFeature]HyperVPowerShell')

        # Create each virtual switch
        foreach ($vmSwitch in $SwitchName)
        {
            # Remove spaces and hyphens from the identifier
            $vmSwitchName = $vmSwitch -replace ' ','' -replace '-',''
            # Add the virtual switch dependency
            $VMHyperVDependsOn += "[VMSwitch]$vmSwitchName"

            VMSwitch $vmSwitchName
            {
                Ensure         = 'Present'
                Name           = $vmSwitch
                Type           = 'Internal'
                DependsOn      = '[WindowsFeature]HyperV','[WindowsFeature]HyperVPowerShell'
            }
        }

        # Ensures a VM with all the properties
        VMHyperV $VMName
        {
            Ensure     = 'Present'
            Name       = $VMName
            VhdPath    = $VhdPath
            SwitchName = $SwitchName
            MACAddress = $MACAddress
            # Use the dynamically created dependency list/array
            DependsOn  = $VMHyperVDependsOn
        }
    }
}

HyperVDsc Module

Clone this wiki locally