PowerCLI Reference

New-VM

Synopsis

This cmdlet creates a new virtual machine.

Syntax

New-VM [-AdvancedOption <AdvancedOption[]>] [[-VMHost] <VMHost>] [-Version <VMVersion>] -Name <String> [-ResourcePool <VIContainer>] [-VApp <VApp>] [-Location <Folder>] [-Datastore <StorageResource>] [-DiskMB <Int64[]>] [-DiskGB <Decimal[]>] [-DiskPath <String[]>] [-DiskStorageFormat <VirtualDiskStorageFormat>] [-MemoryMB <Int64>] [-MemoryGB <Decimal>] [-NumCpu <Int32>] [-CoresPerSocket <Int32>] [-Floppy] [-CD] [-GuestId <String>] [-AlternateGuestName <String>] [-NetworkName <String[]>] [-Portgroup <VirtualPortGroupBase[]>] [-HARestartPriority <HARestartPriority>] [-HAIsolationResponse <HAIsolationResponse>] [-DrsAutomationLevel <DrsAutomationLevel>] [-VMSwapfilePolicy <VMSwapfilePolicy>] [-Server <VIServer[]>] [-RunAsync] [-Notes <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

New-VM [-AdvancedOption <AdvancedOption[]>] [[-VMHost] <VMHost>] [-Name <String>] [-ResourcePool <VIContainer>] [-VApp <VApp>] [-Location <Folder>] [-Datastore <StorageResource>] [-DiskStorageFormat <VirtualDiskStorageFormat>] [-OSCustomizationSpec <OSCustomizationSpec>] [-HARestartPriority <HARestartPriority>] [-HAIsolationResponse <HAIsolationResponse>] [-DrsAutomationLevel <DrsAutomationLevel>] [-LinkedClone] [-ReferenceSnapshot <Snapshot>] [-Server <VIServer[]>] [-RunAsync] [-Notes <String>] -VM <VirtualMachine[]> [-WhatIf] [-Confirm] [<CommonParameters>]

New-VM [-AdvancedOption <AdvancedOption[]>] [[-VMHost] <VMHost>] -Name <String> [-ResourcePool <VIContainer>] [-VApp <VApp>] [-Location <Folder>] [-Datastore <StorageResource>] [-Template] <Template> [-DiskStorageFormat <VirtualDiskStorageFormat>] [-OSCustomizationSpec <OSCustomizationSpec>] [-HARestartPriority <HARestartPriority>] [-HAIsolationResponse <HAIsolationResponse>] [-DrsAutomationLevel <DrsAutomationLevel>] [-Server <VIServer[]>] [-RunAsync] [-Notes <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

New-VM [[-VMHost] <VMHost>] [-Name <String>] [-ResourcePool <VIContainer>] [-VApp <VApp>] [-Location <Folder>] [-HARestartPriority <HARestartPriority>] [-HAIsolationResponse <HAIsolationResponse>] [-DrsAutomationLevel <DrsAutomationLevel>] -VMFilePath <String> [-Server <VIServer[]>] [-RunAsync] [-Notes <String>] [-WhatIf] [-Confirm] [<CommonParameters>]

New-VM [[-VMHost] <VMHost>] [-Name <String>] [-ResourcePool <VIContainer>] [-Location <Folder>] [-Datastore <StorageResource>] [-DiskStorageFormat <VirtualDiskStorageFormat>] [-HARestartPriority <HARestartPriority>] [-HAIsolationResponse <HAIsolationResponse>] [-DrsAutomationLevel <DrsAutomationLevel>] [-ContentLibraryItem] <ContentLibraryItem> [-Server <VIServer[]>] [-RunAsync] [-WhatIf] [-Confirm] [<CommonParameters>]

Related Commands

Online version
Get-VM
Move-VM
Remove-VM
Set-VM
Start-VM
Stop-VM
Suspend-VM
Restart-VM

Detailed Description

This cmdlet creates a new virtual machine with the provided parameters. The network adapter and the SCSI adapter of the new virtual machine are created of the recommended type for the OS that is specified by the GuestId parameter. If the OSCustomizationSpec parameter is used, the virtual machine is customized according to the spec. You must specify values for at least one of the ResourcePool, VMHost, and VApp parameters.

Parameters

NameTypeDescriptionRequired?Pipeline InputDefault Value
VMHostVMHostSpecifies the host on which you want to create the new virtual machine.falsetrue (ByValue)
ContentLibraryItemContentLibraryItemSpecifies the content library template to deploy the virtual machine from.truetrue (ByValue)
TemplateTemplateSpecifies the virtual machine template you want to use for the creation of the new virtual machine. Passing values to this parameter through a pipeline is deprecated and will be disabled in a future release.truetrue (ByValue)
AdvancedOptionAdvancedOption[]Specifies advanced options for creating virtual machines. Accepts only SdrsVMDiskAntiAffinityRule and SdrsVMAntiAffinityRule objects.

The SdrsVMDiskAntiAffinityRule defines a Storage DRS intra-VM anti-affinity rule (vm disk anti-affinity rule). It is only applicable when creating a virtual machine or hard disk on a datastore cluster. An instance of the object is created by invoking its constructor. There are two constructors - "public SdrsVMDiskAntiAffinityRule(param string[] diskIdentifier)" and "public SdrsVMDiskAntiAffinityRule(param HardDisk[] disk)". For the first constructor, "diskIdentifier" can be either the disk key or the index of the disk in the disk array. The specified disks (and the disk to which the rule is applied) are placed in an anti-affinity rule on a DatastoreCluster. Only one such rule is supported per a virtual machine. You can pass the instance to the AdvancedOption parameter of the New-VM or New-HardDisk cmdlets.

The SdrsVMAntiAffinityRule defines a Storage DRS inter-VM anti-affinity rule. It is only applicable when creating a virtual machine on a DatastoreCluster. An instance of the object is created by invoking its constructor. The constructor has one parameter - an array of virtual machines - "public SdrsVMAntiAffinityRule(param VirtualMachine[] vm)". Then, you can pass the instance to the AdvancedOption parameter of the New-VM cmdlet. This will place the new virtual machine and the virtual machines specified in the constructor in an inter-VM anti-affinity rule on a DatastoreCluster.
falsefalse
AlternateGuestNameStringSpecifies the full OS name of the new virtual machine. Use this parameter if the GuestID parameter is set to otherGuest or otherGuest64.falsefalse
CDSwitchParameterIndicates that you want to add a CD drive to the new virtual machine.falsefalse
ConfirmSwitchParameterIf the value is $true, indicates that the cmdlet asks for confirmation before running. If the value is $false, the cmdlet runs without asking for user confirmation.falsefalse
CoresPerSocketInt32Specifies the number of virtual CPU cores per socket.falsefalse
DatastoreStorageResourceSpecifies the datastore where you want to place the new virtual machine. If a DatastoreCluster is passed to the Datastore parameter, the virtual machine is placed in the DatastoreCluster in an automated SDRS mode and with enabled intra-VM affinity rule (unless another rule is specified). You can specify a SDRS rule when creating the virtual machine in a DatastoreCluster by passing either a SdrsVMDiskAntiAffinityRule or SdrsVMAntiAffinityRule objects to the AdvancedOption parameter. These two rules are mutually exclusive.falsefalse
DiskGBDecimal[]Specifies the size in gigabytes (GB) of the disks that you want to create and add to the new virtual machine.falsefalse
DiskMBInt64[]This parameter is obsolete. Use DiskGB instead.
Specifies the size in megabytes (MB) of the disks that you want to create and add to the new virtual machine.
falsefalse
DiskPathString[]Specifies paths to virtual disks you want to add to the new virtual machine.falsefalse
DiskStorageFormatVirtualDiskStorageFormatSpecifies the storage format of the disks of the virtual machine. This parameter accepts Thin, Thick, and EagerZeroedThick values.falsefalse
DrsAutomationLevelDrsAutomationLevelSpecifies a DRS (Distributed Resource Scheduler) automation level. The valid values are FullyAutomated, Manual, PartiallyAutomated, AsSpecifiedByCluster, and Disabled. Passing values to this parameter through a pipeline is deprecated and will be disabled in a future release. Specifying this parameter is only supported when the virtual machine is inside a cluster. Otherwise, an error is generated.falsefalse
FloppySwitchParameterIndicates that you want to add a floppy drive to the new virtual machine.falsefalse
GuestIdStringSpecifies the guest operating system of the new virtual machine. The valid values for specific ESX versions are listed in the description of the VirtualMachineGuestOsIdentifier enumeration type in the vSphere API Reference available at http://www.vmware.com/support/developer/vc-sdk/. Depending on the hardware configuration of the host, some of the guest operating systems might be inapplicable.falsefalse
HAIsolationResponseHAIsolationResponseIndicates whether the virtual machine should be powered off if a host determines that it is isolated from the rest of the compute resource. The available values are AsSpecifiedByCluster, PowerOff, and DoNothing. Passing values to this parameter through a pipeline is deprecated and will be disabled in a future release. Specifying this parameter is only supported when the virtual machine is inside a cluster. Otherwise, an error is generated.falsefalse
HARestartPriorityHARestartPrioritySpecifies the HA restart priority of the new virtual machine. The valid values are Disabled, Low, Medium, High, and ClusterRestartPriority. VMware HA is a feature that detects failed virtual machines and automatically restarts them on alternative ESX hosts. Passing values to this parameter through a pipeline is deprecated and will be disabled in a future release. Specifiesing this parameter is only supported when the virtual machine is inside a cluster. Otherwise, an error is generated.falsefalse
LinkedCloneSwitchParameterIndicates that you want to create a linked clone. When you set the LinkedClone parameter, the ReferenceSnapshot parameter becomes mandatory.falsefalse
LocationFolderSpecifies the folder where you want to place the new virtual machine.falsefalse
MemoryGBDecimalSpecifies the memory size in gigabytes (GB) of the new virtual machine.falsefalse
MemoryMBInt64This parameter is obsolete. Use MemoryGB instead.
Specifies the memory size in megabytes (MB) of the new virtual machine.
falsefalse
NameStringSpecifies a name for the new virtual machine. If you are registering or cloning an existing virtual machine, this parameter is not mandatory.truefalse
NetworkNameString[]Specifies the networks to which you want to connect the new virtual machine. Specifying a distributed port group name is obsolete. Use the Portgroup parameter instead.falsefalse
NotesStringProvides a description of the new virtual machine. The alias of this parameter is Description.falsefalse
NumCpuInt32Specifies the number of the virtual CPUs of the new virtual machine.falsefalse
OSCustomizationSpecOSCustomizationSpecSpecifies a customization specification that is to be applied to the new virtual machine.falsefalse
PortgroupVirtualPortGroupBase[]Specifies standard or distributed port groups to which you want to connect the virtual machine. For each specified port group, a new network adapter is created.falsefalse
ReferenceSnapshotSnapshotSpecifies a source snapshot for the linked clone that you want to create. When you set the LinkedClone parameter, the ReferenceSnapshot parameter becomes mandatory.falsefalse
ResourcePoolVIContainerSpecifies where you want to place the new virtual machine. The parameter accepts VMHost, Cluster, ResourcePool, and VApp objects. If no value is specified, the virtual machine is added to the resource pool of its host.falsetrue (ByValue)
RunAsyncSwitchParameterIndicates that the command returns immediately without waiting for the task to complete. In this mode, the output of the cmdlet is a Task object. For more information about the RunAsync parameter run "help About_RunAsync" in the VMware PowerCLI console.falsefalse
ServerVIServer[]Specifies the vCenter Server systems on which you want to run the cmdlet. If no value is passed to this parameter, the command runs on the default servers. For more information about default servers, see the description of Connect-VIServer.falsefalse
VAppVAppThis parameter is deprecated. Use the ResourcePool parameter instead.
Specifies the vApp where you want to create the new virtual machine.
falsetrue (ByValue)
VersionVMVersionSpecifies the version of the new virtual machine. The valid values are v4, v7, v8, v9, v10, and v11. By default, the new virtual machine is created with the latest available version.falsefalse
VMVirtualMachine[]Specifies a virtual machine to clone.truetrue (ByValue)
VMFilePathStringSpecifies a path to the virtual machine you want to register.truefalse
VMSwapfilePolicyVMSwapfilePolicySpecifies the swapfile placement policy. The following values are valid:

InHostDataStore - Stores the swapfile in the datastore specified by the VMSwapfileDatastoreID property of the virtual machine host. If the VMSwapfileDatastoreID property is not set or indicates a datastore with insufficient free space, the swapfile is stored in the same directory as the virtual machine. This setting might degrade the VMotion performance.

WithVM - Stores the swapfile in the same directory as the virtual machine.
falsefalse
WhatIfSwitchParameterIndicates that the cmdlet is run only to display the changes that would be made and actually no objects are modified.falsefalse

Return Type

The newly created VirtualMachine object

Notes

Examples

-------------- Example 1 --------------

$myTargetVMHost = Get-VMHost -Name MyVMHost1
New-VM -Name MyVM1 -ResourcePool $myTargetVMHost -Datastore MyDatastore1 -NumCPU 2 -MemoryGB 4 -DiskGB 40 -NetworkName "VM Network" -Floppy -CD -DiskStorageFormat Thin -GuestID winNetDatacenterGuest

Creates a virtual machine by specifying a target host, a target datastore, and a network to connect to, and configures the settings for the virtual machine.

-------------- Example 2 --------------

$myCluster = Get-Cluster -Name MyCluster1
New-VM -Name MyVM1 -ResourcePool $myCluster

Creates a virtual machine by specifying a cluster. The ResourcePool parameter accepts ResourcePool, Cluster, VApp, and standalone VMHost objects.

-------------- Example 3 --------------

$vmhost = Get-VMHost -Name MyVMHost1
$myCluster = Get-Cluster -Name MyCluster1
New-VM -Name MyVM1 -VMHost $vmhost -ResourcePool $myCluster -DiskGB 4 -MemoryGB 1

Creates a virtual machine by specifying a cluster and explicitly selecting the host, instead of allowing auto-selection of a target host.

-------------- Example 4 --------------

$vmhost = Get-VMHost -Name MyVMHost1
New-VM -Name MyVM1 -ResourePool $vmhost -DiskGB 40,100

Creates a virtual machine with multiple disks.

-------------- Example 5 --------------

$vmhost = Get-VMHost -Name MyVMHost1
New-VM -Name MyVM1 -ResourcePool $vmhost -DiskPath "[Storage1] WindowsXP/WindowsXP.vmdk"

Creates a virtual machine by specifying an existing disk.

-------------- Example 6 --------------

$vmhost = Get-VMHost -Name MyVMHost1
New-VM -Name MyVM1 -ResourcePool $vmhost -Version v4

Creates a virtual machine by explicitly specifying the version of the virtual machine hardware through the Version parameter.

-------------- Example 7 --------------

$myDatastore = Get-Datastore -Name MyDatastore1
$vmhost = Get-VMHost -Name MyVMHost1
New-VM -Name MyVM2 -VM MyVM1 -Datastore $myDatastore -VMHost $vmhost

Creates a new virtual machine named MyVM2 by cloning the MyVM1 virtual machine on the specified datastore and host.

-------------- Example 8 --------------

New-VM -VM MyVM1, MyVM2 -Location MyFolder1 -VMHost MyHost1

Copies the MyVM1 and MyVM2 virtual machines to the MyFolder1 folder on the MyHost1 host.

-------------- Example 9 --------------

$myResourcePool = Get-ResourcePool -Name MyResourcePool1
$mySpecification = Get-OSCustomizationSpec -Name WindowsSpec
New-VM -VM MyVM1 -Name MyVM2 -OSCustomizationSpec $mySpecification -ResourcePool $myResourcePool

Clones the virtual machine MyVM1 to MyVM2 and applies a customization specification on the cloned virtual machine.

-------------- Example 10 --------------

$myResourcePool = Get-ResourcePool -Name MyResourcePool1
$myTemplate = Get-Template -Name WindowsTemplate
$mySpecification = Get-OSCustomizationSpec -Name WindowsSpec
New-VM -Name MyVM2 -Template $myTemplate -ResourcePool $myResourcePool -OSCustomizationSpec $mySpecification

Creates a virtual machine from the specified template and applies the specified customization specification.

-------------- Example 11 --------------

cd vmstores:\myserver@443\Datacenter\Storage1\MyVM1\
$vmxFile = Get-Item MyVM1.vmx
$vmhost = Get-VMHost -Name MyVMHost1
New-VM -VMHost $vmhost -VMFilePath $vmxFile.DatastoreFullPath

Retrieves the specified configuration file for the MyVM1 virtual machine and registers the MyVM1 virtual machine on the specified host.

-------------- Example 12 --------------

$vmhost = Get-VMHost -Name MyVMHost1
$myDatastoreCluster = Get-DatastoreCluster -Name MyStorageCluster1
New-VM -Name MyVM1 -DiskGB 40,40 -Datastore $myDatastoreCluster -ResourcePool $vmhost

Creates a virtual machine on a datastore cluster. By default, the new virtual machine has an intra-VM affinity rule.

-------------- Example 13 --------------

$vmhost = Get-VMHost -Name MyVMHost1
$myDatastoreCluster = Get-DatastoreCluster -Name MyStorageCluster1
$myAdvancedOption = New-Object 'VMware.VimAutomation.ViCore.Types.V1.DatastoreManagement.SdrsVMDiskAntiAffinityRule' 1,2
New-VM -Name MyVM1 -DiskGB 40,40,40 -Datastore $myDatastoreCluster -AdvancedOption $myAdvancedOption -ResourcePool $vmhost

Creates a virtual machine on a datastore cluster. The machine has three hard disks. For the first two disks, intra-VM anti-affinity rule is specified and they will be placed on a datastore different from the datastore cluster. Identifying the hard disk in the Intra-VM anti-affinity happens by indexing the disks starting from 1.

-------------- Example 14 --------------

$myVM1 = Get-VM -Name WindowsXP
$myResourcePool = Get-ResourcePool -Name MyResourcePool1
$myAdvancedOption = New-Object 'VMware.VimAutomation.ViCore.Types.V1.DatastoreManagement.SdrsVMAntiAffinityRule' $myVM1
$myDatastoreCluster = Get-DatastoreCluster -Name MyStorageCluster1
New-VM -Name MyVM1 -DiskGB 40,40,40 -Datastore $myDatastoreCluster -AdvancedOption $myAdvancedOption -ResourcePool $myResourcePool

Creates a virtual machine on a datastore cluster and specifies a VM anti-affinity rule between the new virtual machine and an existing virtual machine.

-------------- Example 15 --------------

$mySourceVM = Get-VM -Name MySourceVM1
$vmhost = Get-VMHost -Name MyVMHost1
$hardDiskList = Get-HardDisk -VM $vm | select -First 2
$myDatastoreCluster = Get-DatastoreCluster -Name MyStorageCluster1
$myAdvancedOption = New-Object 'VMware.VimAutomation.ViCore.Types.V1.DatastoreManagement.SdrsVMDiskAntiAffinityRule' $hardDiskList
New-VM -Name MyVM1 -VM $mySourceVM -Datastore $myDatastoreCluster -AdvancedOption $myAdvancedOption -ResourcePool $vmhost

Clones a virtual machine on a datastore cluster and specifies an intra-VM anti-affinity rule by using references to the hard disks of the source virtual machine. When you apply this rule to the AdvancedOption parameter of New-VM, the first and second disk of the new virtual machine will be placed on different datastores within the specified datastore cluster.

-------------- Example 16 --------------

$mySourceVM = Get-VM -Name MySourceVM1
$myVM1 = Get-VM -Name WindowsXP
$myAdvancedOption = New-Object 'VMware.VimAutomation.ViCore.Types.V1.DatastoreManagement.SdrsVMAntiAffinityRule' $myVM1
$myDatastoreCluster = Get-DatastoreCluster -Name MyStorageCluster1
$vmhost = Get-VMHost -Name MyVMHost1
New-VM -Name MyVM2 -VM $mySourceVM -Datastore $myDatastoreCluster -AdvancedOption $myAdvancedOption -ResourcePool $vmhost

Clones a virtual machine on a datastore cluster and specifies a VM anti-afffinity rule between the new virtual machine and an existing virtual machine. When you apply this rule to the AdvancedOption parameter of New-VM, the new virtual machine and the WindowsXP virtual machine will be placed on different datastores within the specified datastore cluster.

-------------- Example 17 --------------

$mySourceTemplate = Get-Template -Name WindowsTemplate
$myDatastoreCluster = Get-DatastoreCluster -Name MyStorageCluster
$myAdvancedOption = New-Object 'VMware.VimAutomation.ViCore.Types.V1.DatastoreManagement.SdrsVMDiskAntiAffinityRule' $hardDiskList
$vmhost = Get-VMHost -Name MyVMHost1
New-VM -Name MyVM1 -Template $mySourceTemplate -Datastore $myDatastoreCluster -AdvancedOption $myAdvancedOption -ResourcePool $vmhost

Creates a virtual machine from a template, specifies a VM anti-affinity rule, and stores the virtual machine on a specified datastore cluster.

-------------- Example 18 --------------

$vmhost = Get-VMHost -Name MyVMHost1
$myVM = Get-VM -Name WindowsXP
$mySourceTemplate = Get-Template -Name WindowsTemplate
$myDatastoreCluster = Get-DatastoreCluster -Name MyStorageCluster1
$myAdvancedOption = New-Object 'VMware.VimAutomation.ViCore.Types.V1.DatastoreManagement.SdrsVMAntiAffinityRule' $myVM
New-VM -Name VM -Template $mySourceTemplate -Datastore $myDatastoreCluster -AdvancedOption $myAdvancedOption -ResourcePool $vmhost

Creates a virtual machine from a template, specifies a VM anti-affinity rule, and stores the virtual machine on a specified datastore cluster.

-------------- Example 19 --------------

$mySourceVM = Get-VM -Name MySourceVM1
$myReferenceSnapshot = Get-Snapshot -VM $mySourceVM -Name "InitialState"
$vmhost = Get-VMHost -Name MyVMHost1
$myDatastore = Get-Datastore -Name MyDatastore1
New-VM -Name MyLinkedCloneVM1 -VM $mySourceVM -LinkedClone -ReferenceSnapshot $myReferenceSnapshot -ResourcePool $vmhost -Datastore $myDatastore

Creates a linked clone from the specified snapshot of the parent virtual machine. The linked clone is stored to the specified VM host and datastore.

-------------- Example 20 --------------

$myCluster = Get-Cluster -Name "MyCluster"
$myVDPortGroup = Get-VDPortgroup -Name "MyVDPortGroup"
$mySharedDatastore = Get-Datastore -Name "MySharedDatastore"
New-VM -Name MyVM -ResourcePool $myCluster -Portgroup $myVDPortGroup -DiskGB 40 -MemoryGB 4 -Datastore $mySharedDatastore

Creates a new virtual machine with the specified configuration and connects it to the specified distributed port group.


Copyright © VMware, Inc. All rights reserved.