---
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)

## 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'

### 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/HTTPConfig.mdx'

#### Optional:

@include 'common/HTTPConfig-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'

### 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'

## Working with Clusters

#### Standalone Hosts

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

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

#### Clusters Without DRS

Use the `cluster` and `host`parameters:

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

#### Clusters With DRS

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

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

## 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
  ```