packer-cn/website/pages/docs/builders/vmware/vsphere-clone.mdx

---
modeline: |
  vim: set ft=pandoc:
description: >
  This VMware Packer builder uses the vSphere API to clone an existing vSphere
  template and create a new virtual machine remotely.
layout: docs
page_title: VSphere Clone - Builders
sidebar_title: VSphere Clone
---

# VMWare Vsphere Clone Builder

Type: `vsphere-clone`

This builder clones VMs from existing templates.

- VMware Player is not required.
- It uses the official vCenter API, and does not require ESXi host [modification](https://www.packer.io/docs/builders/vmware-iso.html#building-on-a-remote-vsphere-hypervisor)
- This builder is supported for vSphere version 6.5 and greater. Builds on lower
versions may work, but some configuration options may throw errors because they
do not exist in the older versions of the vSphere API.

## Examples

See complete Ubuntu, Windows, and macOS templates in the [examples folder](https://github.com/hashicorp/packer/tree/master/builder/vsphere/examples/).

## VSphere-Clone Configuration Reference

There are many configuration options available for this builder. In addition to
the items listed here, you will want to look at the general configuration
references for [Hardware](#hardware-configuration),
[Output](#output-configuration),
[Boot](#boot-configuration),
[Run](#run-configuration),
[Shutdown](#shutdown-configuration),
[Communicator](#communicator-configuration),
[Export](#export-configuration),
configuration references, which are
necessary for this build to succeed and can be found further down the page.

@include 'builder/vsphere/clone/Config-not-required.mdx'

### Clone Configuration

@include 'builder/vsphere/clone/CloneConfig-not-required.mdx'

### vApp Options Configuration

@include 'builder/vsphere/clone/vAppConfig-not-required.mdx'

Example of usage:

<Tabs>
<Tab heading="JSON">

```json
 "vapp": {
     "properties": {
         "hostname": "{{ user `hostname`}}",
         "user-data": "{{ env `USERDATA`}}"
     }
 }
```

A `user-data` field requires the content of a yaml file to be encoded with base64. This
can be done via environment variable:
`export USERDATA=$(gzip -c9 <userdata.yaml | { base64 -w0 2>/dev/null || base64; })`

</Tab>
<Tab heading="HCL2">

```hcl
   vapp {
     properties = {
        hostname  = var.hostname
        user-data = base64encode(var.user_data)
     }
   }
```

</Tab>
</Tabs>

### Extra Configuration Parameters

@include 'builder/vsphere/common/ConfigParamsConfig-not-required.mdx'

### Customization

@include '/builder/vsphere/clone/CustomizeConfig.mdx'

@include 'builder/vsphere/clone/CustomizeConfig-not-required.mdx'

#### Network Interface Settings

@include 'builder/vsphere/clone/NetworkInterface-not-required.mdx'

#### Global Routing Settings

@include 'builder/vsphere/clone/GlobalRoutingSettings.mdx'

@include 'builder/vsphere/clone/GlobalRoutingSettings-not-required.mdx'

#### Global DNS Settings

@include 'builder/vsphere/clone/GlobalDnsSettings.mdx'

@include 'builder/vsphere/clone/GlobalDnsSettings-not-required.mdx'

#### Linux Customization Settings

@include 'builder/vsphere/clone/LinuxOptions-not-required.mdx'

#### Customization Example

<Tabs>
<Tab heading="JSON">

```json
 "customize": {
          "linux_options": {
            "host_name": "packer-test",
            "domain": "test.internal"
          },
          "network_interface": {
            "ipv4_address": "10.0.0.10",
            "ipv4_netmask": "24"
          }
 }
```

</Tab>
<Tab heading="HCL2">

```hcl
   customize {
         linux_options {
           host_name = "packer-test"
           domain = "test.internal"
         }

         network_interface {
           ipv4_address = "10.0.0.10"
           ipv4_netmask = "24"
         }
   }
```

</Tab>
</Tabs>

### Boot configuration

@include 'common/bootcommand/BootConfig.mdx'

#### Optional:

@include 'common/bootcommand/BootConfig-not-required.mdx'

@include 'builder/vsphere/common/BootConfig-not-required.mdx'

### Http directory configuration

@include 'common/commonsteps/HTTPConfig.mdx'

#### Optional:

@include 'common/commonsteps/HTTPConfig-not-required.mdx'

### Floppy configuration

@include 'builder/vsphere/common/FloppyConfig-not-required.mdx'

### Connection Configuration

@include 'builder/vsphere/common/ConnectConfig-not-required.mdx'

### Hardware Configuration

@include 'builder/vsphere/common/HardwareConfig-not-required.mdx'

### Location Configuration

@include 'builder/vsphere/common/LocationConfig-not-required.mdx'

### Run Configuration

@include 'builder/vsphere/common/RunConfig-not-required.mdx'

### Shutdown Configuration

@include 'builder/vsphere/common/ShutdownConfig-not-required.mdx'

### Wait Configuration

@include 'builder/vsphere/common/WaitIpConfig-not-required.mdx'

### CDRom Configuration

@include 'common/commonsteps/CDConfig.mdx'

#### Optional:

@include 'common/commonsteps/CDConfig-not-required.mdx'

@include 'builder/vsphere/common/CDRomConfig-not-required.mdx'

@include 'builder/vsphere/common/RemoveCDRomConfig-not-required.mdx'

### Communicator configuration

#### Optional common fields:

@include 'helper/communicator/Config-not-required.mdx'

#### Optional SSH fields:

@include 'helper/communicator/SSH-not-required.mdx'

@include 'helper/communicator/SSH-Temporary-Key-Pair-not-required.mdx'

@include 'helper/communicator/SSH-Key-Pair-Name-not-required.mdx'

@include 'helper/communicator/SSH-Private-Key-File-not-required.mdx'

@include 'helper/communicator/SSH-Agent-Auth-not-required.mdx'

-> **NOTE:** Packer uses vApp Options to inject ssh public keys to the Virtual Machine.
The [temporary_key_pair_name](/docs/builders/vmware/vsphere-clone#temporary_key_pair_name) will only work
if the template being cloned contains the vApp property `public-keys`.
If using [ssh_private_key_file](/docs/builders/vmware/vsphere-clone#ssh_private_key_file), provide
the public key via [configuration_parameters](/docs/builders/vmware/vsphere-clone#configuration_parameters) or
[vApp Options Configuration](/docs/builders/vmware/vsphere-clone#vapp-options-configuration) whenever the `guestinto.userdata`
is available. See [VMware Guestinfo datasource](https://github.com/vmware/cloud-init-vmware-guestinfo) for more information
about the key.

#### Optional WinRM fields:

@include 'helper/communicator/WinRM-not-required.mdx'

### Export Configuration

@include 'builder/vsphere/common/ExportConfig.mdx'

#### Optional:

@include 'builder/vsphere/common/ExportConfig-not-required.mdx'

#### Output Configuration:

@include 'builder/vsphere/common/OutputConfig-not-required.mdx'

### Content Library Import Configuration

@include 'builder/vsphere/common/ContentLibraryDestinationConfig.mdx'

@include 'builder/vsphere/common/ContentLibraryDestinationConfig-not-required.mdx'

Minimal example of usage:

<Tabs>
<Tab heading="JSON">

```json
	"content_library_destination" : {
	    "library": "Packer Library Test"
	}
```

</Tab>
<Tab heading="HCL2">

```hcl
	content_library_destination {
			library = "Packer Library Test"
	}
```

</Tab>
</Tabs>

## Working With Clusters And Hosts

#### Standalone Hosts

Only use the `host` option. Optionally specify a `resource_pool`:

<Tabs>
<Tab heading="JSON">

```json
"host": "esxi-1.vsphere65.test",
"resource_pool": "pool1",
```

</Tab>
<Tab heading="HCL2">

```hcl
host = "esxi-1.vsphere65.test"
resource_pool = "pool1"
```

</Tab>
</Tabs>

#### Clusters Without DRS

Use the `cluster` and `host`parameters:

<Tabs>
<Tab heading="JSON">

```json
"cluster": "cluster1",
"host": "esxi-2.vsphere65.test",
```

</Tab>
<Tab heading="HCL2">

```hcl
cluster = "cluster1"
host = "esxi-2.vsphere65.test"
```

</Tab>
</Tabs>

#### Clusters With DRS

Only use the `cluster` option. Optionally specify a `resource_pool`:

<Tabs>
<Tab heading="JSON">

```json
"cluster": "cluster2",
"resource_pool": "pool1",
```

</Tab>
<Tab heading="HCL2">

```hcl
cluster = "cluster2"
resource_pool = "pool1"
```

</Tab>
</Tabs>

## Required vSphere Permissions

- VM folder (this object and children):
  ```text
  Virtual machine -> Inventory
  Virtual machine -> Configuration
  Virtual machine -> Interaction
  Virtual machine -> Snapshot management
  Virtual machine -> Provisioning
  ```
  Individual privileges are listed in https://github.com/jetbrains-infra/packer-builder-vsphere/issues/97#issuecomment-436063235.
- Resource pool, host, or cluster (this object):
  ```text
  Resource -> Assign virtual machine to resource pool
  ```
- Host in clusters without DRS (this object):
  ```text
  Read-only
  ```
- Datastore (this object):
  ```text
  Datastore -> Allocate space
  Datastore -> Browse datastore
  Datastore -> Low level file operations
  ```
- Network (this object):
  ```text
  Network -> Assign network
  ```
- Distributed switch (this object):
  ```text
  Read-only
  ```

For floppy image upload:

- Datacenter (this object):
  ```text
  Datastore -> Low level file operations
  ```
- Host (this object):
  ```text
  Host -> Configuration -> System Management
  ```