Packer Builder for VMware vSphere

Type: vsphere-iso

This builder uses the vSphere API, and creates virtual machines remotely. It starts from an ISO file and creates new VMs from scratch.

VMware Player is not required.
It uses the official vCenter API, and does not require ESXi host modification

Examples

See complete Ubuntu, Windows, and macOS templates in the examples folder.

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 HTTP, Floppy, Boot, Driver, Hardware, Output, Run, Shutdown, Communicator, Tools, vmx, Export, configuration references, which are necessary for this build to succeed and can be found further down the page.

create_snapshot (bool) - Create a snapshot when set to true, so the VM can be used as a base for linked clones. Defaults to false.
convert_to_template (bool) - Convert VM to a template. Defaults to false.
export (*common.ExportConfig) - Configuration for exporting VM to an ovf file. The VM will not be exported if no Export Configuration is specified.

Connection Configuration

vcenter_server (string) - vCenter server hostname.
username (string) - vSphere username.
password (string) - vSphere password.
insecure_connection (bool) - Do not validate vCenter server's TLS certificate. Defaults to false.
datacenter (string) - VMware datacenter name. Required if there is more than one datacenter in vCenter.

Hardware Configuration

CPUs (int32) - Number of CPU sockets.
cpu_cores (int32) - Number of CPU cores per socket.
CPU_reservation (int64) - Amount of reserved CPU resources in MHz.
CPU_limit (int64) - Upper limit of available CPU resources in MHz.
CPU_hot_plug (bool) - Enable CPU hot plug setting for virtual machine. Defaults to false.
RAM (int64) - Amount of RAM in MB.
RAM_reservation (int64) - Amount of reserved RAM in MB.
RAM_reserve_all (bool) - Reserve all available RAM. Defaults to false. Cannot be used together with RAM_reservation.
RAM_hot_plug (bool) - Enable RAM hot plug setting for virtual machine. Defaults to false.
video_ram (int64) - Amount of video memory in MB.
vgpu_profile (string) - vGPU profile for accelerated graphics. See NVIDIA GRID vGPU documentation for examples of profile names. Defaults to none.
NestedHV (bool) - Enable nested hardware virtualization for VM. Defaults to false.
firmware (string) - Set the Firmware for virtual machine. Supported values: bios, efi, efi-secure or empty string to keep as in template. Defaults to empty string.

Location Configuration

vm_name (string) - Name of the new VM to create.
folder (string) - VM folder to create the VM in.
cluster (string) - ESXi cluster where target VM is created. See Working with Clusters.
host (string) - ESXi host where target VM is created. A full path must be specified if the host is in a folder. For example folder/host. See the Specifying Clusters and Hosts section above for more details.
resource_pool (string) - VMWare resource pool. Defaults to the root resource pool of the host or cluster.
datastore (string) - VMWare datastore. Required if host is a cluster, or if host has multiple datastores.

Run Configuration

boot_order (string) - Priority of boot devices. Defaults to disk,cdrom

Shutdown Configuration

shutdown_command (string) - Specify a VM guest shutdown command. VMware guest tools are used by default.
shutdown_timeout (duration string | ex: "1h5m2s") - Amount of time to wait for graceful VM shutdown. Defaults to 5m or five minutes.
disable_shutdown (bool) - Packer normally halts the virtual machine after all provisioners have run when no shutdown_command is defined. If this is set to true, Packer will not halt the virtual machine but will assume that you will send the stop signal yourself through the preseed.cfg or your final provisioner. Packer will wait for a default of five minutes until the virtual machine is shutdown. The timeout can be changed using shutdown_timeout option.

Wait Configuration

ip_wait_timeout (duration string | ex: "1h5m2s") - Amount of time to wait for VM's IP, similar to 'ssh_timeout'. Defaults to 30m (30 minutes). See the Goang ParseDuration documentation for full details.
ip_settle_timeout (duration string | ex: "1h5m2s") - Amount of time to wait for VM's IP to settle down, sometimes VM may report incorrect IP initially, then its recommended to set that parameter to apx. 2 minutes. Examples 45s and 10m. Defaults to 5s(5 seconds). See the Golang ParseDuration documentation for full details.

ISO Configuration

By default, Packer will symlink, download or copy image files to the Packer cache into a "hash($iso_url+$iso_checksum).$iso_target_extension" file. Packer uses hashicorp/go-getter in file mode in order to perform a download.

go-getter supports the following protocols:

Local files
Git
Mercurial
HTTP
Amazon S3

Examples: go-getter can guess the checksum type based on iso_checksum len.

{
  "iso_checksum": "946a6077af6f5f95a51f82fdc44051c7aa19f9cfc5f737954845a6050543d7c2",
  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
}

{
  "iso_checksum_type": "file",
  "iso_checksum": "ubuntu.org/..../ubuntu-14.04.1-server-amd64.iso.sum",
  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
}

{
  "iso_checksum_url": "./shasums.txt",
  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
}

{
  "iso_checksum_type": "sha256",
  "iso_checksum_url": "./shasums.txt",
  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
}

Required:

iso_checksum (string) - The checksum for the ISO file or virtual hard drive file. The algorithm to use when computing the checksum can be optionally specified with iso_checksum_type. When iso_checksum_type is not set packer will guess the checksumming type based on iso_checksum length. iso_checksum can be also be a file or an URL, in which case iso_checksum_type must be set to file; the go-getter will download it and use the first hash found.
iso_url (string) - A URL to the ISO containing the installation image or virtual hard drive (VHD or VHDX) file to clone.

Optional:

iso_checksum_url (string) - An URL to a checksum file containing a checksum for the ISO file. At least one of iso_checksum and iso_checksum_url must be defined. iso_checksum_url will be ignored if iso_checksum is non empty.
iso_checksum_type (string) - The algorithm to be used when computing the checksum of the file specified in iso_checksum. Currently, valid values are "", "none", "md5", "sha1", "sha256", "sha512" or "file". Since the validity of ISO and virtual disk files are typically crucial to a successful build, Packer performs a check of any supplied media by default. While setting "none" will cause Packer to skip this check, corruption of large files such as ISOs and virtual hard drives can occur from time to time. As such, skipping this check is not recommended. iso_checksum_type must be set to file when iso_checksum is an url.
iso_urls ([]string) - Multiple URLs for the ISO to download. Packer will try these in order. If anything goes wrong attempting to download or while downloading a single URL, it will move on to the next. All URLs must point to the same file (same checksum). By default this is empty and iso_url is used. Only one of iso_url or iso_urls can be specified.
iso_target_path (string) - The path where the iso should be saved after download. By default will go in the packer cache, with a hash of the original filename and checksum as its name.
iso_target_extension (string) - The extension of the iso file after download. This defaults to iso.

CDRom Configuration

Each iso defined in the CDRom Configuration adds a new drive. If the "iso_url" is defined in addition to the "iso_paths", the "iso_url" is added to the VM first. This keeps the "iso_url" first in the boot order by default allowing the boot iso being defined by the iso_url and the vmware tools iso added from the datastore. Example:

"iso_urls": [
  "win10.iso",
  "http://example.org/isos/win10.iso"
],
"iso_paths": [
    "[] /usr/lib/vmware/isoimages/windows.iso"
],

cdrom_type (string) - Which controller to use. Example: sata. Defaults to ide.
iso_paths ([]string) - List of datastore paths to ISO files that will be mounted to the VM. Example: "[datastore1] ISO/ubuntu.iso".

Create Configuration

vm_version (uint) - Set VM hardware version. Defaults to the most current VM hardware version supported by vCenter. See VMWare article 1003746 for the full list of supported VM hardware versions.
guest_os_type (string) - Set VM OS type. Defaults to otherGuest. See here for a full list of possible values.
firmware (string) - Set the Firmware at machine creation. Supported values: bios, efi or efi-secure. Defaults to bios.
disk_controller_type (string) - Set VM disk controller type. Example pvscsi.
disk_size (int64) - The size of the disk in MB.
disk_thin_provisioned (bool) - Enable VMDK thin provisioning for VM. Defaults to false.
disk_eagerly_scrub (bool) - Enable VMDK eager scrubbing for VM. Defaults to false.
storage ([]DiskConfig) - A collection of one or more disks to be provisioned along with the VM.
network (string) - Set network VM will be connected to.
network_card (string) - Set VM network card type. Example vmxnet3.
network_adapters ([]NIC) - Network adapters
usb_controller (bool) - Create USB controller for virtual machine. Defaults to false.
notes (string) - VM notes.

Network Adapter Configuration

Defines a Network Adapter

Example that creates two network adapters:

  "network_adapters": [
    {
      "network": "VM Network",
      "network_card": "vmxnet3"
    },
    {
      "network": "OtherNetwork",
      "network_card": "vmxnet3"
    }
  ],

network_card (string) - Set VM network card type. Example vmxnet3.

Optional

network (string) - Set network VM will be connected to.
mac_address (string) - Set network card MAC address
passthrough (*bool) - Enable DirectPath I/O passthrough

Storage Configuration

Defines the disk storage for a VM.

Example that will create a 15GB and a 20GB disk on the VM. The second disk will be thin provisioned:

  "storage": [
    {
      "disk_size": 15000,
    },
    {
      "disk_size": 20000,
      "disk_thin_provisioned": true
    }
  ],

disk_size (int64) - The size of the disk in MB.

Optional

disk_thin_provisioned (bool) - Enable VMDK thin provisioning for VM. Defaults to false.
disk_eagerly_scrub (bool) - Enable VMDK eager scrubbing for VM. Defaults to false.

Floppy Configuration

floppy_img_path (string) - Datastore path to a floppy image that will be mounted to the VM. Example: [datastore1] ISO/pvscsi-Windows8.flp.
floppy_files ([]string) - List of local files to be mounted to the VM floppy drive. Can be used to make Debian preseed or RHEL kickstart files available to the VM.
floppy_dirs ([]string) - List of directories to copy files from.

Export Configuration

You may optionally export an ovf from VSphere to the instance running Packer.

Example usage:

...
  "vm_name": "example-ubuntu",
...
  "export": {
    "force": true,
    "output_directory": "./output_vsphere"
  },

The above configuration would create the following files:

./output_vsphere/example-ubuntu-disk-0.vmdk
./output_vsphere/example-ubuntu.mf
./output_vsphere/example-ubuntu.ovf

Optional:

name (string) - name of the ovf. defaults to the name of the VM
force (bool) - overwrite ovf if it exists
images (bool) - include iso and img image files that are attached to the VM
manifest (string) - generate manifest using sha1, sha256, sha512. Defaults to 'sha256'. Use 'none' for no manifest.
options ([]string) - Advanced ovf export options. Options can include:
- mac - MAC address is exported for all ethernet devices
- uuid - UUID is exported for all virtual machines
- extraconfig - all extra configuration options are exported for a virtual machine
- nodevicesubtypes - resource subtypes for CD/DVD drives, floppy drives, and serial and parallel ports are not exported
For example, adding the following export config option would output the mac addresses for all Ethernet devices in the ovf file:
```
...
  "export": {
    "options": ["mac"]
  },
```

Output Configuration:

output_directory (string) - This setting specifies the directory that artifacts from the build, such as the virtual machine files and disks, will be output to. The path to the directory may be relative or absolute. If relative, the path is relative to the working directory packer is executed from. This directory must not exist or, if created, must be empty prior to running the builder. By default this is "output-BUILDNAME" where "BUILDNAME" is the name of the build.

Extra Configuration Parameters

configuration_parameters (map[string]string) - Custom parameters.

Communicator configuration

Optional common fields:

communicator (string) - Packer currently supports three kinds of communicators:
- none - No communicator will be used. If this is set, most provisioners also can't be used.
- ssh - An SSH connection will be established to the machine. This is usually the default.
- winrm - A WinRM connection will be established.
In addition to the above, some builders have custom communicators they can use. For example, the Docker builder has a "docker" communicator that uses docker exec and docker cp to execute scripts and copy files.
pause_before_connecting (duration string | ex: "1h5m2s") - We recommend that you enable SSH or WinRM as the very last step in your guest's bootstrap script, but sometimes you may have a race condition where you need Packer to wait before attempting to connect to your guest.
If you end up in this situation, you can use the template option pause_before_connecting. By default, there is no pause. For example:
```
{
  "communicator": "ssh",
  "ssh_username": "myuser",
  "pause_before_connecting": "10m"
}
```
In this example, Packer will check whether it can connect, as normal. But once a connection attempt is successful, it will disconnect and then wait 10 minutes before connecting to the guest and beginning provisioning.

Optional SSH fields:

ssh_host (string) - The address to SSH to. This usually is automatically configured by the builder.
ssh_port (int) - The port to connect to SSH. This defaults to 22.
ssh_username (string) - The username to connect to SSH with. Required if using SSH.
ssh_password (string) - A plaintext password to use to authenticate with SSH.
ssh_keypair_name (string) - If specified, this is the key that will be used for SSH with the machine. The key must match a key pair name loaded up into the remote. By default, this is blank, and Packer will generate a temporary keypair unless ssh_password is used. ssh_private_key_file or ssh_agent_auth must be specified when ssh_keypair_name is utilized.
temporary_key_pair_name (string) - The name of the temporary key pair to generate. By default, Packer generates a name that looks like packer_<UUID>, where <UUID> is a 36 character unique identifier.
ssh_clear_authorized_keys (bool) - If true, Packer will attempt to remove its temporary key from ~/.ssh/authorized_keys and /root/.ssh/authorized_keys. This is a mostly cosmetic option, since Packer will delete the temporary private key from the host system regardless of whether this is set to true (unless the user has set the -debug flag). Defaults to "false"; currently only works on guests with sed installed.
ssh_private_key_file (string) - Path to a PEM encoded private key file to use to authenticate with SSH. The ~ can be used in path and will be expanded to the home directory of current user.
ssh_pty (bool) - If true, a PTY will be requested for the SSH connection. This defaults to false.
ssh_timeout (duration string | ex: "1h5m2s") - The time to wait for SSH to become available. Packer uses this to determine when the machine has booted so this is usually quite long. Example value: 10m.
ssh_agent_auth (bool) - If true, the local SSH agent will be used to authenticate connections to the source instance. No temporary keypair will be created, and the values of ssh_password and ssh_private_key_file will be ignored. The environment variable SSH_AUTH_SOCK must be set for this option to work properly.
ssh_disable_agent_forwarding (bool) - If true, SSH agent forwarding will be disabled. Defaults to false.
ssh_handshake_attempts (int) - The number of handshakes to attempt with SSH once it can connect. This defaults to 10.
ssh_bastion_host (string) - A bastion host to use for the actual SSH connection.
ssh_bastion_port (int) - The port of the bastion host. Defaults to 22.
ssh_bastion_agent_auth (bool) - If true, the local SSH agent will be used to authenticate with the bastion host. Defaults to false.
ssh_bastion_username (string) - The username to connect to the bastion host.
ssh_bastion_password (string) - The password to use to authenticate with the bastion host.
ssh_bastion_interactive (bool) - If true, the keyboard-interactive used to authenticate with bastion host.
ssh_bastion_private_key_file (string) - Path to a PEM encoded private key file to use to authenticate with the bastion host. The ~ can be used in path and will be expanded to the home directory of current user.
ssh_file_transfer_method (string) - scp or sftp - How to transfer files, Secure copy (default) or SSH File Transfer Protocol.
ssh_proxy_host (string) - A SOCKS proxy host to use for SSH connection
ssh_proxy_port (int) - A port of the SOCKS proxy. Defaults to 1080.
ssh_proxy_username (string) - The optional username to authenticate with the proxy server.
ssh_proxy_password (string) - The optional password to use to authenticate with the proxy server.
ssh_keep_alive_interval (duration string | ex: "1h5m2s") - How often to send "keep alive" messages to the server. Set to a negative value (-1s) to disable. Example value: 10s. Defaults to 5s.
ssh_read_write_timeout (duration string | ex: "1h5m2s") - The amount of time to wait for a remote command to end. This might be useful if, for example, packer hangs on a connection after a reboot. Example: 5m. Disabled by default.
ssh_remote_tunnels ([]string) -
ssh_local_tunnels ([]string) -
ssh_public_key ([]byte) - SSH Internals
ssh_private_key ([]byte) - SSH Private Key

Optional WinRM fields:

winrm_username (string) - The username to use to connect to WinRM.
winrm_password (string) - The password to use to connect to WinRM.
winrm_host (string) - The address for WinRM to connect to.
NOTE: If using an Amazon EBS builder, you can specify the interface WinRM connects to via ssh_interface
winrm_port (int) - The WinRM port to connect to. This defaults to 5985 for plain unencrypted connection and 5986 for SSL when winrm_use_ssl is set to true.
winrm_timeout (duration string | ex: "1h5m2s") - The amount of time to wait for WinRM to become available. This defaults to 30m since setting up a Windows machine generally takes a long time.
winrm_use_ssl (bool) - If true, use HTTPS for WinRM.
winrm_insecure (bool) - If true, do not check server certificate chain and host name.
winrm_use_ntlm (bool) - If true, NTLMv2 authentication (with session security) will be used for WinRM, rather than default (basic authentication), removing the requirement for basic authentication to be enabled within the target guest. Further reading for remote connection authentication can be found here.

Working with Clusters

Standalone Hosts

Only use the host option. Optionally specify a resource_pool:

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

Clusters Without DRS

Use the cluster and hostparameters:

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

Clusters With DRS

Only use the cluster option. Optionally specify a resource_pool:

"cluster": "cluster2",
"resource_pool": "pool1",

Required vSphere Permissions

VM folder (this object and children):

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

Resource -> Assign virtual machine to resource pool

Host in clusters without DRS (this object):
```
Read-only
```

Datastore (this object):

Datastore -> Allocate space
Datastore -> Browse datastore
Datastore -> Low level file operations

Network (this object):
```
Network -> Assign network
```
Distributed switch (this object):
```
Read-only
```

For floppy image upload:

Datacenter (this object):
```
Datastore -> Low level file operations
```

Host (this object):

Host -> Configuration -> System Management