From bdf3e18ceaed3334afdb39662dc548dbf45401cd Mon Sep 17 00:00:00 2001 From: Anthony ARNAUD Date: Tue, 30 Mar 2021 23:19:39 -0400 Subject: [PATCH] feat: add vgpu to vm resource Add a new option `shared-pci-device-id` to the `virtual machine` resource. This enables users to 1 or more vGPU to the VM as an update to the resource or during the clone operation. --- .../virtual_machine_device_subresource.go | 147 ++++- vsphere/resource_vsphere_virtual_machine.go | 48 +- website/docs/r/virtual_machine.html.markdown | 509 +++++++++--------- 3 files changed, 452 insertions(+), 252 deletions(-) diff --git a/vsphere/internal/virtualdevice/virtual_machine_device_subresource.go b/vsphere/internal/virtualdevice/virtual_machine_device_subresource.go index c0430eef3..51dfbdb4e 100644 --- a/vsphere/internal/virtualdevice/virtual_machine_device_subresource.go +++ b/vsphere/internal/virtualdevice/virtual_machine_device_subresource.go @@ -1018,7 +1018,7 @@ func (c *pciApplyConfig) modifyVirtualPciDevices(devList *schema.Set, op types.V } // PciPassthroughApplyOperation checks for changes in a virtual machine's -// PCI passthrough devices and creates config specs to apply apply to the +// PCI passthrough devices and creates config specs to apply to the // virtual machine. func PciPassthroughApplyOperation(d *schema.ResourceData, c *govmomi.Client, l object.VirtualDeviceList) (object.VirtualDeviceList, []types.BaseVirtualDeviceConfigSpec, error) { old, newValue := d.GetChange("pci_device_id") @@ -1095,3 +1095,148 @@ func PciPassthroughPostCloneOperation(d *schema.ResourceData, c *govmomi.Client, } return applyConfig.VirtualDevice, applyConfig.Spec, nil } + +// modifyVirtualSharedPciDevices will take a list of devices and an operation and +// will create the appropriate config spec. +func (c *pciApplyConfig) modifyVirtualSharedPciDevices(devList *schema.Set, op types.VirtualDeviceConfigSpecOperation) error { + log.Printf("VirtualMachine: Creating Shared PCI device specs %v", op) + for _, devId := range devList.List() { + log.Printf("[DEBUG] modifyVirtualSharedPciDevices: Appending %v spec for %s", op, devId.(string)) + + dev := &types.VirtualPCIPassthrough{ + VirtualDevice: types.VirtualDevice{ + DynamicData: types.DynamicData{}, + Backing: &types.VirtualPCIPassthroughVmiopBackingInfo{ + Vgpu: devId.(string), + }, + }, + } + + vm, err := virtualmachine.FromUUID(c.Client, c.ResourceData.Id()) + if err != nil { + return err + } + + vprops, err := virtualmachine.Properties(vm) + if err != nil { + return err + } + + // This will only find a device for delete operations. + for _, vmDevP := range vprops.Config.Hardware.Device { + if vmDev, ok := vmDevP.(*types.VirtualPCIPassthrough); ok { + if vmDev.Backing.(*types.VirtualPCIPassthroughVmiopBackingInfo).Vgpu == devId { + dev = vmDev + } + } + } + + dspec, err := object.VirtualDeviceList{dev}.ConfigSpec(op) + if err != nil { + return err + } + + c.Spec = append(c.Spec, dspec...) + c.VirtualDevice = applyDeviceChange(c.VirtualDevice, dspec) + } + log.Printf("VirtualMachine: Shared PCI device specs created") + return nil +} + +// SharedPciApplyOperation checks for changes in a virtual machine's +// Shared PCI device and creates config specs to apply to the +// virtual machine. +func SharedPciApplyOperation(d *schema.ResourceData, c *govmomi.Client, l object.VirtualDeviceList) (object.VirtualDeviceList, []types.BaseVirtualDeviceConfigSpec, error) { + log.Printf("[DEBUG] SharedPciApplyOperation: Looking for shared PCI device changes") + + // Get current (old) and new devices + old, newValue := d.GetChange("shared_pci_device_id") + oldDevIds := old.(*schema.Set) + newDevIds := newValue.(*schema.Set) + + // Compare + delDevs := oldDevIds.Difference(newDevIds) + addDevs := newDevIds.Difference(oldDevIds) + + // Create base apply config + applyConfig := &pciApplyConfig{ + Client: c, + ResourceData: d, + Spec: []types.BaseVirtualDeviceConfigSpec{}, + VirtualDevice: l, + } + + // If there are no changes, return as is + if addDevs.Len() == 0 && delDevs.Len() == 0 { + log.Printf("[DEBUG] SharedPciApplyOperation: No shared PCI device additions/deletions") + return applyConfig.VirtualDevice, applyConfig.Spec, nil + } + + // Set reboot + _ = d.Set("reboot_required", true) + + // Add new Shared PCI devices + log.Printf("[DEBUG] SharedPciApplyOperation: Identified %d shared PCI device additions", + addDevs.Len()) + err := applyConfig.modifyVirtualSharedPciDevices(addDevs, types.VirtualDeviceConfigSpecOperationAdd) + if err != nil { + return nil, nil, err + } + + // Remove deleted Shared PCI devices + log.Printf("[DEBUG] SharedPciApplyOperation: Identified %d shared PCI device deletions", + delDevs.Len()) + err = applyConfig.modifyVirtualSharedPciDevices(delDevs, types.VirtualDeviceConfigSpecOperationRemove) + if err != nil { + return nil, nil, err + } + + return applyConfig.VirtualDevice, applyConfig.Spec, nil +} + +// SharedPciPostCloneOperation normalizes the Shared PCI devices +// on a newly-cloned virtual machine and outputs any necessary device change +// operations. It also sets the state in advance of the post-create read. +func SharedPciPostCloneOperation(d *schema.ResourceData, c *govmomi.Client, l object.VirtualDeviceList) (object.VirtualDeviceList, []types.BaseVirtualDeviceConfigSpec, error) { + log.Printf("[DEBUG] SharedPCIPostCloneOperation: Looking for shared PCI device changes post-clone") + + // Get current (old) and new devices + old, newValue := d.GetChange("shared_pci_device_id") + oldDevIds := old.(*schema.Set) + newDevIds := newValue.(*schema.Set) + + // Compare + delDevs := oldDevIds.Difference(newDevIds) + addDevs := newDevIds.Difference(oldDevIds) + + // Create base apply config + applyConfig := &pciApplyConfig{ + Client: c, + ResourceData: d, + Spec: []types.BaseVirtualDeviceConfigSpec{}, + VirtualDevice: l, + } + + // If there are no changes, return as is + if addDevs.Len() <= 0 && delDevs.Len() <= 0 { + log.Printf("[DEBUG] SharedPCIPostCloneOperation: No shared PCI device additions/deletions post-clone") + return applyConfig.VirtualDevice, applyConfig.Spec, nil + } + + // Add new Shared PCI devices + log.Printf("[DEBUG] SharedPCIPostCloneOperation: Identified %d shared PCI device additions post-clone", + addDevs.Len()) + err := applyConfig.modifyVirtualSharedPciDevices(addDevs, types.VirtualDeviceConfigSpecOperationAdd) + if err != nil { + return nil, nil, err + } + + // Remove deleted Shared PCI devices + log.Printf("[DEBUG] SharedPCIPostCloneOperation: Identified %d shared PCI device deletions post-clone", + delDevs.Len()) + err = applyConfig.modifyVirtualSharedPciDevices(delDevs, types.VirtualDeviceConfigSpecOperationRemove) + if err != nil { + return nil, nil, err + } + return applyConfig.VirtualDevice, applyConfig.Spec, nil +} diff --git a/vsphere/resource_vsphere_virtual_machine.go b/vsphere/resource_vsphere_virtual_machine.go index 0d600609d..d63f6b60c 100644 --- a/vsphere/resource_vsphere_virtual_machine.go +++ b/vsphere/resource_vsphere_virtual_machine.go @@ -7,7 +7,6 @@ import ( "context" "errors" "fmt" - "github.com/hashicorp/terraform-provider-vsphere/vsphere/internal/helper/guestoscustomizations" "log" "net" "os" @@ -15,6 +14,8 @@ import ( "strings" "time" + "github.com/hashicorp/terraform-provider-vsphere/vsphere/internal/helper/guestoscustomizations" + "github.com/hashicorp/terraform-provider-vsphere/vsphere/internal/helper/contentlibrary" "github.com/hashicorp/terraform-provider-vsphere/vsphere/internal/helper/ovfdeploy" @@ -244,6 +245,12 @@ func resourceVSphereVirtualMachine() *schema.Resource { Description: "A list of PCI passthrough devices", Elem: &schema.Schema{Type: schema.TypeString}, }, + "shared_pci_device_id": { + Type: schema.TypeSet, + Optional: true, + Description: "A list of Shared PCI passthrough device, 'grid_rtx8000-8q'", + Elem: &schema.Schema{Type: schema.TypeString}, + }, "clone": { Type: schema.TypeList, Optional: true, @@ -530,13 +537,23 @@ func resourceVSphereVirtualMachineRead(d *schema.ResourceData, meta interface{}) // Read the virtual machine PCI passthrough devices var pciDevs []string + var sharedPciDevs []string for _, dev := range vprops.Config.Hardware.Device { if pci, ok := dev.(*types.VirtualPCIPassthrough); ok { - if pciBacking, ok := pci.Backing.(*types.VirtualPCIPassthroughDeviceBackingInfo); ok { - devId := pciBacking.Id + switch t := pci.Backing.(type) { + case *types.VirtualPCIPassthroughDeviceBackingInfo: + devId := t.Id pciDevs = append(pciDevs, devId) - } else { - log.Printf("[DEBUG] %s: PCI passthrough device %q has no backing ID", resourceVSphereVirtualMachineIDString(d), pci.GetVirtualDevice().DeviceInfo.GetDescription()) + log.Printf("[DEBUG] Identified VM %q VirtualPCIPassthrough device %s with backing type of %T", + vm.InventoryPath, devId, pci.Backing) + case *types.VirtualPCIPassthroughVmiopBackingInfo: + dev := t.Vgpu + sharedPciDevs = append(sharedPciDevs, dev) + log.Printf("[DEBUG] Identified VM %q VirtualPCIPassthrough device %s with backing type of %T", + vm.InventoryPath, dev, pci.Backing) + default: + log.Printf("[WARN] Ignoring VM %q VirtualPCIPassthrough device with backing type of %T", + vm.InventoryPath, pci.Backing) } } } @@ -544,6 +561,10 @@ func resourceVSphereVirtualMachineRead(d *schema.ResourceData, meta interface{}) if err != nil { return err } + err = d.Set("shared_pci_device_id", sharedPciDevs) + if err != nil { + return err + } // Perform pending device read operations. devices := object.VirtualDeviceList(vprops.Config.Hardware.Device) @@ -1685,6 +1706,17 @@ func resourceVSphereVirtualMachinePostDeployChanges(d *schema.ResourceData, meta ) } cfgSpec.DeviceChange = virtualdevice.AppendDeviceChangeSpec(cfgSpec.DeviceChange, delta...) + // Shared PCI devices + devices, delta, err = virtualdevice.SharedPciPostCloneOperation(d, client, devices) + if err != nil { + return resourceVSphereVirtualMachineRollbackCreate( + d, + meta, + vm, + fmt.Errorf("error processing shared PCI device changes post-clone: %s", err), + ) + } + cfgSpec.DeviceChange = virtualdevice.AppendDeviceChangeSpec(cfgSpec.DeviceChange, delta...) log.Printf("[DEBUG] %s: Final device list: %s", resourceVSphereVirtualMachineIDString(d), virtualdevice.DeviceListString(devices)) log.Printf("[DEBUG] %s: Final device change cfgSpec: %s", resourceVSphereVirtualMachineIDString(d), virtualdevice.DeviceChangeString(cfgSpec.DeviceChange)) @@ -1988,6 +2020,12 @@ func applyVirtualDevices(d *schema.ResourceData, c *govmomi.Client, l object.Vir return nil, err } spec = virtualdevice.AppendDeviceChangeSpec(spec, delta...) + // Shared PCI device + l, delta, err = virtualdevice.SharedPciApplyOperation(d, c, l) + if err != nil { + return nil, err + } + spec = virtualdevice.AppendDeviceChangeSpec(spec, delta...) log.Printf("[DEBUG] %s: Final device list: %s", resourceVSphereVirtualMachineIDString(d), virtualdevice.DeviceListString(l)) log.Printf("[DEBUG] %s: Final device change spec: %s", resourceVSphereVirtualMachineIDString(d), virtualdevice.DeviceChangeString(spec)) return spec, nil diff --git a/website/docs/r/virtual_machine.html.markdown b/website/docs/r/virtual_machine.html.markdown index 133ad637a..74c23eb36 100644 --- a/website/docs/r/virtual_machine.html.markdown +++ b/website/docs/r/virtual_machine.html.markdown @@ -8,7 +8,7 @@ description: |- This resource can be used to create, modify, and delete virtual machines. --- -# vsphere\_virtual\_machine +# vsphere_virtual_machine The `vsphere_virtual_machine` resource is used to manage the lifecycle of a virtual machine. @@ -28,7 +28,7 @@ The `vsphere_virtual_machine` resource supports standard VMDK-backed virtual dis Disks are managed by a label supplied to the [`label`](#label) attribute in a [`disk` block](#disk-options). This is separate from the automatic naming that vSphere assigns when a virtual machine is created. Control of the name for a virtual disk is not supported unless you are attaching an external disk with the [`attach`](#attach) attribute. -Virtual disks can be SCSI, SATA, or IDE. The storage controllers managed by the Terraform provider can vary, depending on the value supplied to [`scsi_controller_count`](#scsi_controller_count), [`sata_controller_count`](#sata_controller_count), or [`ide_controller_count`](#ide_controller_count). This also dictates the controllers that are checked when looking for disks during a cloning process. SCSI controllers are all configured with the controller type defined by the [`scsi_type`](#scsi_type) setting. If you are cloning from a template, devices will be added or re-configured as necessary. +Virtual disks can be SCSI, SATA, or IDE. The storage controllers managed by the Terraform provider can vary, depending on the value supplied to [`scsi_controller_count`](#scsi_controller_count), [`sata_controller_count`](#sata_controller_count), or [`ide_controller_count`](#ide_controller_count). This also dictates the controllers that are checked when looking for disks during a cloning process. SCSI controllers are all configured with the controller type defined by the [`scsi_type`](#scsi_type) setting. If you are cloning from a template, devices will be added or re-configured as necessary. When cloning from a template, you must specify disks of either the same or greater size than the disks in the source template or the same size when cloning from a snapshot (also known as a linked clone). @@ -40,11 +40,11 @@ Terraform waits during various parts of a virtual machine deployment to ensure t The waiters include the following: -* **Customization Waiter**: +- **Customization Waiter**: This waiter watches events in vSphere to monitor when customization on a virtual machine completes during creation. Depending on your vSphere or virtual machine configuration, it may be necessary to change the timeout or turn off the waiter. This can be controlled by using the [`timeout`](#timeout-1) setting in the [customization settings](#virtual-machine-customizations) block. -* **Network Waiter**: +- **Network Waiter**: This waiter waits for interfaces to appear on a virtual machine guest operating system and occurs close to the end of both virtual machine creation and update. This waiter ensures that the IP information gets reported to the guest operating system, mainly to facilitate the availability of a valid, reachable default IP address for any provisioners. @@ -58,13 +58,13 @@ The following block contains the option necessary to create a virtual machine, w In this example, the resource makes use of the following data sources: -* [`vsphere_datacenter`][tf-vsphere-datacenter] to locate the datacenter, +- [`vsphere_datacenter`][tf-vsphere-datacenter] to locate the datacenter, -* [`vsphere_datastore`][tf-vsphere-datastore] to locate the default datastore to place the virtual machine files, +- [`vsphere_datastore`][tf-vsphere-datastore] to locate the default datastore to place the virtual machine files, -* [`vsphere_compute-cluster`][tf-vsphere-compute-cluster] to locate a resource pool located in a cluster or standalone host, and +- [`vsphere_compute-cluster`][tf-vsphere-compute-cluster] to locate a resource pool located in a cluster or standalone host, and -* [`vsphere_network`][tf-vsphere-network] to locate the network. +- [`vsphere_network`][tf-vsphere-network] to locate the network. [tf-vsphere-datacenter]: /docs/providers/vsphere/d/datacenter.html [tf-vsphere-datastore]: /docs/providers/vsphere/d/datastore.html @@ -608,25 +608,27 @@ The following arguments are supported: The following options are general virtual machine and provider workflow options: -* `alternate_guest_name` - (Optional) The guest name for the operating system when `guest_id` is `otherGuest` or `otherGuest64`. +- `alternate_guest_name` - (Optional) The guest name for the operating system when `guest_id` is `otherGuest` or `otherGuest64`. -* `annotation` - (Optional) A user-provided description of the virtual machine. +- `annotation` - (Optional) A user-provided description of the virtual machine. -* `cdrom` - (Optional) A specification for a CD-ROM device on the virtual machine. See [CD-ROM options](#cd-rom-options) for more information. +- `cdrom` - (Optional) A specification for a CD-ROM device on the virtual machine. See [CD-ROM options](#cd-rom-options) for more information. -* `clone` - (Optional) When specified, the virtual machine will be created as a clone of a specified template. Optional customization options can be submitted for the resource. See [creating a virtual machine from a template](#creating-a-virtual-machine-from-a-template) for more information. +- `clone` - (Optional) When specified, the virtual machine will be created as a clone of a specified template. Optional customization options can be submitted for the resource. See [creating a virtual machine from a template](#creating-a-virtual-machine-from-a-template) for more information. -* `extra_config_reboot_required` - (Optional) Allow the virtual machine to be rebooted when a change to `extra_config` occurs. Default: `true`. +~> **NOTE:** Cloning requires vCenter Server and is not supported on direct ESXi host connections. + +- `extra_config_reboot_required` - (Optional) Allow the virtual machine to be rebooted when a change to `extra_config` occurs. Default: `true`. -* `custom_attributes` - (Optional) Map of custom attribute ids to attribute value strings to set for virtual machine. Please refer to the [`vsphere_custom_attributes`][docs-setting-custom-attributes] resource for more information on setting custom attributes. +- `custom_attributes` - (Optional) Map of custom attribute ids to attribute value strings to set for virtual machine. Please refer to the [`vsphere_custom_attributes`][docs-setting-custom-attributes] resource for more information on setting custom attributes. [docs-setting-custom-attributes]: /docs/providers/vsphere/r/custom_attribute.html#using-custom-attributes-in-a-supported-resource ~> **NOTE:** Custom attributes requires vCenter Server and is not supported on direct ESXi host connections. -* `datastore_id` - (Optional) The [managed object reference ID][docs-about-morefs] of the datastore in which to place the virtual machine. The virtual machine configuration files is placed here, along with any virtual disks that are created where a datastore is not explicitly specified. See the section on [virtual machine migration](#virtual-machine-migration) for more information on modifying this value. +- `datastore_id` - (Optional) The [managed object reference ID][docs-about-morefs] of the datastore in which to place the virtual machine. The virtual machine configuration files is placed here, along with any virtual disks that are created where a datastore is not explicitly specified. See the section on [virtual machine migration](#virtual-machine-migration) for more information on modifying this value. -* `datastore_cluster_id` - (Optional) The [managed object reference ID][docs-about-morefs] of the datastore cluster in which to place the virtual machine. This setting applies to entire virtual machine and implies that you wish to use vSphere Storage DRS with the virtual machine. See the section on [virtual machine migration](#virtual-machine-migration) for more information on modifying this value. +- `datastore_cluster_id` - (Optional) The [managed object reference ID][docs-about-morefs] of the datastore cluster in which to place the virtual machine. This setting applies to entire virtual machine and implies that you wish to use vSphere Storage DRS with the virtual machine. See the section on [virtual machine migration](#virtual-machine-migration) for more information on modifying this value. ~> **NOTE:** One of `datastore_id` or `datastore_cluster_id` must be specified. @@ -634,44 +636,44 @@ The following options are general virtual machine and provider workflow options: ~> **NOTE:** The `datastore_cluster_id` setting applies to the entire virtual machine resource. You cannot assign individual individual disks to datastore clusters. In addition, you cannot use the [`attach`](#attach) setting to attach external disks on virtual machines that are assigned to datastore clusters. -* `datacenter_id` - (Optional) The datacenter ID. Required only when deploying an OVF/OVA template. +- `datacenter_id` - (Optional) The datacenter ID. Required only when deploying an OVF/OVA template. -* `disk` - (Required) A specification for a virtual disk device on the virtual machine. See [disk options](#disk-options) for more information. +- `disk` - (Required) A specification for a virtual disk device on the virtual machine. See [disk options](#disk-options) for more information. -* `extra_config` - (Optional) Extra configuration data for the virtual machine. Can be used to supply advanced parameters not normally in configuration, such as instance metadata and userdata. +- `extra_config` - (Optional) Extra configuration data for the virtual machine. Can be used to supply advanced parameters not normally in configuration, such as instance metadata and userdata. ~> **NOTE:** Do not use `extra_config` when working with a template imported from OVF/OVA as your settings may be ignored. Use the `vapp` block `properties` section as described in [Using vApp Properties for OVF/OVA Configuration](#using-vapp-properties-for-ovf-ova-configuration). -* `firmware` - (Optional) The firmware for the virtual machine. One of `bios` or `efi`. +- `firmware` - (Optional) The firmware for the virtual machine. One of `bios` or `efi`. -* `folder` - (Optional) The path to the virtual machine folder in which to place the virtual machine, relative to the datacenter path (`//vm`). For example, `/dc-01/vm/foo` +- `folder` - (Optional) The path to the virtual machine folder in which to place the virtual machine, relative to the datacenter path (`//vm`). For example, `/dc-01/vm/foo` -* `guest_id` - (Optional) The guest ID for the operating system type. For a full list of possible values, see [here][vmware-docs-guest-ids]. Default: `otherGuest64`. +- `guest_id` - (Optional) The guest ID for the operating system type. For a full list of possible values, see [here][vmware-docs-guest-ids]. Default: `otherGuest64`. [vmware-docs-guest-ids]: https://vdc-repo.vmware.com/vmwb-repository/dcr-public/184bb3ba-6fa8-4574-a767-d0c96e2a38f4/ba9422ef-405c-47dd-8553-e11b619185b2/SDK/vsphere-ws/docs/ReferenceGuide/vim.vm.GuestOsDescriptor.GuestOsIdentifier.html -* `hardware_version` - (Optional) The hardware version number. Valid range is from 4 to 21. The hardware version cannot be downgraded. See virtual machine hardware [versions][virtual-machine-hardware-versions] and [compatibility][virtual-machine-hardware-compatibility] for more information on supported settings. +- `hardware_version` - (Optional) The hardware version number. Valid range is from 4 to 21. The hardware version cannot be downgraded. See virtual machine hardware [versions][virtual-machine-hardware-versions] and [compatibility][virtual-machine-hardware-compatibility] for more information on supported settings. [virtual-machine-hardware-versions]: https://kb.vmware.com/s/article/1003746 [virtual-machine-hardware-compatibility]: https://kb.vmware.com/s/article/2007240 -* `host_system_id` - (Optional) The [managed object reference ID][docs-about-morefs] of a host on which to place the virtual machine. See the section on [virtual machine migration](#virtual-machine-migration) for more information on modifying this value. When using a vSphere cluster, if a `host_system_id` is not supplied, vSphere will select a host in the cluster to place the virtual machine, according to any defaults or vSphere DRS placement policies. +- `host_system_id` - (Optional) The [managed object reference ID][docs-about-morefs] of a host on which to place the virtual machine. See the section on [virtual machine migration](#virtual-machine-migration) for more information on modifying this value. When using a vSphere cluster, if a `host_system_id` is not supplied, vSphere will select a host in the cluster to place the virtual machine, according to any defaults or vSphere DRS placement policies. -* `name` - (Required) The name of the virtual machine. +- `name` - (Required) The name of the virtual machine. -* `network_interface` - (Required) A specification for a virtual NIC on the virtual machine. See [network interface options](#network-interface-options) for more information. +- `network_interface` - (Required) A specification for a virtual NIC on the virtual machine. See [network interface options](#network-interface-options) for more information. -* `pci_device_id` - (Optional) List of host PCI device IDs in which to create PCI passthroughs. +- `pci_device_id` - (Optional) List of host PCI device IDs in which to create PCI passthroughs. -~> **NOTE:** Cloning requires vCenter Server and is not supported on direct ESXi host connections. +- `shared_pci_device_id` - (Optional) A shared PCI device ID to create PCI passthrough. -* `ovf_deploy` - (Optional) When specified, the virtual machine will be deployed from the provided OVF/OVA template. See [creating a virtual machine from an OVF/OVA template](#creating-a-virtual-machine-from-an-ovf-ova-template) for more information. +- `ovf_deploy` - (Optional) When specified, the virtual machine will be deployed from the provided OVF/OVA template. See [creating a virtual machine from an OVF/OVA template](#creating-a-virtual-machine-from-an-ovf-ova-template) for more information. -* `replace_trigger` - (Optional) Triggers replacement of resource whenever it changes. +- `replace_trigger` - (Optional) Triggers replacement of resource whenever it changes. -For example, `replace_trigger = sha256(format("%s-%s",data.template_file.cloud_init_metadata.rendered,data.template_file.cloud_init_userdata.rendered))` will fingerprint the changes in cloud-init metadata and userdata templates. This will enable a replacement of the resource whenever the dependant template renders a new configuration. (Forces a replacement.) + For example, `replace_trigger = sha256(format("%s-%s",data.template_file.cloud_init_metadata.rendered,data.template_file.cloud_init_userdata.rendered))` will fingerprint the changes in cloud-init metadata and userdata templates. This will enable a replacement of the resource whenever the dependant template renders a new configuration. (Forces a replacement.) -* `resource_pool_id` - (Required) The [managed object reference ID][docs-about-morefs] of the resource pool in which to place the virtual machine. See the [Virtual Machine Migration](#virtual-machine-migration) section for more information on modifying this value. +- `resource_pool_id` - (Required) The [managed object reference ID][docs-about-morefs] of the resource pool in which to place the virtual machine. See the [Virtual Machine Migration](#virtual-machine-migration) section for more information on modifying this value. [docs-about-morefs]: /docs/providers/vsphere/index.html#use-of-managed-object-references-by-the-vsphere-provider @@ -679,31 +681,45 @@ For example, `replace_trigger = sha256(format("%s-%s",data.template_file.cloud_i [docs-resource-pool-cluster-default]: /docs/providers/vsphere/d/resource_pool.html#specifying-the-root-resource-pool-for-a-standalone-host -* `scsi_type` - (Optional) The SCSI controller type for the virtual machine. One of `lsilogic` (LSI Logic Parallel), `lsilogic-sas` (LSI Logic SAS) or `pvscsi` (VMware Paravirtual). Default: `pvscsi`. +- `scsi_type` - (Optional) The SCSI controller type for the virtual machine. One of `lsilogic` (LSI Logic Parallel), `lsilogic-sas` (LSI Logic SAS) or `pvscsi` (VMware Paravirtual). Default: `pvscsi`. + +- `scsi_bus_sharing` - (Optional) The type of SCSI bus sharing for the virtual machine SCSI controller. One of `physicalSharing`, `virtualSharing`, and `noSharing`. Default: `noSharing`. + +- # `storage_policy_id` - (Optional) The ID of the storage policy to assign to the home directory of a virtual machine. -* `scsi_bus_sharing` - (Optional) The type of SCSI bus sharing for the virtual machine SCSI controller. One of `physicalSharing`, `virtualSharing`, and `noSharing`. Default: `noSharing`. +- `shared_pci_device_id` - (Optional) List of shared PCI device(s) to create + shared PCI passthrough. -* `storage_policy_id` - (Optional) The ID of the storage policy to assign to the home directory of a virtual machine. +For example, attaching a vGPU to the virtual machine: +`shared_pci_device_id = ["grid_a100d-40c"]` -* `tags` - (Optional) The IDs of any tags to attach to this resource. Please refer to the [`vsphere_tag`][docs-applying-tags] resource for more information on applying tags to virtual machine resources. +~> **NOTE:** The use of vGPU requires that the VM has memory reservation set equal +to the amount of provisioned memory. This can be accomplished by leveraging +the [`memory_reservation`](#memory_reservation) option. + +- `storage_policy_id` - (Optional) The ID of the storage policy to assign to the home directory of a virtual machine. + + > > > > > > > 0276fdd7 (feat: add vgpu to vm resource) + +- `tags` - (Optional) The IDs of any tags to attach to this resource. Please refer to the [`vsphere_tag`][docs-applying-tags] resource for more information on applying tags to virtual machine resources. [docs-applying-tags]: /docs/providers/vsphere/r/tag.html#using-tags-in-a-supported-resource ~> **NOTE:** Tagging support is unsupported on direct ESXi host connections and requires vCenter Server instance. -* `vapp` - (Optional) Used for vApp configurations. The only sub-key available is `properties`, which is a key/value map of properties for virtual machines imported from and OVF/OVA. See [Using vApp Properties for OVF/OVA Configuration](#using-vapp-properties-for-ovf-ova-configuration) for more information. +- `vapp` - (Optional) Used for vApp configurations. The only sub-key available is `properties`, which is a key/value map of properties for virtual machines imported from and OVF/OVA. See [Using vApp Properties for OVF/OVA Configuration](#using-vapp-properties-for-ovf-ova-configuration) for more information. ### CPU and Memory Options The following options control CPU and memory settings on a virtual machine: -* `cpu_hot_add_enabled` - (Optional) Allow CPUs to be added to the virtual machine while it is powered on. +- `cpu_hot_add_enabled` - (Optional) Allow CPUs to be added to the virtual machine while it is powered on. -* `cpu_hot_remove_enabled` - (Optional) Allow CPUs to be removed to the virtual machine while it is powered on. +- `cpu_hot_remove_enabled` - (Optional) Allow CPUs to be removed to the virtual machine while it is powered on. -* `memory` - (Optional) The memory size to assign to the virtual machine, in MB. Default: `1024` (1 GB). +- `memory` - (Optional) The memory size to assign to the virtual machine, in MB. Default: `1024` (1 GB). -* `memory_hot_add_enabled` - (Optional) Allow memory to be added to the virtual machine while it is powered on. +- `memory_hot_add_enabled` - (Optional) Allow memory to be added to the virtual machine while it is powered on. ~> **NOTE:** CPU and memory hot add options are not available on all guest operating systems. Please refer to the [VMware Guest OS Compatibility Guide][vmware-docs-compat-guide] to which settings are allow for your guest operating system. In addition, at least one `terraform apply` must be run before you are able to use CPU and memory hot add. @@ -713,21 +729,21 @@ The following options control CPU and memory settings on a virtual machine: [vmware-kb-2008405]: https://kb.vmware.com/s/article/2008405 -* `num_cores_per_socket` - (Optional) The number of cores per socket in the virtual machine. The number of vCPUs on the virtual machine will be `num_cpus` divided by `num_cores_per_socket`. If specified, the value supplied to `num_cpus` must be evenly divisible by this value. Default: `1`. +- `num_cores_per_socket` - (Optional) The number of cores per socket in the virtual machine. The number of vCPUs on the virtual machine will be `num_cpus` divided by `num_cores_per_socket`. If specified, the value supplied to `num_cpus` must be evenly divisible by this value. Default: `1`. -* `num_cpus` - (Optional) The total number of virtual processor cores to assign to the virtual machine. Default: `1`. +- `num_cpus` - (Optional) The total number of virtual processor cores to assign to the virtual machine. Default: `1`. ### Boot Options The following options control boot settings on a virtual machine: -* `boot_delay` - (Optional) The number of milliseconds to wait before starting the boot sequence. The default is no delay. +- `boot_delay` - (Optional) The number of milliseconds to wait before starting the boot sequence. The default is no delay. -* `boot_retry_delay` - (Optional) The number of milliseconds to wait before retrying the boot sequence. This option is only valid if `boot_retry_enabled` is `true`. Default: `10000` (10 seconds). +- `boot_retry_delay` - (Optional) The number of milliseconds to wait before retrying the boot sequence. This option is only valid if `boot_retry_enabled` is `true`. Default: `10000` (10 seconds). -* `boot_retry_enabled` - (Optional) If set to `true`, a virtual machine that fails to boot will try again after the delay defined in `boot_retry_delay`. Default: `false`. +- `boot_retry_enabled` - (Optional) If set to `true`, a virtual machine that fails to boot will try again after the delay defined in `boot_retry_delay`. Default: `false`. -* `efi_secure_boot_enabled` - (Optional) Use this option to enable EFI secure boot when the `firmware` type is set to is `efi`. Default: `false`. +- `efi_secure_boot_enabled` - (Optional) Use this option to enable EFI secure boot when the `firmware` type is set to is `efi`. Default: `false`. ~> **NOTE:** EFI secure boot is only available on vSphere 6.5 and later. @@ -735,25 +751,25 @@ The following options control boot settings on a virtual machine: The following options control VMware Tools settings on the virtual machine: -* `sync_time_with_host` - (Optional) Enable the guest operating system to synchronization its clock with the host when the virtual machine is powered on or resumed. Requires vSphere 7.0 Update 1 and later. Requires VMware Tools to be installed. +- `sync_time_with_host` - (Optional) Enable the guest operating system to synchronization its clock with the host when the virtual machine is powered on or resumed. Requires vSphere 7.0 Update 1 and later. Requires VMware Tools to be installed. -* `sync_time_with_host_periodically` - (Optional) Enable the guest operating system to periodically synchronize its clock with the host. Requires vSphere 7.0 Update 1 and later. On previous versions, setting `sync_time_with_host` is will enable periodic synchronization. Requires VMware Tools to be installed. +- `sync_time_with_host_periodically` - (Optional) Enable the guest operating system to periodically synchronize its clock with the host. Requires vSphere 7.0 Update 1 and later. On previous versions, setting `sync_time_with_host` is will enable periodic synchronization. Requires VMware Tools to be installed. -* `run_tools_scripts_after_power_on` - (Optional) Enable post-power-on scripts to run when VMware Tools is installed. Default: `true`. +- `run_tools_scripts_after_power_on` - (Optional) Enable post-power-on scripts to run when VMware Tools is installed. Default: `true`. -* `run_tools_scripts_after_resume` - (Optional) Enable ost-resume scripts to run when VMware Tools is installed. Default: `true`. +- `run_tools_scripts_after_resume` - (Optional) Enable ost-resume scripts to run when VMware Tools is installed. Default: `true`. -* `run_tools_scripts_before_guest_reboot` - (Optional) Enable pre-reboot scripts to run when VMware Tools is installed. Default: `false`. +- `run_tools_scripts_before_guest_reboot` - (Optional) Enable pre-reboot scripts to run when VMware Tools is installed. Default: `false`. -* `run_tools_scripts_before_guest_shutdown` - (Optional) Enable pre-shutdown scripts to run when VMware Tools is installed. Default: `true`. +- `run_tools_scripts_before_guest_shutdown` - (Optional) Enable pre-shutdown scripts to run when VMware Tools is installed. Default: `true`. -* `run_tools_scripts_before_guest_standby` - (Optional) Enable pre-standby scripts to run when VMware Tools is installed. Default: `true`. +- `run_tools_scripts_before_guest_standby` - (Optional) Enable pre-standby scripts to run when VMware Tools is installed. Default: `true`. -* `sync_time_with_host` - (Optional) Enable the guest operating system to synchronization its clock with the host when the virtual machine is powered on or resumed. Requires vSphere 7.0 Update 1 and later. Requires VMware Tools to be installed. Default: `true`. +- `sync_time_with_host` - (Optional) Enable the guest operating system to synchronization its clock with the host when the virtual machine is powered on or resumed. Requires vSphere 7.0 Update 1 and later. Requires VMware Tools to be installed. Default: `true`. -* `sync_time_with_host_periodically` - (Optional) Enable the guest operating system to periodically synchronize its clock with the host. Requires vSphere 7.0 Update 1 and later. On previous versions, setting `sync_time_with_host` is will enable periodic synchronization. Requires VMware Tools to be installed. Default: `false`. +- `sync_time_with_host_periodically` - (Optional) Enable the guest operating system to periodically synchronize its clock with the host. Requires vSphere 7.0 Update 1 and later. On previous versions, setting `sync_time_with_host` is will enable periodic synchronization. Requires VMware Tools to be installed. Default: `false`. -* `tools_upgrade_policy` - (Optional) Enable automatic upgrade of the VMware Tools version when the virtual machine is rebooted. If necessary, VMware Tools is upgraded to the latest version supported by the host on which the virtual machine is running. Requires VMware Tools to be installed. One of `manual` or `upgradeAtPowerCycle`. Default: `manual`. +- `tools_upgrade_policy` - (Optional) Enable automatic upgrade of the VMware Tools version when the virtual machine is rebooted. If necessary, VMware Tools is upgraded to the latest version supported by the host on which the virtual machine is running. Requires VMware Tools to be installed. One of `manual` or `upgradeAtPowerCycle`. Default: `manual`. ### Resource Allocation Options @@ -761,21 +777,21 @@ The following options control CPU and memory allocation on the virtual machine. The options are: -* `cpu_limit` - (Optional) The maximum amount of CPU (in MHz) that the virtual machine can consume, regardless of available resources. The default is no limit. +- `cpu_limit` - (Optional) The maximum amount of CPU (in MHz) that the virtual machine can consume, regardless of available resources. The default is no limit. -* `cpu_reservation` - (Optional) The amount of CPU (in MHz) that the virtual machine is guaranteed. The default is no reservation. +- `cpu_reservation` - (Optional) The amount of CPU (in MHz) that the virtual machine is guaranteed. The default is no reservation. -* `cpu_share_level` - (Optional) The allocation level for the virtual machine CPU resources. One of `high`, `low`, `normal`, or `custom`. Default: `custom`. +- `cpu_share_level` - (Optional) The allocation level for the virtual machine CPU resources. One of `high`, `low`, `normal`, or `custom`. Default: `custom`. -* `cpu_share_count` - (Optional) The number of CPU shares allocated to the virtual machine when the `cpu_share_level` is `custom`. +- `cpu_share_count` - (Optional) The number of CPU shares allocated to the virtual machine when the `cpu_share_level` is `custom`. -* `memory_limit` - (Optional) The maximum amount of memory (in MB) that th virtual machine can consume, regardless of available resources. The default is no limit. +- `memory_limit` - (Optional) The maximum amount of memory (in MB) that th virtual machine can consume, regardless of available resources. The default is no limit. -* `memory_reservation` - (Optional) The amount of memory (in MB) that the virtual machine is guaranteed. The default is no reservation. +- `memory_reservation` - (Optional) The amount of memory (in MB) that the virtual machine is guaranteed. The default is no reservation. -* `memory_share_level` - (Optional) The allocation level for the virtual machine memory resources. One of `high`, `low`, `normal`, or `custom`. Default: `custom`. +- `memory_share_level` - (Optional) The allocation level for the virtual machine memory resources. One of `high`, `low`, `normal`, or `custom`. Default: `custom`. -* `memory_share_count` - (Optional) The number of memory shares allocated to the virtual machine when the `memory_share_level` is `custom`. +- `memory_share_count` - (Optional) The number of memory shares allocated to the virtual machine when the `memory_share_level` is `custom`. ### Advanced Options @@ -783,53 +799,53 @@ The following options control advanced operation of the virtual machine, or cont The options are: -* `cpu_performance_counters_enabled` - (Optional) Enable CPU performance counters on the virtual machine. Default: `false`. +- `cpu_performance_counters_enabled` - (Optional) Enable CPU performance counters on the virtual machine. Default: `false`. -* `enable_disk_uuid` - (Optional) Expose the UUIDs of attached virtual disks to the virtual machine, allowing access to them in the guest. Default: `false`. +- `enable_disk_uuid` - (Optional) Expose the UUIDs of attached virtual disks to the virtual machine, allowing access to them in the guest. Default: `false`. -* `enable_logging` - (Optional) Enable logging of virtual machine events to a log file stored in the virtual machine directory. Default: `false`. +- `enable_logging` - (Optional) Enable logging of virtual machine events to a log file stored in the virtual machine directory. Default: `false`. -* `ept_rvi_mode` - (Optional) The EPT/RVI (hardware memory virtualization) setting for the virtual machine. One of `automatic`, `on`, or `off`. Default: `automatic`. +- `ept_rvi_mode` - (Optional) The EPT/RVI (hardware memory virtualization) setting for the virtual machine. One of `automatic`, `on`, or `off`. Default: `automatic`. -* `force_power_off` - (Optional) If a guest shutdown failed or times out while updating or destroying (see [`shutdown_wait_timeout`](#shutdown_wait_timeout)), force the power-off of the virtual machine. Default: `true`. +- `force_power_off` - (Optional) If a guest shutdown failed or times out while updating or destroying (see [`shutdown_wait_timeout`](#shutdown_wait_timeout)), force the power-off of the virtual machine. Default: `true`. -* `hv_mode` - (Optional) The hardware virtualization (non-nested) setting for the virtual machine. One of `hvAuto`, `hvOn`, or `hvOff`. Default: `hvAuto`. +- `hv_mode` - (Optional) The hardware virtualization (non-nested) setting for the virtual machine. One of `hvAuto`, `hvOn`, or `hvOff`. Default: `hvAuto`. -* `ide_controller_count` - (Optional) The number of IDE controllers that the virtual machine. This directly affects the number of disks you can add to the virtual machine and the maximum disk unit number. Note that lowering this value does not remove controllers. Default: `2`. +- `ide_controller_count` - (Optional) The number of IDE controllers that the virtual machine. This directly affects the number of disks you can add to the virtual machine and the maximum disk unit number. Note that lowering this value does not remove controllers. Default: `2`. -* `ignored_guest_ips` - (Optional) List of IP addresses and CIDR networks to ignore while waiting for an available IP address using either of the waiters. Any IP addresses in this list will be ignored so that the waiter will continue to wait for a valid IP address. Default: `[]`. +- `ignored_guest_ips` - (Optional) List of IP addresses and CIDR networks to ignore while waiting for an available IP address using either of the waiters. Any IP addresses in this list will be ignored so that the waiter will continue to wait for a valid IP address. Default: `[]`. -* `latency_sensitivity` - (Optional) Controls the scheduling delay of the virtual machine. Use a higher sensitivity for applications that require lower latency, such as VOIP, media player applications, or applications that require frequent access to mouse or keyboard devices. One of `low`, `normal`, `medium`, or `high`. +- `latency_sensitivity` - (Optional) Controls the scheduling delay of the virtual machine. Use a higher sensitivity for applications that require lower latency, such as VOIP, media player applications, or applications that require frequent access to mouse or keyboard devices. One of `low`, `normal`, `medium`, or `high`. ~> **NOTE:** On higher sensitivities, you may need to adjust the [`memory_reservation`](#memory_reservation) to the full amount of memory provisioned for the virtual machine. -* `migrate_wait_timeout` - (Optional) The amount of time, in minutes, to wait for a virtual machine migration to complete before failing. Default: `10` minutes. See the section on [virtual machine migration](#virtual-machine-migration) for more information. +- `migrate_wait_timeout` - (Optional) The amount of time, in minutes, to wait for a virtual machine migration to complete before failing. Default: `10` minutes. See the section on [virtual machine migration](#virtual-machine-migration) for more information. -* `nested_hv_enabled` - (Optional) Enable nested hardware virtualization on the virtual machine, facilitating nested virtualization in the guest operating system. Default: `false`. +- `nested_hv_enabled` - (Optional) Enable nested hardware virtualization on the virtual machine, facilitating nested virtualization in the guest operating system. Default: `false`. -* `sata_controller_count` - (Optional) The number of SATA controllers that the virtual machine. This directly affects the number of disks you can add to the virtual machine and the maximum disk unit number. Note that lowering this value does not remove controllers. Default: `0`. +- `sata_controller_count` - (Optional) The number of SATA controllers that the virtual machine. This directly affects the number of disks you can add to the virtual machine and the maximum disk unit number. Note that lowering this value does not remove controllers. Default: `0`. -* `scsi_controller_count` - (Optional) The number of SCSI controllers on the virtual machine. This setting directly affects the number of disks you can add to the virtual machine and the maximum disk unit number. Note that lowering this value does not remove controllers. Default: `1`. +- `scsi_controller_count` - (Optional) The number of SCSI controllers on the virtual machine. This setting directly affects the number of disks you can add to the virtual machine and the maximum disk unit number. Note that lowering this value does not remove controllers. Default: `1`. -* `shutdown_wait_timeout` - (Optional) The amount of time, in minutes, to wait for a graceful guest shutdown when making necessary updates to the virtual machine. If `force_power_off` is set to `true`, the virtual machine will be forced to power-off after the timeout, otherwise an error is returned. Default: `3` minutes. +- `shutdown_wait_timeout` - (Optional) The amount of time, in minutes, to wait for a graceful guest shutdown when making necessary updates to the virtual machine. If `force_power_off` is set to `true`, the virtual machine will be forced to power-off after the timeout, otherwise an error is returned. Default: `3` minutes. -* `swap_placement_policy` - (Optional) The swap file placement policy for the virtual machine. One of `inherit`, `hostLocal`, or `vmDirectory`. Default: `inherit`. +- `swap_placement_policy` - (Optional) The swap file placement policy for the virtual machine. One of `inherit`, `hostLocal`, or `vmDirectory`. Default: `inherit`. -* `vbs_enabled` - (Optional) Enable Virtualization Based Security. Requires `firmware` to be `efi`. In addition, `vvtd_enabled`, `nested_hv_enabled`, and `efi_secure_boot_enabled` must all have a value of `true`. Supported on vSphere 6.7 and later. Default: `false`. +- `vbs_enabled` - (Optional) Enable Virtualization Based Security. Requires `firmware` to be `efi`. In addition, `vvtd_enabled`, `nested_hv_enabled`, and `efi_secure_boot_enabled` must all have a value of `true`. Supported on vSphere 6.7 and later. Default: `false`. -* `vvtd_enabled` - (Optional) Enable Intel Virtualization Technology for Directed I/O for the virtual machine (_I/O MMU_ in the vSphere Client). Supported on vSphere 6.7 and later. Default: `false`. +- `vvtd_enabled` - (Optional) Enable Intel Virtualization Technology for Directed I/O for the virtual machine (_I/O MMU_ in the vSphere Client). Supported on vSphere 6.7 and later. Default: `false`. -* `wait_for_guest_ip_timeout` - (Optional) The amount of time, in minutes, to wait for an available guest IP address on the virtual machine. This should only be used if the version VMware Tools does not allow the [`wait_for_guest_net_timeout`](#wait_for_guest_net_timeout) waiter to be used. A value less than `1` disables the waiter. Default: `0`. +- `wait_for_guest_ip_timeout` - (Optional) The amount of time, in minutes, to wait for an available guest IP address on the virtual machine. This should only be used if the version VMware Tools does not allow the [`wait_for_guest_net_timeout`](#wait_for_guest_net_timeout) waiter to be used. A value less than `1` disables the waiter. Default: `0`. -* `wait_for_guest_net_routable` - (Optional) Controls whether or not the guest network waiter waits for a routable address. When `false`, the waiter does not wait for a default gateway, nor are IP addresses checked against any discovered default gateways as part of its success criteria. This property is ignored if the [`wait_for_guest_ip_timeout`](#wait_for_guest_ip_timeout) waiter is used. Default: `true`. +- `wait_for_guest_net_routable` - (Optional) Controls whether or not the guest network waiter waits for a routable address. When `false`, the waiter does not wait for a default gateway, nor are IP addresses checked against any discovered default gateways as part of its success criteria. This property is ignored if the [`wait_for_guest_ip_timeout`](#wait_for_guest_ip_timeout) waiter is used. Default: `true`. -* `wait_for_guest_net_timeout` - (Optional) The amount of time, in minutes, to wait for an available guest IP address on the virtual machine. Older versions of VMware Tools do not populate this property. In those cases, this waiter can be disabled and the [`wait_for_guest_ip_timeout`](#wait_for_guest_ip_timeout) waiter can be used instead. A value less than `1` disables the waiter. Default: `5` minutes. +- `wait_for_guest_net_timeout` - (Optional) The amount of time, in minutes, to wait for an available guest IP address on the virtual machine. Older versions of VMware Tools do not populate this property. In those cases, this waiter can be disabled and the [`wait_for_guest_ip_timeout`](#wait_for_guest_ip_timeout) waiter can be used instead. A value less than `1` disables the waiter. Default: `5` minutes. ### Disk Options Virtual disks are managed by adding one or more instance of the `disk` block. -At a minimum, both the `label` and `size` attributes must be provided. The `unit_number` is required for any disk other than the first, and there must be at least one resource with the implicit number of `0`. +At a minimum, both the `label` and `size` attributes must be provided. The `unit_number` is required for any disk other than the first, and there must be at least one resource with the implicit number of `0`. The following example demonstrates and abridged multi-disk configuration: @@ -853,58 +869,58 @@ resource "vsphere_virtual_machine" "vm" { The options are: -* `label` - (Required) A label for the virtual disk. Forces a new disk, if changed. +- `label` - (Required) A label for the virtual disk. Forces a new disk, if changed. ~> **NOTE:** It's recommended that you set the disk label to a format matching `diskN`, where `N` is the number of the disk, starting from disk number 0. This will ensure that your configuration is compatible when importing a virtual machine. See the section on [importing](#importing) for more information. -~> **NOTE:** Do not choose a label that starts with `orphaned_disk_` (_e.g._ `orphaned_disk_0`), as this prefix is reserved for disks that the provider does not recognize. Such as disks that are attached externally. The Terraform provider will issue +~> **NOTE:** Do not choose a label that starts with `orphaned_disk_` (_e.g._ `orphaned_disk_0`), as this prefix is reserved for disks that the provider does not recognize. Such as disks that are attached externally. The Terraform provider will issue an error if you try to label a disk with this prefix. -* `size` - (Required) The size of the disk, in GB. Must be a whole number. +- `size` - (Required) The size of the disk, in GB. Must be a whole number. -* `unit_number` - (Optional) The disk number on the storage bus. The maximum value for this setting is the value of the controller count times the controller capacity (15 for SCSI, 30 for SATA, and 2 for IDE). Duplicate unit numbers are not allowed. Default `0`, for which one disk must be set to. +- `unit_number` - (Optional) The disk number on the storage bus. The maximum value for this setting is the value of the controller count times the controller capacity (15 for SCSI, 30 for SATA, and 2 for IDE). Duplicate unit numbers are not allowed. Default `0`, for which one disk must be set to. -* `datastore_id` - (Optional) The [managed object reference ID][docs-about-morefs] for the datastore on which the virtual disk is placed. The default is to use the datastore of the virtual machine. See the section on [virtual machine migration](#virtual-machine-migration) for information on modifying this value. +- `datastore_id` - (Optional) The [managed object reference ID][docs-about-morefs] for the datastore on which the virtual disk is placed. The default is to use the datastore of the virtual machine. See the section on [virtual machine migration](#virtual-machine-migration) for information on modifying this value. ~> **NOTE:** Datastores cannot be assigned to individual disks when [`datastore_cluster_id`](#datastore_cluster_id) is used. -* `attach` - (Optional) Attach an external disk instead of creating a new one. Implies and conflicts with `keep_on_remove`. If set, you cannot set `size`, `eagerly_scrub`, or `thin_provisioned`. Must set `path` if used. +- `attach` - (Optional) Attach an external disk instead of creating a new one. Implies and conflicts with `keep_on_remove`. If set, you cannot set `size`, `eagerly_scrub`, or `thin_provisioned`. Must set `path` if used. ~> **NOTE:** External disks cannot be attached when [`datastore_cluster_id`](#datastore_cluster_id) is used. -* `path` - (Optional) When using `attach`, this parameter controls the path of a virtual disk to attach externally. Otherwise, it is a computed attribute that contains the virtual disk filename. +- `path` - (Optional) When using `attach`, this parameter controls the path of a virtual disk to attach externally. Otherwise, it is a computed attribute that contains the virtual disk filename. -* `keep_on_remove` - (Optional) Keep this disk when removing the device or destroying the virtual machine. Default: `false`. +- `keep_on_remove` - (Optional) Keep this disk when removing the device or destroying the virtual machine. Default: `false`. -* `disk_mode` - (Optional) The mode of this this virtual disk for purposes of writes and snapshots. One of `append`, `independent_nonpersistent`, `independent_persistent`, `nonpersistent`, `persistent`, or `undoable`. Default: `persistent`. For more information on these option, please refer to the [product documentation][vmware-docs-disk-mode]. +- `disk_mode` - (Optional) The mode of this this virtual disk for purposes of writes and snapshots. One of `append`, `independent_nonpersistent`, `independent_persistent`, `nonpersistent`, `persistent`, or `undoable`. Default: `persistent`. For more information on these option, please refer to the [product documentation][vmware-docs-disk-mode]. [vmware-docs-disk-mode]: https://vdc-download.vmware.com/vmwb-repository/dcr-public/da47f910-60ac-438b-8b9b-6122f4d14524/16b7274a-bf8b-4b4c-a05e-746f2aa93c8c/doc/vim.vm.device.VirtualDiskOption.DiskMode.html -* `eagerly_scrub` - (Optional) If set to `true`, the disk space is zeroed out when the virtual machine is created. This will delay the creation of the virtual disk. Cannot be set to `true` when `thin_provisioned` is `true`. See the section on [picking a disk type](#picking-a-disk-type) for more information. Default: `false`. +- `eagerly_scrub` - (Optional) If set to `true`, the disk space is zeroed out when the virtual machine is created. This will delay the creation of the virtual disk. Cannot be set to `true` when `thin_provisioned` is `true`. See the section on [picking a disk type](#picking-a-disk-type) for more information. Default: `false`. -* `thin_provisioned` - (Optional) If `true`, the disk is thin provisioned, with space for the file being allocated on an as-needed basis. Cannot be set to `true` when `eagerly_scrub` is `true`. See the section on [selecting a disk type](#selecting-a-disk-type) for more information. Default: `true`. +- `thin_provisioned` - (Optional) If `true`, the disk is thin provisioned, with space for the file being allocated on an as-needed basis. Cannot be set to `true` when `eagerly_scrub` is `true`. See the section on [selecting a disk type](#selecting-a-disk-type) for more information. Default: `true`. -* `disk_sharing` - (Optional) The sharing mode of this virtual disk. One of `sharingMultiWriter` or `sharingNone`. Default: `sharingNone`. +- `disk_sharing` - (Optional) The sharing mode of this virtual disk. One of `sharingMultiWriter` or `sharingNone`. Default: `sharingNone`. ~> **NOTE:** Disk sharing is only available on vSphere 6.0 and later. -* `write_through` - (Optional) If `true`, writes for this disk are sent directly to the filesystem immediately instead of being buffered. Default: `false`. +- `write_through` - (Optional) If `true`, writes for this disk are sent directly to the filesystem immediately instead of being buffered. Default: `false`. -* `io_limit` - (Optional) The upper limit of IOPS that this disk can use. The default is no limit. +- `io_limit` - (Optional) The upper limit of IOPS that this disk can use. The default is no limit. -* `io_reservation` - (Optional) The I/O reservation (guarantee) for the virtual disk has, in IOPS. The default is no reservation. +- `io_reservation` - (Optional) The I/O reservation (guarantee) for the virtual disk has, in IOPS. The default is no reservation. -* `io_share_level` - (Optional) The share allocation level for the virtual disk. One of `low`, `normal`, `high`, or `custom`. Default: `normal`. +- `io_share_level` - (Optional) The share allocation level for the virtual disk. One of `low`, `normal`, `high`, or `custom`. Default: `normal`. -* `io_share_count` - (Optional) The share count for the virtual disk when the share level is `custom`. +- `io_share_count` - (Optional) The share count for the virtual disk when the share level is `custom`. -* `storage_policy_id` - (Optional) The UUID of the storage policy to assign to the virtual disk. +- `storage_policy_id` - (Optional) The UUID of the storage policy to assign to the virtual disk. -* `controller_type` - (Optional) The type of storage controller to attach the disk to. Can be `scsi`, `sata`, or `ide`. You must have the appropriate number of controllers enabled for the selected type. Default `scsi`. +- `controller_type` - (Optional) The type of storage controller to attach the disk to. Can be `scsi`, `sata`, or `ide`. You must have the appropriate number of controllers enabled for the selected type. Default `scsi`. #### Computed Disk Attributes -* `uuid` - The UUID of the virtual disk VMDK file. This is used to track the virtual disk on the virtual machine. +- `uuid` - The UUID of the virtual disk VMDK file. This is used to track the virtual disk on the virtual machine. #### Virtual Disk Provisioning Policies @@ -912,15 +928,15 @@ The `eagerly_scrub` and `thin_provisioned` options control the virtual disk spac The options are: -* **Thick Provision Lazy Zeroed**: +- **Thick Provision Lazy Zeroed**: Both `eagerly_scrub` and `thin_provisioned` should be set to `false`. -* **Thick Provision Eager Zeroed**: +- **Thick Provision Eager Zeroed**: `eagerly_scrub` should be set to `true`, and `thin_provisioned` should be set to `false`. -* **Thin Provision**: +- **Thin Provision**: `eagerly_scrub` should be set to `false`, and `thin_provisioned` should be set to `true`. @@ -957,52 +973,53 @@ In the above example, the first interface is assigned to the `public` network an The options are: -* `network_id` - (Required) The [managed object reference ID][docs-about-morefs] of the network on which to connect the virtual machine network interface. +- `network_id` - (Required) The [managed object reference ID][docs-about-morefs] of the network on which to connect the virtual machine network interface. -* `adapter_type` - (Optional) The network interface type. One of `e1000`, `e1000e`, `sriov`, or `vmxnet3`. Default: `vmxnet3`. +- `adapter_type` - (Optional) The network interface type. One of `e1000`, `e1000e`, `sriov`, or `vmxnet3`. Default: `vmxnet3`. -* `use_static_mac` - (Optional) If true, the `mac_address` field is treated as a static MAC address and set accordingly. Setting this to `true` requires `mac_address` to be set. Default: `false`. +- `use_static_mac` - (Optional) If true, the `mac_address` field is treated as a static MAC address and set accordingly. Setting this to `true` requires `mac_address` to be set. Default: `false`. -* `mac_address` - (Optional) The MAC address of the network interface. Can only be manually set if `use_static_mac` is `true`. Otherwise, the value is computed and presents the assigned MAC address for the interface. +- `mac_address` - (Optional) The MAC address of the network interface. Can only be manually set if `use_static_mac` is `true`. Otherwise, the value is computed and presents the assigned MAC address for the interface. -* `bandwidth_limit` - (Optional) The upper bandwidth limit of the network interface, in Mbits/sec. The default is no limit. Ignored if `adapter_type` is set to `sriov`. +- `bandwidth_limit` - (Optional) The upper bandwidth limit of the network interface, in Mbits/sec. The default is no limit. Ignored if `adapter_type` is set to `sriov`. -* `bandwidth_reservation` - (Optional) The bandwidth reservation of the network interface, in Mbits/sec. The default is no reservation. +- `bandwidth_reservation` - (Optional) The bandwidth reservation of the network interface, in Mbits/sec. The default is no reservation. -* `bandwidth_share_level` - (Optional) The bandwidth share allocation level for the network interface. One of `low`, `normal`, `high`, or `custom`. Default: `normal`. Ignored if `adapter_type` is set to `sriov`. +- `bandwidth_share_level` - (Optional) The bandwidth share allocation level for the network interface. One of `low`, `normal`, `high`, or `custom`. Default: `normal`. Ignored if `adapter_type` is set to `sriov`. -* `bandwidth_share_count` - (Optional) The share count for the network interface when the share level is `custom`. Ignored if `adapter_type` is set to `sriov`. +- `bandwidth_share_count` - (Optional) The share count for the network interface when the share level is `custom`. Ignored if `adapter_type` is set to `sriov`. -* `ovf_mapping` - (Optional) Specifies which NIC in an OVF/OVA the `network_interface` should be associated. Only applies at creation when deploying from an OVF/OVA. +- `ovf_mapping` - (Optional) Specifies which NIC in an OVF/OVA the `network_interface` should be associated. Only applies at creation when deploying from an OVF/OVA. #### Using SR-IOV Network Interfaces -In order to attach your virtual machine to an SR-IOV network interface, +In order to attach your virtual machine to an SR-IOV network interface, there are a few requirements -* SR-IOV network interfaces must be declared after all non-SRIOV network interfaces. +- SR-IOV network interfaces must be declared after all non-SRIOV network interfaces. + +- The target host must be known, if creating a VM from scratch, this means setting the `host_system_id` option. -* The target host must be known, if creating a VM from scratch, this means setting the `host_system_id` option. +- SR-IOV must be enabled on the relevant physical adapter on the host. -* SR-IOV must be enabled on the relevant physical adapter on the host. +- The `memory_reservation` must be fully set (that is, equal to the `memory`) for the VM. -* The `memory_reservation` must be fully set (that is, equal to the `memory`) for the VM. +- The `network_interface` sub-resource takes a `physical_function` argument: -* The `network_interface` sub-resource takes a `physical_function` argument: - * This **must** be set if your adapter type is `sriov`. - * This **must not** be set if your adapter type is not `sriov`. - * This can be found by navigating to the relevant host in the vSphere Client, + - This **must** be set if your adapter type is `sriov`. + - This **must not** be set if your adapter type is not `sriov`. + - This can be found by navigating to the relevant host in the vSphere Client, going to the 'Configure' tab followed by 'Networking' then 'Physical adapters' and finding the relevant physical network adapter; one of the properties of the NIC is its PCI Location. - * This is usually in the form of "0000:ab:cd.e" + - This is usually in the form of "0000:ab:cd.e" -* The `bandwidth_*` options on the network interface are not permitted. +- The `bandwidth_*` options on the network interface are not permitted. -* Adding, modifying, and deleting SR-IOV NICs is supported but requires a VM restart. +- Adding, modifying, and deleting SR-IOV NICs is supported but requires a VM restart. -* Modifying the number of non-SR-IOV (_e.g._, VMXNET3) interfaces when there are SR-IOV interfaces existing is - explicitly blocked (as the provider does not support modifying an interface at the same index from - non-SR-IOV to SR-IOV or vice-versa). To work around this delete all SRIOV NICs for one terraform apply, and re-add +- Modifying the number of non-SR-IOV (_e.g._, VMXNET3) interfaces when there are SR-IOV interfaces existing is + explicitly blocked (as the provider does not support modifying an interface at the same index from + non-SR-IOV to SR-IOV or vice-versa). To work around this delete all SRIOV NICs for one terraform apply, and re-add them with any change to the number of non-SRIOV NICs on a second terraform apply. **Example**: @@ -1016,9 +1033,9 @@ resource "vsphere_virtual_machine" "vm" { network_interface { network_id = data.vsphere_network.network.id adapter_type = "sriov" - physical_function = "0000:3b:00.1" + physical_function = "0000:3b:00.1" } - ... other network_interfaces... + ... other network_interfaces... } ``` @@ -1043,11 +1060,11 @@ resource "vsphere_virtual_machine" "vm" { The options are: -* `client_device` - (Optional) Indicates whether the device should be backed by remote client device. Conflicts with `datastore_id` and `path`. +- `client_device` - (Optional) Indicates whether the device should be backed by remote client device. Conflicts with `datastore_id` and `path`. -* `datastore_id` - (Optional) The datastore ID that on which the ISO is located. Required for using a datastore ISO. Conflicts with `client_device`. +- `datastore_id` - (Optional) The datastore ID that on which the ISO is located. Required for using a datastore ISO. Conflicts with `client_device`. -* `path` - (Optional) The path to the ISO file. Required for using a datastore ISO. Conflicts with `client_device`. +- `path` - (Optional) The path to the ISO file. Required for using a datastore ISO. Conflicts with `client_device`. ~> **NOTE:** Either `client_device` (for a remote backed CD-ROM) or `datastore_id` and `path` (for a datastore ISO backed CD-ROM) are required to . @@ -1059,9 +1076,9 @@ Virtual devices (`disk`, `network_interface`, and `cdrom`) all export the follow The options are: -* `key` - The ID of the device within the virtual machine. +- `key` - The ID of the device within the virtual machine. -* `device_address` - An address internal to Terraform that helps locate the device when `key` is unavailable. This follows a convention of `CONTROLLER_TYPE:BUS_NUMBER:UNIT_NUMBER`. Example: `scsi:0:1` means device unit `1` on SCSI bus `0`. +- `device_address` - An address internal to Terraform that helps locate the device when `key` is unavailable. This follows a convention of `CONTROLLER_TYPE:BUS_NUMBER:UNIT_NUMBER`. Example: `scsi:0:1` means device unit `1` on SCSI bus `0`. ## Creating a Virtual Machine from a Template @@ -1075,13 +1092,13 @@ See the section on [cloning and customization](#cloning-and-customization) for m The options available in the `clone` block are: -* `template_uuid` - (Required) The UUID of the source virtual machine or template. +- `template_uuid` - (Required) The UUID of the source virtual machine or template. -* `linked_clone` - (Optional) Clone the virtual machine from a snapshot or a template. Default: `false`. +- `linked_clone` - (Optional) Clone the virtual machine from a snapshot or a template. Default: `false`. -* `timeout` - (Optional) The timeout, in minutes, to wait for the cloning process to complete. Default: 30 minutes. +- `timeout` - (Optional) The timeout, in minutes, to wait for the cloning process to complete. Default: 30 minutes. -* `customize` - (Optional) The customization spec for this clone. This allows the user to configure the virtual machine post-clone. For more details, see [virtual machine customizations](#virtual-machine-customizations). +- `customize` - (Optional) The customization spec for this clone. This allows the user to configure the virtual machine post-clone. For more details, see [virtual machine customizations](#virtual-machine-customizations). ### Virtual Machine Customizations @@ -1096,7 +1113,7 @@ The settings for `customize` are as follows: #### Customization Timeout Settings -* `timeout` - (Optional) The time, in minutes, that the provider waits for customization to complete before failing. The default is `10` minutes. Setting the value to `0` or a negative value disables the waiter. +- `timeout` - (Optional) The time, in minutes, that the provider waits for customization to complete before failing. The default is `10` minutes. Setting the value to `0` or a negative value disables the waiter. #### Network Interface Settings @@ -1159,17 +1176,17 @@ resource "vsphere_virtual_machine" "vm" { The options are: -* `dns_server_list` - (Optional) DNS servers for the network interface. Used by Windows guest operating systems, but ignored by Linux distribution guest operating systems. For Linux, please refer to the section on the [global DNS settings](#global-dns-settings). +- `dns_server_list` - (Optional) DNS servers for the network interface. Used by Windows guest operating systems, but ignored by Linux distribution guest operating systems. For Linux, please refer to the section on the [global DNS settings](#global-dns-settings). -* `dns_domain` - (Optional) DNS search domain for the network interface. Used by Windows guest operating systems, but ignored by Linux distribution guest operating systems. For Linux, please refer to the section on the [global DNS settings](#global-dns-settings). +- `dns_domain` - (Optional) DNS search domain for the network interface. Used by Windows guest operating systems, but ignored by Linux distribution guest operating systems. For Linux, please refer to the section on the [global DNS settings](#global-dns-settings). -* `ipv4_address` - (Optional) The IPv4 address assigned to the network adapter. If blank or not included, DHCP is used. +- `ipv4_address` - (Optional) The IPv4 address assigned to the network adapter. If blank or not included, DHCP is used. -* `ipv4_netmask` The IPv4 subnet mask, in bits (_e.g._ `24` for 255.255.255.0). +- `ipv4_netmask` The IPv4 subnet mask, in bits (_e.g._ `24` for 255.255.255.0). -* `ipv6_address` - (Optional) The IPv6 address assigned to the network adapter. If blank or not included, auto-configuration is used. +- `ipv6_address` - (Optional) The IPv6 address assigned to the network adapter. If blank or not included, auto-configuration is used. -* `ipv6_netmask` - (Optional) The IPv6 subnet mask, in bits (_e.g._ `32`). +- `ipv6_netmask` - (Optional) The IPv6 subnet mask, in bits (_e.g._ `32`). ~> **NOTE:** The minimum setting for IPv4 in a customization specification is DHCP. If you are setting up an IPv6-exclusive network without DHCP, you may need to set [`wait_for_guest_net_timeout`](#wait_for_guest_net_timeout) to a high enough value to cover the DHCP timeout of your virtual machine, or disable by supplying a zero or negative value. Disabling `wait_for_guest_net_timeout` may result in IP addresses not being reported to any provisioners you may have configured on the resource. @@ -1181,17 +1198,17 @@ The settings must match the IP address and netmask of at least one `network_inte The options are: -* `ipv4_gateway` - (Optional) The IPv4 default gateway when using `network_interface` customization on the virtual machine. +- `ipv4_gateway` - (Optional) The IPv4 default gateway when using `network_interface` customization on the virtual machine. -* `ipv6_gateway` - (Optional) The IPv6 default gateway when using `network_interface` customization on the virtual machine. +- `ipv6_gateway` - (Optional) The IPv6 default gateway when using `network_interface` customization on the virtual machine. #### Global DNS Settings The following settings configure DNS globally, generally for Linux distribution guest operating systems. For Windows guest operating systems, this is performer per-interface. See the section on [network interface settings](#network-interface-settings) for more information. -* `dns_server_list` - The list of DNS servers to configure on the virtual machine. +- `dns_server_list` - The list of DNS servers to configure on the virtual machine. -* `dns_suffix_list` - A list of DNS search domains to add to the DNS configuration on the virtual machine. +- `dns_suffix_list` - A list of DNS search domains to add to the DNS configuration on the virtual machine. #### Linux Customization Options @@ -1217,18 +1234,18 @@ resource "vsphere_virtual_machine" "vm" { The options are: -* `host_name` - (Required) The host name for this machine. This, along with `domain`, make up the FQDN of the virtual machine. +- `host_name` - (Required) The host name for this machine. This, along with `domain`, make up the FQDN of the virtual machine. -* `domain` - (Required) The domain name for this machine. This, along with `host_name`, make up the FQDN of the virtual machine. +- `domain` - (Required) The domain name for this machine. This, along with `host_name`, make up the FQDN of the virtual machine. -* `hw_clock_utc` - (Optional) Tells the operating system that the hardware clock is set to UTC. Default: `true`. +- `hw_clock_utc` - (Optional) Tells the operating system that the hardware clock is set to UTC. Default: `true`. -* `script_text` - (Optional) The customization script for the virtual machine that will be applied before and / or after guest customization. For more information on enabling and using a customization script, please refer to [VMware KB 74880][vmware-kb-74880]. The [Heredoc style][tf-heredoc-strings] of string literal is recommended. +- `script_text` - (Optional) The customization script for the virtual machine that will be applied before and / or after guest customization. For more information on enabling and using a customization script, please refer to [VMware KB 74880][vmware-kb-74880]. The [Heredoc style][tf-heredoc-strings] of string literal is recommended. [vmware-kb-74880]: https://kb.vmware.com/s/article/74880 [tf-heredoc-strings]: https://www.terraform.io/language/expressions/strings#heredoc-strings -* `time_zone` - (Optional) Sets the time zone. For a list of possible combinations, please refer to [VMware KB 2145518][vmware-kb-2145518]. The default is UTC. +- `time_zone` - (Optional) Sets the time zone. For a list of possible combinations, please refer to [VMware KB 2145518][vmware-kb-2145518]. The default is UTC. [vmware-kb-2145518]: https://kb.vmware.com/s/article/2145518 @@ -1257,35 +1274,35 @@ resource "vsphere_virtual_machine" "vm" { The options are: -* `computer_name` - (Required) The computer name of the virtual machine. +- `computer_name` - (Required) The computer name of the virtual machine. -* `admin_password` - (Optional) The administrator password for the virtual machine. +- `admin_password` - (Optional) The administrator password for the virtual machine. -~> **NOTE:** `admin_password` is a sensitive field and will not be output on-screen, but is stored in state and sent to the virtual machine in plain text. +~> \*_NOTE:_- `admin_password` is a sensitive field and will not be output on-screen, but is stored in state and sent to the virtual machine in plain text. -* `workgroup` - (Optional) The workgroup name for the virtual machine. One of this or `join_domain` must be included. +- `workgroup` - (Optional) The workgroup name for the virtual machine. One of this or `join_domain` must be included. -* `join_domain` - (Optional) The domain name in which to join the virtual machine. One of this or `workgroup` must be included. +- `join_domain` - (Optional) The domain name in which to join the virtual machine. One of this or `workgroup` must be included. -* `domain_admin_user` - (Optional) The user account with administrative privileges to use to join the guest operating system to the domain. Required if setting `join_domain`. +- `domain_admin_user` - (Optional) The user account with administrative privileges to use to join the guest operating system to the domain. Required if setting `join_domain`. -* `domain_admin_password` - (Optional) The password user account with administrative privileges used to join the virtual machine to the domain. Required if setting `join_domain`. +- `domain_admin_password` - (Optional) The password user account with administrative privileges used to join the virtual machine to the domain. Required if setting `join_domain`. -~> **NOTE:** `domain_admin_password` is a sensitive field and will not be output on-screen, but is stored in state and sent to the virtual machine in plain text +~> \*_NOTE:_- `domain_admin_password` is a sensitive field and will not be output on-screen, but is stored in state and sent to the virtual machine in plain text -* `full_name` - (Optional) The full name of the organization owner of the virtual machine. This populates the "user" field in the general Windows system information. Default: `Administrator`. +- `full_name` - (Optional) The full name of the organization owner of the virtual machine. This populates the "user" field in the general Windows system information. Default: `Administrator`. -* `organization_name` - (Optional) The name of the organization for the virtual machine. This option populates the "organization" field in the general Windows system information. Default: `Managed by Terraform`. +- `organization_name` - (Optional) The name of the organization for the virtual machine. This option populates the "organization" field in the general Windows system information. Default: `Managed by Terraform`. -* `product_key` - (Optional) The product key for the virtual machine Windows guest operating system. The default is no key. +- `product_key` - (Optional) The product key for the virtual machine Windows guest operating system. The default is no key. -* `run_once_command_list` - (Optional) A list of commands to run at first user logon, after guest customization. Each run once command is limited by the API to 260 characters. +- `run_once_command_list` - (Optional) A list of commands to run at first user logon, after guest customization. Each run once command is limited by the API to 260 characters. -* `auto_logon` - (Optional) Specifies whether or not the virtual machine automatically logs on as Administrator. Default: `false`. +- `auto_logon` - (Optional) Specifies whether or not the virtual machine automatically logs on as Administrator. Default: `false`. -* `auto_logon_count` - (Optional) Specifies how many times the virtual machine should auto-logon the Administrator account when `auto_logon` is `true`. This option should be set accordingly to ensure that all of your commands that run in `run_once_command_list` can log in to run. Default: `1`. +- `auto_logon_count` - (Optional) Specifies how many times the virtual machine should auto-logon the Administrator account when `auto_logon` is `true`. This option should be set accordingly to ensure that all of your commands that run in `run_once_command_list` can log in to run. Default: `1`. -* `time_zone` - (Optional) The time zone for the virtual machine. For a list of supported codes, please refer to the [MIcrosoft documentation][ms-docs-valid-sysprep-tzs]. The default is `85` (GMT/UTC). +- `time_zone` - (Optional) The time zone for the virtual machine. For a list of supported codes, please refer to the [MIcrosoft documentation][ms-docs-valid-sysprep-tzs]. The default is `85` (GMT/UTC). [ms-docs-valid-sysprep-tzs]: https://msdn.microsoft.com/en-us/library/ms912391(v=winembedded.11).aspx @@ -1320,25 +1337,25 @@ See the [Deploying from OVF example](#deploying-vm-from-an-ovf-ova-template) for The options available in the `ovf_deploy` block are: -* `allow_unverified_ssl_cert` - (Optional) Allow unverified SSL certificates while deploying OVF/OVA from a URL. Defaults `false`. +- `allow_unverified_ssl_cert` - (Optional) Allow unverified SSL certificates while deploying OVF/OVA from a URL. Defaults `false`. -* `enable_hidden_properties` - (Optional) Allow properties with `ovf:userConfigurable=false` to be set. Defaults `false`. +- `enable_hidden_properties` - (Optional) Allow properties with `ovf:userConfigurable=false` to be set. Defaults `false`. -* `local_ovf_path` - (Optional) The absolute path to the OVF/OVA file on the local system. When deploying from an OVF, ensure the necessary files, such as `.vmdk` and `.mf` files are also in the same directory as the `.ovf` file. +- `local_ovf_path` - (Optional) The absolute path to the OVF/OVA file on the local system. When deploying from an OVF, ensure the necessary files, such as `.vmdk` and `.mf` files are also in the same directory as the `.ovf` file. -* `remote_ovf_url` - (Optional) URL to the OVF/OVA file. +- `remote_ovf_url` - (Optional) URL to the OVF/OVA file. ~> **NOTE:** Either `local_ovf_path` or `remote_ovf_url` is required. -* `ip_allocation_policy` - (Optional) The IP allocation policy. +- `ip_allocation_policy` - (Optional) The IP allocation policy. -* `ip_protocol` - (Optional) The IP protocol. +- `ip_protocol` - (Optional) The IP protocol. -* `disk_provisioning` - (Optional) The disk provisioning policy. If set, all the disks included in the OVF/OVA will have the same specified policy. One of `thin`, `flat`, `thick`, or `sameAsSource`. +- `disk_provisioning` - (Optional) The disk provisioning policy. If set, all the disks included in the OVF/OVA will have the same specified policy. One of `thin`, `flat`, `thick`, or `sameAsSource`. -* `deployment_option` - (Optional) The key for the deployment option. If empty, the default option is selected. +- `deployment_option` - (Optional) The key for the deployment option. If empty, the default option is selected. -* `ovf_network_map` - (Optional) The mapping of network identifiers from the OVF descriptor to a network UUID. +- `ovf_network_map` - (Optional) The mapping of network identifiers from the OVF descriptor to a network UUID. ### Using vApp Properties for OVF/OVA Configuration @@ -1431,13 +1448,13 @@ resource "vsphere_virtual_machine" "vm" { When cloning from a template, there are additional requirements in both the resource configuration and source template: -* The virtual machine must not be powered on at the time of cloning. -* All disks on the virtual machine must be SCSI disks. -* You must specify at least the same number of `disk` devices as there are disks that exist in the template. These devices are ordered and lined up by the `unit_number` attribute. Additional disks can be added past this. -* The `size` of a virtual disk must be at least the same size as its counterpart disk in the source template. -* When using `linked_clone`, the `size`, `thin_provisioned`, and `eagerly_scrub` settings for each disk must be an exact match to the individual disk's counterpart in the source template. -* The storage controller count settings should be configured as necessary to cover all of the disks on the template. For best results, only configure this setting for the number of controllers you will need to cover your disk quantity and bandwidth needs, and configure your template accordingly. For most workloads, this setting should be kept at the default of `1` SCSI controller, and all disks in the template should reside on the single, primary controller. -* Some operating systems do not respond well to a change in disk controller type. Ensure that `scsi_type` is set to an exact match of the template's controller set. For maximum compatibility, make sure the SCSI controllers on the source template are all the same type. +- The virtual machine must not be powered on at the time of cloning. +- All disks on the virtual machine must be SCSI disks. +- You must specify at least the same number of `disk` devices as there are disks that exist in the template. These devices are ordered and lined up by the `unit_number` attribute. Additional disks can be added past this. +- The `size` of a virtual disk must be at least the same size as its counterpart disk in the source template. +- When using `linked_clone`, the `size`, `thin_provisioned`, and `eagerly_scrub` settings for each disk must be an exact match to the individual disk's counterpart in the source template. +- The storage controller count settings should be configured as necessary to cover all of the disks on the template. For best results, only configure this setting for the number of controllers you will need to cover your disk quantity and bandwidth needs, and configure your template accordingly. For most workloads, this setting should be kept at the default of `1` SCSI controller, and all disks in the template should reside on the single, primary controller. +- Some operating systems do not respond well to a change in disk controller type. Ensure that `scsi_type` is set to an exact match of the template's controller set. For maximum compatibility, make sure the SCSI controllers on the source template are all the same type. You can use the [`vsphere_virtual_machine`][tf-vsphere-virtual-machine-ds] data source, which provides disk attributes, network interface types, SCSI bus types, and the guest ID of the source template, to return this information. See the section on [cloning and customization](#cloning-and-customization) for more information. @@ -1455,9 +1472,9 @@ The same rules apply for migration as they do for virtual machine creation - any Storage migration can be done on two levels: -* Global datastore migration can be handled by changing the global `datastore_id` attribute. This triggers a storage migration for all disks that do not have an explicit `datastore_id` specified. -* When using Storage DRS through the `datastore_cluster_id` attribute, the entire virtual machine can be migrated from one datastore cluster to another by changing the value of this setting. In addition, when `datastore_cluster_id` is in use, any disks that drift to datastores outside of the datastore cluster via such actions as manual modification will be migrated back to the datastore cluster on the next apply. -* An individual `disk` device can be migrated by manually specifying the `datastore_id` in its configuration block. This also pins it to the specific datastore that is specified - if at a later time the virtual machine and any unpinned disks migrate to another host, the disk will stay on the specified datastore. +- Global datastore migration can be handled by changing the global `datastore_id` attribute. This triggers a storage migration for all disks that do not have an explicit `datastore_id` specified. +- When using Storage DRS through the `datastore_cluster_id` attribute, the entire virtual machine can be migrated from one datastore cluster to another by changing the value of this setting. In addition, when `datastore_cluster_id` is in use, any disks that drift to datastores outside of the datastore cluster via such actions as manual modification will be migrated back to the datastore cluster on the next apply. +- An individual `disk` device can be migrated by manually specifying the `datastore_id` in its configuration block. This also pins it to the specific datastore that is specified - if at a later time the virtual machine and any unpinned disks migrate to another host, the disk will stay on the specified datastore. An example of datastore pinning is below. As long as the datastore in the `pinned_datastore` data source does not change, any change to the standard `vm_datastore` data source will not affect the data disk - the disk will stay where it is. @@ -1491,68 +1508,68 @@ You cannot migrate external disks added with the `attach` parameter. Typically, The virtual machine will be rebooted if any of the following parameters are changed: -* `alternate_guest_name` -* `cpu_hot_add_enabled` -* `cpu_hot_remove_enabled` -* `cpu_performance_counters_enabled` -* `disk.controller_type` -* `disk.unit_number` -* `disk.disk_mode` -* `disk.write_through` -* `disk.disk_sharing` -* `efi_secure_boot_enabled` -* `ept_rvi_mode` -* `enable_disk_uuid` -* `enable_logging` -* `extra_config` -* `firmware` -* `guest_id` -* `hardware_version` -* `hv_mode` -* `memory` - When reducing the memory size, or when increasing the memory size and `memory_hot_add_enabled` is set to `false` -* `memory_hot_add_enabled` -* `nested_hv_enabled` -* `network_interface` - When deleting a network interface and VMware Tools is not running. -* `network_interface.adapter_type` - When VMware Tools is not running. -* `num_cores_per_socket` -* `pci_device_id` -* `run_tools_scripts_after_power_on` -* `run_tools_scripts_after_resume` -* `run_tools_scripts_before_guest_standby` -* `run_tools_scripts_before_guest_shutdown` -* `run_tools_scripts_before_guest_reboot` -* `swap_placement_policy` -* `tools_upgrade_policy` -* `vbs_enabled` -* `vvtd_enabled` +- `alternate_guest_name` +- `cpu_hot_add_enabled` +- `cpu_hot_remove_enabled` +- `cpu_performance_counters_enabled` +- `disk.controller_type` +- `disk.unit_number` +- `disk.disk_mode` +- `disk.write_through` +- `disk.disk_sharing` +- `efi_secure_boot_enabled` +- `ept_rvi_mode` +- `enable_disk_uuid` +- `enable_logging` +- `extra_config` +- `firmware` +- `guest_id` +- `hardware_version` +- `hv_mode` +- `memory` - When reducing the memory size, or when increasing the memory size and `memory_hot_add_enabled` is set to `false` +- `memory_hot_add_enabled` +- `nested_hv_enabled` +- `network_interface` - When deleting a network interface and VMware Tools is not running. +- `network_interface.adapter_type` - When VMware Tools is not running. +- `num_cores_per_socket` +- `pci_device_id` +- `run_tools_scripts_after_power_on` +- `run_tools_scripts_after_resume` +- `run_tools_scripts_before_guest_standby` +- `run_tools_scripts_before_guest_shutdown` +- `run_tools_scripts_before_guest_reboot` +- `swap_placement_policy` +- `tools_upgrade_policy` +- `vbs_enabled` +- `vvtd_enabled` ## Attribute Reference The following attributes are exported on the base level of this resource: -* `id` - The UUID of the virtual machine. +- `id` - The UUID of the virtual machine. -* `reboot_required` - Value internal to Terraform used to determine if a configuration set change requires a reboot. This value is most useful during an update process and gets reset on refresh. +- `reboot_required` - Value internal to Terraform used to determine if a configuration set change requires a reboot. This value is most useful during an update process and gets reset on refresh. -* `vmware_tools_status` - The state of VMware Tools in the guest. This will determine the proper course of action for some device operations. +- `vmware_tools_status` - The state of VMware Tools in the guest. This will determine the proper course of action for some device operations. -* `vmx_path` - The path of the virtual machine configuration file on the datastore in which the virtual machine is placed. +- `vmx_path` - The path of the virtual machine configuration file on the datastore in which the virtual machine is placed. -* `imported` - Indicates if the virtual machine resource has been imported, or if the state has been migrated from a previous version of the resource. It influences the behavior of the first post-import apply operation. See the section on [importing](#importing) below. +- `imported` - Indicates if the virtual machine resource has been imported, or if the state has been migrated from a previous version of the resource. It influences the behavior of the first post-import apply operation. See the section on [importing](#importing) below. -* `change_version` - A unique identifier for a given version of the last configuration was applied. +- `change_version` - A unique identifier for a given version of the last configuration was applied. -* `uuid` - The UUID of the virtual machine. Also exposed as the `id` of the resource. +- `uuid` - The UUID of the virtual machine. Also exposed as the `id` of the resource. -* `default_ip_address` - The IP address selected by Terraform to be used with any [provisioners][tf-docs-provisioners] configured on this resource. When possible, this is the first IPv4 address that is reachable through the default gateway configured on the machine, then the first reachable IPv6 address, and then the first general discovered address if neither exists. If VMware Tools is not running on the virtual machine, or if the virtual machine is powered off, this value will be blank. +- `default_ip_address` - The IP address selected by Terraform to be used with any [provisioners][tf-docs-provisioners] configured on this resource. When possible, this is the first IPv4 address that is reachable through the default gateway configured on the machine, then the first reachable IPv6 address, and then the first general discovered address if neither exists. If VMware Tools is not running on the virtual machine, or if the virtual machine is powered off, this value will be blank. -* `guest_ip_addresses` - The current list of IP addresses on this machine, including the value of `default_ip_address`. If VMware Tools is not running on the virtual machine, or if the virtul machine is powered off, this list will be empty. +- `guest_ip_addresses` - The current list of IP addresses on this machine, including the value of `default_ip_address`. If VMware Tools is not running on the virtual machine, or if the virtul machine is powered off, this list will be empty. -* `moid`: The [managed object reference ID][docs-about-morefs] of the created virtual machine. +- `moid`: The [managed object reference ID][docs-about-morefs] of the created virtual machine. -* `vapp_transport` - Computed value which is only valid for cloned virtual machines. A list of vApp transport methods supported by the source virtual machine or template. +- `vapp_transport` - Computed value which is only valid for cloned virtual machines. A list of vApp transport methods supported by the source virtual machine or template. -* `power_state` - A computed value for the current power state of the virtual machine. One of `on`, `off`, or `suspended`. +- `power_state` - A computed value for the current power state of the virtual machine. One of `on`, `off`, or `suspended`. [docs-about-morefs]: https://registry.terraform.io/providers/hashicorp/vsphere/latest/docs#use-of-managed-object-references-by-the-vsphere-provider @@ -1577,19 +1594,19 @@ Many of the requirements for [cloning](#additional-requirements-and-notes-for-cl The following requirements apply to import: -* The disks must have a [`label`](#label) argument assigned in a convention matching `diskN`, starting with disk number 0, based on each virtual disk order on the SCSI bus. As an example, a disk on SCSI controller `0` with a unit number of `0` would be labeled as `disk0`, a disk on the same controller with a unit number of `1` would be `disk1`, but the next disk, which is on SCSI controller `1` with a unit number of `0`, still becomes `disk2`. +- The disks must have a [`label`](#label) argument assigned in a convention matching `diskN`, starting with disk number 0, based on each virtual disk order on the SCSI bus. As an example, a disk on SCSI controller `0` with a unit number of `0` would be labeled as `disk0`, a disk on the same controller with a unit number of `1` would be `disk1`, but the next disk, which is on SCSI controller `1` with a unit number of `0`, still becomes `disk2`. -* Disks are always imported with [`keep_on_remove`](#keep_on_remove) enabled until the first `terraform apply` run which will remove the setting for known disks. This process safeguards against naming or accounting mistakes in the disk configuration. +- Disks are always imported with [`keep_on_remove`](#keep_on_remove) enabled until the first `terraform apply` run which will remove the setting for known disks. This process safeguards against naming or accounting mistakes in the disk configuration. -* The storage controller count for the resource is set to the number of contiguous storage controllers found, starting with the controller at SCSI bus number `0`. If no storage controllers are discovered, the virtual machine is not eligible for import. For maximum compatibility, ensure that the virtual machine has the exact number of storage controllers needed and set the storage controller count accordingly. +- The storage controller count for the resource is set to the number of contiguous storage controllers found, starting with the controller at SCSI bus number `0`. If no storage controllers are discovered, the virtual machine is not eligible for import. For maximum compatibility, ensure that the virtual machine has the exact number of storage controllers needed and set the storage controller count accordingly. After importing, you should run `terraform plan`. Unless you have changed anything else in the configuration that would cause other attributes to change. The only difference should be configuration-only changes, which are typically comprised of: -* The [`imported`](#imported) flag will transition from `true` to `false`. +- The [`imported`](#imported) flag will transition from `true` to `false`. -* The [`keep_on_remove`](#keep_on_remove) of known disks will transition from `true` to `false`. +- The [`keep_on_remove`](#keep_on_remove) of known disks will transition from `true` to `false`. -* Configuration supplied in the [`clone`](#clone) block, if present, will be persisted to state. This initial persistence operation does not perform any cloning or customization actions, nor does it force a new resource. After the first apply operation, further changes to `clone` will force the creation of a new resource. +- Configuration supplied in the [`clone`](#clone) block, if present, will be persisted to state. This initial persistence operation does not perform any cloning or customization actions, nor does it force a new resource. After the first apply operation, further changes to `clone` will force the creation of a new resource. ~> **NOTE:** Do not make any configuration changes to `clone` after importing or upgrading from a legacy version of the provider before doing an initial `terraform apply` as these changes will not correctly force a new resource and your changes will have persisted to state, preventing further plans from correctly triggering a diff.