HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Packer
Packer Home

You are viewing documentation for version v1.5.x. View latest version.

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

Examples

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

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 ISO, HTTP, 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) - Export

Clone Configuration

  • template (string) - Name of source VM. Path is optional.
  • disk_size (int64) - The size of the disk in MB.
  • linked_clone (bool) - Create VM as a linked clone from latest snapshot. Defaults to false.
  • network (string) - Set network VM will be connected to.
  • notes (string) - VM notes.

Extra Configuration Parameters

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.

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.

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.

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