» 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 ISO, 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.

» 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.

  • NestedHV (bool) - Enable nested hardware virtualization for VM. Defaults to false.

» 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. Examples 45s and 10m. Defaults to 5m(5 minutes).

» 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.

» CDRom Configuration

  • 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. Example efi. 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.

  • 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

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

» 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.

» 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 Network Adapter fields:

  • network (string) - Set network VM will be connected to.

  • mac_address (string) - Set network card MAC address

  • passthrough (*bool) - Enable DirectPath I/O passthrough

» 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 Amazon EC2. 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. To use this option with a key pair already configured in the source AMI, leave the ssh_keypair_name blank. To associate an existing key pair in AWS with the source instance, set the ssh_keypair_name field to the name of the key pair. 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_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