HyperDeploy is a Powershell module that allows the use of infrastructure as code (IaC) to create and provision Hyper-V virtual machines.

HyperDeploy is not currently cross-platform and will only run on Windows, it can be installed by running the following command:

Install-Module -Name HyperDeploy

The main function provided by HyperDeploy is Publish-HyperDeploy which has the following parameters:

Publish-HyperDeploy -DefinitionFile "C:\definition.json"

The definition file is a json file that instructs Hyper Deploy on the infrastructure changes that you want, it is the code part of infrastructure as code. More information on the definition file can be found below.

Publish-HyperDeploy -DefinitionFile "C:\definition.json" -Replace

If replace is specified then Hyper Deploy will replace any Hyper-V VM's that already exist when Publish-HyperDeploy is ran.

Publish-HyperDeploy -DefinitionFile "C:\definition.json" -Force

Force will prevent Hyper Deploy prompting for confirmation before carrying out actions, use with care!

Publish-HyperDeploy -DefinitionFile "C:\definition.json" -Destroy

Destroy will remove all infrastructure specified in the definition file, use with care!

Publish-HyperDeploy -DefinitionFile "C:\definition.json" -Replace -ReplaceUpFront

If replace is set then remove all VM's specified within the definition file in one go before replacing. If not set HyperDeploy will remove and replace one-by-one.

Publish-HyperDeploy -DefinitionFile "C:\definition.json" -ContinueOnError

Stops HyperDeploy from aborting if an issue is encountered during execution.

Example definition file:

{
    "DeploymentOptions": {
        "StartAfterCreation": true,
        "Parallel": false
    },
    "VMs": [
        {
            "Name": "VM",
            "ProcessorCount": 8,
            "MemoryStartupBytes": "1GB",
            "MemoryMaximumBytes": "4GB",
            "CheckpointType": "Disabled",
            "Replicas": 50,
            "ReplicaStartIndex" : 5,
            "SkipNames": [
                "VM10"
            ],
            "HyperVServers": [
                {
                    "Name": "Host1",
                    "SwitchName": "VM Virtual Switch",
                    "GoldenImagePath": "A:\\goldenimage.vhdx",
                    "VMHardDiskPath": "A:\\Virtual Hard Disks"
                },
                {
                    "Name": "Host2",
                    "SwitchName": "VM Virtual Switch",
                    "GoldenImagePath": "A:\\goldenimage.vhdx",
                    "VMHardDiskPath": "A:\\Virtual Hard Disks",
                    "MaxReplicas" : 20
                }
            ],
            "PostCreate":{
                "Scripts":[
                    "C:\\HyperDeployScripts\\SetVLANS.ps1"
                ]
            },
            "Provisioning": {
                "RebootAfterEachScript": true,
                "RebootAfterLastScript": true,
                "RebuildOnValidationFailure": true,
                "RebuildOnProvisionFailure": true,
                "Scripts": [
                    "C:\\HyperDeployScripts\\Script1.Set-Credential.ps1",
                    "C:\\HyperDeployScripts\\Script2.ps1"
                ]
            }
        }
    ]
}

"DeploymentOptions": {
        "StartAfterCreation": true,
        "Parallel": false
    }

Deployment options are global settings which rule over all deployments.

If set to true HyperDeploy will start a VM immediately after the VM has been created. This must be set to true to use the provisioning features of HyperDeploy (discussed below)

If set to true HyperDeploy will attempt to create VM's and provision in parallel to speed up deployment. Up to 5 VM's will be created/provisioned in parallel. This is an experamental feature and has not been thoroughly tested so use with care.

VMS is an array of virtual machines that you want to create/destroy using HyperDeploy. See below for an explanation of options that can be set on each VM.

{
            "Name": "VM",
            "ProcessorCount": 8,
            "MemoryStartupBytes": "1GB",
            "MemoryMaximumBytes": "4GB",
            "CheckpointType": "Disabled",
            "Replicas": 50,
            "ReplicaStartIndex" : 5,
            "SkipNames": [
                "VM10"
            ],
            "HyperVServers": [
                {
                    "Name": "Host1",
                    "SwitchName": "VM Virtual Switch",
                    "GoldenImagePath": "A:\\goldenimage.vhdx",
                    "VMHardDiskPath": "A:\\Virtual Hard Disks"
                },
                {
                    "Name": "Host2",
                    "SwitchName": "VM Virtual Switch",
                    "GoldenImagePath": "A:\\goldenimage.vhdx",
                    "VMHardDiskPath": "A:\\Virtual Hard Disks",
                    "MaxReplicas" : 20
                }
            ],
            "PostCreate":{
                "Scripts":[
                    "C:\\HyperDeployScripts\\SetVLANS.ps1"
                ]
            },
            "Provisioning": {
                "RebootAfterEachScript": true,
                "RebootAfterLastScript": true,
                "RebuildOnValidationFailure": true,
                "RebuildOnProvisionFailure": true,
                "Scripts": [
                    "C:\\HyperDeployScripts\\Script1.Set-Credential.ps1",
                    "C:\\HyperDeployScripts\\Script2.ps1"
                ]
            }
        }

Name of VM you want to create/destroy using HyperDeploy, if Replicas is also specified then a number will be suffixed onto the name for each replica created.

Specifies how many virtual processors the VM should be created with.

Specifies how much memory the VM should be assigned at startup.

Specifies the maximum memory that can be assigned to the VM.

Allows setting the VMs checkpoint setting within Hyper-V, for options see below:

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.

If set HyperDeploy will create replicas of the VM, this is useful when you have a golden image and want to deploy x amount of replicas. For each replica a number will be suffixed onto the name value. Replicas will be load balanced accross the hosts specified in the HyperVServers array (see below).

Used in conjunction with Replicas, dictates what the starting replica number should be.

Use this array to specify any VM's you want to be skipped over when creating replicas. For example if Name is set to VM and Replicas is set to 3 the following VMs would be created: VM1, VM2 and VM3. If SkipNames has VM2 specified in it like so:

"SkipNames": [
                "VM2"
            ],

The VMs created would be VM`, VM3 and VM4.

This array contains the details about each Hyper-V host you want to deploy VM's to.

"HyperVServers": [
                {
                    "Name": "Host1",
                    "SwitchName": "VM Virtual Switch",
                    "GoldenImagePath": "A:\\goldenimage.vhdx",
                    "VMHardDiskPath": "A:\\Virtual Hard Disks",
                    "MaxReplicas" : 20
                }
            ]

Name of the Hyper-V host you want to deploy VM's to. The host much have WinRM enabled and allow remote connections.

Name of the Hyper-V Virtual Switch you want to assign to the VM

Used in conjuction with VM Replica setting. If specified a copy of the golden image specified will be taken and attached as a virtual hard disk to the VM

Location where you want to store the VM hard disk on the host server.

Maximum amount on replicas to assign to the host if Replicas are in use.

Post create allows you to execute scripts against the created VM, the main use of these scripts is to set additional Hyper V configuration settings that HyperDeploy cannot do natively such as assign a VLAN Identifier or set VM Firmware configuration.

"PostCreate":{
                "Scripts":[
                    "C:\\HyperDeployScripts\\SetVLANS.ps1"
                ]
            }

The name of the created VM is passed as an argument to any specified scripts. An example Post Create script may look like the following:

param($name)

Set-VMNetworkAdapterVlan -VMName $name -Access -VlanId 121

Provisioning allows you to execute Powershell scripts against VM's created by HyperDeploy during the creation process.

"Provisioning": {
                "RebootAfterEachScript": true,
                "RebootAfterLastScript": true,
                "RebuildOnProvisionFailure": true,
                "Scripts": [
                    "C:\\HyperDeployScripts\\Script1.Set-Credential.ps1",
                    "C:\\HyperDeployScripts\\Script2.ps1"
                ]
            }

If true after each script is ran the VM will be rebooted. Useful when your scripts require a reboot to apply such as joining a domain.

If true will reboot after the last provisioning script is ran, default value is true

If true will recreate the VM if any error is detected as part of the priovisioning process, this will be retried up to 3 times.

Array of scripts you want to execute against the VM. These are executed over WinRM. In order for communication to be established over WinRM you need to set the credentials for HyperDeploy to use, this is done using credential scripts. Credential scripts end in .Set-Credential.ps1 and should return a pscredential object. See below for an example credential script

[string]$userName = 'user'
[string]$userPassword = 'password'
[securestring]$secStringPassword = ConvertTo-SecureString $userPassword -AsPlainText -Force
[pscredential]$credOject = New-Object System.Management.Automation.PSCredential ($userName, $secStringPassword)

return $credOject

I would highly recommend you don't store credentials within a Powershell script and instead use something like a replace tokens task/script within a CI/CD system.