# salt.cloud.clouds.vmware

## VMware Cloud Module

New in version 2015.5.4.

The VMware cloud module allows you to manage VMware ESX, ESXi, and vCenter.

See Getting started with VMware to get started.

codeauthor:

  Nitin Madhok <nmadhok@g.clemson.edu>

## Dependencies

- pyVmomi Python Module

### pyVmomi

PyVmomi can be installed via pip:

    pip install pyVmomi

Note

Version 6.0 of pyVmomi has some problems with SSL error handling on certain versions of Python. If using version 6.0 of pyVmomi, Python 2.6, Python 2.7.9, or newer must be present. This is due to an upstream dependency in pyVmomi 6.0 that is not supported in Python versions 2.7 to 2.7.8. If the version of Python is not in the supported range, you will need to install an earlier version of pyVmomi. See Issue #29537 for more information.

Based on the note above, to install an earlier version of pyVmomi than the version currently listed in PyPi, run the following:

    pip install pyVmomi==5.5.0.2014.1.1

The 5.5.0.2014.1.1 is a known stable version that this original VMware cloud driver was developed against.

Note

Ensure python pyVmomi module is installed by running following one-liner check. The output should be 0.

    python -c "import pyVmomi" ; echo $?

## Configuration

To use this module, set up the vCenter or ESX/ESXi URL, username and password in the cloud configuration at `/etc/salt/cloud.providers` or `/etc/salt/cloud.providers.d/vmware.conf`:

    my-vmware-config:
      driver: vmware
      user: 'DOMAIN\user'
      password: 'verybadpass'
      url: '10.20.30.40'

    vcenter01:
      driver: vmware
      user: 'DOMAIN\user'
      password: 'verybadpass'
      url: 'vcenter01.domain.com'
      protocol: 'https'
      port: 443

    vcenter02:
      driver: vmware
      user: 'DOMAIN\user'
      password: 'verybadpass'
      url: 'vcenter02.domain.com'
      protocol: 'http'
      port: 80

    esx01:
      driver: vmware
      user: 'admin'
      password: 'verybadpass'
      url: 'esx01.domain.com'

Note

Optionally, `protocol` and `port` can be specified if the vCenter server is not using the defaults. Default is `protocol: https` and `port: 443`.

Note

Changed in version 2015.8.0.

The `provider` parameter in cloud provider configuration was renamed to `driver`. This change was made to avoid confusion with the `provider` parameter that is used in cloud profile configuration. Cloud provider configuration now uses `driver` to refer to the salt-cloud driver that provides the underlying functionality to connect to a cloud provider, while cloud profile configuration continues to use `provider` to refer to the cloud provider configuration that you define.

To test the connection for `my-vmware-config` specified in the cloud configuration, run `test_vcenter_connection()`

salt.cloud.clouds.vmware.add_host(kwargs=None, call=None)

  Add a host system to the specified cluster or datacenter in this VMware environment

  Note

  To use this function, you need to specify `esxi_host_user` and `esxi_host_password` under your provider configuration set up at `/etc/salt/cloud.providers` or `/etc/salt/cloud.providers.d/vmware.conf`:

      vcenter01:
        driver: vmware
        user: 'DOMAIN\user'
        password: 'verybadpass'
        url: 'vcenter01.domain.com'

        # Required when adding a host system
        esxi_host_user: 'root'
        esxi_host_password: 'myhostpassword'
        # Optional fields that can be specified when adding a host system
        esxi_host_ssl_thumbprint: '12:A3:45:B6:CD:7E:F8:90:A1:BC:23:45:D6:78:9E:FA:01:2B:34:CD'

  The SSL thumbprint of the host system can be optionally specified by setting `esxi_host_ssl_thumbprint` under your provider configuration. To get the SSL thumbprint of the host system, execute the following command from a remote server:

      echo -n | openssl s_client -connect <YOUR-HOSTSYSTEM-DNS/IP>:443 2>/dev/null | openssl x509 -noout -fingerprint -sha1

  CLI Example:

      salt-cloud -f add_host my-vmware-config host="myHostSystemName" cluster="myClusterName"
      salt-cloud -f add_host my-vmware-config host="myHostSystemName" datacenter="myDatacenterName"

salt.cloud.clouds.vmware.avail_images(call=None)

  Return a list of all the templates present in this VMware environment with basic details

  CLI Example:

      salt-cloud --list-images my-vmware-config

salt.cloud.clouds.vmware.avail_locations(call=None)

  Return a list of all the available locations/datacenters in this VMware environment

  CLI Example:

      salt-cloud --list-locations my-vmware-config

salt.cloud.clouds.vmware.avail_sizes(call=None)

  Return a list of all the available sizes in this VMware environment.

  CLI Example:

      salt-cloud --list-sizes my-vmware-config

  Note

  Since sizes are built into templates, this function will return an empty dictionary.

salt.cloud.clouds.vmware.build_clonespec(config_spec, object_ref, reloc_spec, template)

  Returns the clone spec

salt.cloud.clouds.vmware.connect_host(kwargs=None, call=None)

  Connect the specified host system in this VMware environment

  CLI Example:

      salt-cloud -f connect_host my-vmware-config host="myHostSystemName"

salt.cloud.clouds.vmware.convert_to_template(name, kwargs=None, call=None)

  Convert the specified virtual machine to template.

  CLI Example:

      salt-cloud -a convert_to_template vmname

salt.cloud.clouds.vmware.create(vm_)

  To create a single VM in the VMware environment.

  Sample profile and arguments that can be specified in it can be found here.

  CLI Example:

      salt-cloud -p vmware-centos6.5 vmname

salt.cloud.clouds.vmware.create_cluster(kwargs=None, call=None)

  Create a new cluster under the specified datacenter in this VMware environment

  CLI Example:

      salt-cloud -f create_cluster my-vmware-config name="myNewCluster" datacenter="datacenterName"

salt.cloud.clouds.vmware.create_datacenter(kwargs=None, call=None)

  Create a new data center in this VMware environment

  CLI Example:

      salt-cloud -f create_datacenter my-vmware-config name="MyNewDatacenter"

salt.cloud.clouds.vmware.create_datastore_cluster(kwargs=None, call=None)

  Create a new datastore cluster for the specified datacenter in this VMware environment

  CLI Example:

      salt-cloud -f create_datastore_cluster my-vmware-config name="datastoreClusterName" datacenter="datacenterName"

salt.cloud.clouds.vmware.create_folder(kwargs=None, call=None)

  Create the specified folder path in this VMware environment

  Note

  To create a Host and Cluster Folder under a Datacenter, specify `path="/yourDatacenterName/host/yourFolderName"`

  To create a Network Folder under a Datacenter, specify `path="/yourDatacenterName/network/yourFolderName"`

  To create a Storage Folder under a Datacenter, specify `path="/yourDatacenterName/datastore/yourFolderName"`

  To create a VM and Template Folder under a Datacenter, specify `path="/yourDatacenterName/vm/yourFolderName"`

  CLI Example:

      salt-cloud -f create_folder my-vmware-config path="/Local/a/b/c"
      salt-cloud -f create_folder my-vmware-config path="/MyDatacenter/vm/MyVMFolder"
      salt-cloud -f create_folder my-vmware-config path="/MyDatacenter/host/MyHostFolder"
      salt-cloud -f create_folder my-vmware-config path="/MyDatacenter/network/MyNetworkFolder"
      salt-cloud -f create_folder my-vmware-config path="/MyDatacenter/storage/MyStorageFolder"

salt.cloud.clouds.vmware.create_snapshot(name, kwargs=None, call=None)

  Create a snapshot of the specified virtual machine in this VMware environment

  Note

  If the VM is powered on, the internal state of the VM (memory dump) is included in the snapshot by default which will also set the power state of the snapshot to "powered on". You can set `memdump=False` to override this. This field is ignored if the virtual machine is powered off or if the VM does not support snapshots with memory dumps. Default is `memdump=True`

  Note

  If the VM is powered on when the snapshot is taken, VMware Tools can be used to quiesce the file system in the virtual machine by setting `quiesce=True`. This field is ignored if the virtual machine is powered off; if VMware Tools are not available or if `memdump=True`. Default is `quiesce=False`

  CLI Example:

      salt-cloud -a create_snapshot vmname snapshot_name="mySnapshot"
      salt-cloud -a create_snapshot vmname snapshot_name="mySnapshot" [description="My snapshot"] [memdump=False] [quiesce=True]

salt.cloud.clouds.vmware.destroy(name, call=None)

  To destroy a VM from the VMware environment

  CLI Example:

      salt-cloud -d vmname
      salt-cloud --destroy vmname
      salt-cloud -a destroy vmname

salt.cloud.clouds.vmware.disconnect_host(kwargs=None, call=None)

  Disconnect the specified host system in this VMware environment

  CLI Example:

      salt-cloud -f disconnect_host my-vmware-config host="myHostSystemName"

salt.cloud.clouds.vmware.enter_maintenance_mode(kwargs=None, call=None)

  To put the specified host system in maintenance mode in this VMware environment

  CLI Example:

      salt-cloud -f enter_maintenance_mode my-vmware-config host="myHostSystemName"

salt.cloud.clouds.vmware.exit_maintenance_mode(kwargs=None, call=None)

  To take the specified host system out of maintenance mode in this VMware environment

  CLI Example:

      salt-cloud -f exit_maintenance_mode my-vmware-config host="myHostSystemName"

salt.cloud.clouds.vmware.get_clonespec_for_valid_snapshot(config_spec, object_ref, reloc_spec, template, vm_)

  return clonespec only if values are valid

salt.cloud.clouds.vmware.get_configured_provider()

  Return the first configured instance.

salt.cloud.clouds.vmware.get_dependencies()

  Warn if dependencies aren't met.

salt.cloud.clouds.vmware.get_vcenter_version(kwargs=None, call=None)

  Show the vCenter Server version with build number.

  CLI Example:

      salt-cloud -f get_vcenter_version my-vmware-config

salt.cloud.clouds.vmware.handle_snapshot(config_spec, object_ref, reloc_spec, template, vm_)

  Returns a clone spec for cloning from shapshots :rtype vim.vm.CloneSpec

salt.cloud.clouds.vmware.list_clusters(kwargs=None, call=None)

  List all the clusters for this VMware environment

  CLI Example:

      salt-cloud -f list_clusters my-vmware-config

salt.cloud.clouds.vmware.list_clusters_by_datacenter(kwargs=None, call=None)

  List clusters for each datacenter; or clusters for a specified datacenter in this VMware environment

  To list clusters for each datacenter:

  CLI Example:

      salt-cloud -f list_clusters_by_datacenter my-vmware-config

  To list clusters for a specified datacenter:

  CLI Example:

      salt-cloud -f list_clusters_by_datacenter my-vmware-config datacenter="datacenterName"

salt.cloud.clouds.vmware.list_datacenters(kwargs=None, call=None)

  List all the data centers for this VMware environment

  CLI Example:

      salt-cloud -f list_datacenters my-vmware-config

salt.cloud.clouds.vmware.list_datastore_clusters(kwargs=None, call=None)

  List all the datastore clusters for this VMware environment

  CLI Example:

      salt-cloud -f list_datastore_clusters my-vmware-config

salt.cloud.clouds.vmware.list_datastores(kwargs=None, call=None)

  List all the datastores for this VMware environment

  CLI Example:

      salt-cloud -f list_datastores my-vmware-config

salt.cloud.clouds.vmware.list_dvs(kwargs=None, call=None)

  List all the distributed virtual switches for this VMware environment

  CLI Example:

      salt-cloud -f list_dvs my-vmware-config

salt.cloud.clouds.vmware.list_folders(kwargs=None, call=None)

  List all the folders for this VMware environment

  CLI Example:

      salt-cloud -f list_folders my-vmware-config

salt.cloud.clouds.vmware.list_hbas(kwargs=None, call=None)

  List all HBAs for each host system; or all HBAs for a specified host system; or HBAs of specified type for each host system; or HBAs of specified type for a specified host system in this VMware environment

  Note

  You can specify type as either `parallel`, `iscsi`, `block` or `fibre`.

  To list all HBAs for each host system:

  CLI Example:

      salt-cloud -f list_hbas my-vmware-config

  To list all HBAs for a specified host system:

  CLI Example:

      salt-cloud -f list_hbas my-vmware-config host="hostSystemName"

  To list HBAs of specified type for each host system:

  CLI Example:

      salt-cloud -f list_hbas my-vmware-config type="HBAType"

  To list HBAs of specified type for a specified host system:

  CLI Example:

      salt-cloud -f list_hbas my-vmware-config host="hostSystemName" type="HBAtype"

salt.cloud.clouds.vmware.list_hosts(kwargs=None, call=None)

  List all the hosts for this VMware environment

  CLI Example:

      salt-cloud -f list_hosts my-vmware-config

salt.cloud.clouds.vmware.list_hosts_by_cluster(kwargs=None, call=None)

  List hosts for each cluster; or hosts for a specified cluster in this VMware environment

  To list hosts for each cluster:

  CLI Example:

      salt-cloud -f list_hosts_by_cluster my-vmware-config

  To list hosts for a specified cluster:

  CLI Example:

      salt-cloud -f list_hosts_by_cluster my-vmware-config cluster="clusterName"

salt.cloud.clouds.vmware.list_hosts_by_datacenter(kwargs=None, call=None)

  List hosts for each datacenter; or hosts for a specified datacenter in this VMware environment

  To list hosts for each datacenter:

  CLI Example:

      salt-cloud -f list_hosts_by_datacenter my-vmware-config

  To list hosts for a specified datacenter:

  CLI Example:

      salt-cloud -f list_hosts_by_datacenter my-vmware-config datacenter="datacenterName"

salt.cloud.clouds.vmware.list_networks(kwargs=None, call=None)

  List all the standard networks for this VMware environment

  CLI Example:

      salt-cloud -f list_networks my-vmware-config

salt.cloud.clouds.vmware.list_nodes(kwargs=None, call=None)

  Return a list of all VMs and templates that are on the specified provider, with basic fields

  CLI Example:

      salt-cloud -f list_nodes my-vmware-config

  To return a list of all VMs and templates present on ALL configured providers, with basic fields:

  CLI Example:

      salt-cloud -Q

salt.cloud.clouds.vmware.list_nodes_full(kwargs=None, call=None)

  Return a list of all VMs and templates that are on the specified provider, with full details

  CLI Example:

      salt-cloud -f list_nodes_full my-vmware-config

  To return a list of all VMs and templates present on ALL configured providers, with full details:

  CLI Example:

      salt-cloud -F

salt.cloud.clouds.vmware.list_nodes_min(kwargs=None, call=None)

  Return a list of all VMs and templates that are on the specified provider, with no details

  CLI Example:

      salt-cloud -f list_nodes_min my-vmware-config

salt.cloud.clouds.vmware.list_nodes_select(call=None)

  Return a list of all VMs and templates that are on the specified provider, with fields specified under `query.selection` in `/etc/salt/cloud`

  CLI Example:

      salt-cloud -f list_nodes_select my-vmware-config

  To return a list of all VMs and templates present on ALL configured providers, with fields specified under `query.selection` in `/etc/salt/cloud`:

  CLI Example:

      salt-cloud -S

salt.cloud.clouds.vmware.list_portgroups(kwargs=None, call=None)

  List all the distributed virtual portgroups for this VMware environment

  CLI Example:

      salt-cloud -f list_portgroups my-vmware-config

salt.cloud.clouds.vmware.list_resourcepools(kwargs=None, call=None)

  List all the resource pools for this VMware environment

  CLI Example:

      salt-cloud -f list_resourcepools my-vmware-config

salt.cloud.clouds.vmware.list_snapshots(kwargs=None, call=None)

  List snapshots either for all VMs and templates or for a specific VM/template in this VMware environment

  To list snapshots for all VMs and templates:

  CLI Example:

      salt-cloud -f list_snapshots my-vmware-config

  To list snapshots for a specific VM/template:

  CLI Example:

      salt-cloud -f list_snapshots my-vmware-config name="vmname"

salt.cloud.clouds.vmware.list_templates(kwargs=None, call=None)

  List all the templates present in this VMware environment

  CLI Example:

      salt-cloud -f list_templates my-vmware-config

salt.cloud.clouds.vmware.list_vapps(kwargs=None, call=None)

  List all the vApps for this VMware environment

  CLI Example:

      salt-cloud -f list_vapps my-vmware-config

salt.cloud.clouds.vmware.reboot_host(kwargs=None, call=None)

  Reboot the specified host system in this VMware environment

  Note

  If the host system is not in maintenance mode, it will not be rebooted. If you want to reboot the host system regardless of whether it is in maintenance mode, set `force=True`. Default is `force=False`.

  CLI Example:

      salt-cloud -f reboot_host my-vmware-config host="myHostSystemName" [force=True]

salt.cloud.clouds.vmware.remove_all_snapshots(name, kwargs=None, call=None)

  Remove all the snapshots present for the specified virtual machine.

  Note

  All the snapshots higher up in the hierarchy of the current snapshot tree are consolidated and their virtual disks are merged. To override this behavior and only remove all snapshots, set `merge_snapshots=False`. Default is `merge_snapshots=True`

  CLI Example:

      salt-cloud -a remove_all_snapshots vmname [merge_snapshots=False]

salt.cloud.clouds.vmware.remove_host(kwargs=None, call=None)

  Remove the specified host system from this VMware environment

  CLI Example:

      salt-cloud -f remove_host my-vmware-config host="myHostSystemName"

salt.cloud.clouds.vmware.remove_snapshot(name, kwargs=None, call=None)

  Remove a snapshot of the specified virtual machine in this VMware environment

  CLI Example:

      salt-cloud -a remove_snapshot vmname snapshot_name="mySnapshot"
      salt-cloud -a remove_snapshot vmname snapshot_name="mySnapshot" [remove_children="True"]

salt.cloud.clouds.vmware.rescan_hba(kwargs=None, call=None)

  To rescan a specified HBA or all the HBAs on the Host System

  CLI Example:

      salt-cloud -f rescan_hba my-vmware-config host="hostSystemName"
      salt-cloud -f rescan_hba my-vmware-config hba="hbaDeviceName" host="hostSystemName"

salt.cloud.clouds.vmware.reset(name, soft=False, call=None)

  To reset a VM using its name

  Note

  If `soft=True` then issues a command to the guest operating system asking it to perform a reboot. Otherwise hypervisor will terminate VM and start it again. Default is soft=False

  For `soft=True` vmtools should be installed on guest system.

  CLI Example:

      salt-cloud -a reset vmname
      salt-cloud -a reset vmname soft=True

salt.cloud.clouds.vmware.revert_to_snapshot(name, kwargs=None, call=None)

  Revert virtual machine to its current snapshot. If no snapshot exists, the state of the virtual machine remains unchanged

  Note

  The virtual machine will be powered on if the power state of the snapshot when it was created was set to "Powered On". Set `power_off=True` so that the virtual machine stays powered off regardless of the power state of the snapshot when it was created. Default is `power_off=False`.

  If the power state of the snapshot when it was created was "Powered On" and if `power_off=True`, the VM will be put in suspended state after it has been reverted to the snapshot.

  CLI Example:

      salt-cloud -a revert_to_snapshot vmame [power_off=True]
      salt-cloud -a revert_to_snapshot vmame snapshot_name="selectedSnapshot" [power_off=True]

salt.cloud.clouds.vmware.script(vm_)

  Return the script deployment object

salt.cloud.clouds.vmware.show_instance(name, call=None)

  List all available details of the specified VM

  CLI Example:

      salt-cloud -a show_instance vmname

salt.cloud.clouds.vmware.shutdown_host(kwargs=None, call=None)

  Shut down the specified host system in this VMware environment

  Note

  If the host system is not in maintenance mode, it will not be shut down. If you want to shut down the host system regardless of whether it is in maintenance mode, set `force=True`. Default is `force=False`.

  CLI Example:

      salt-cloud -f shutdown_host my-vmware-config host="myHostSystemName" [force=True]

salt.cloud.clouds.vmware.start(name, call=None)

  To start/power on a VM using its name

  CLI Example:

      salt-cloud -a start vmname

salt.cloud.clouds.vmware.stop(name, soft=False, call=None)

  To stop/power off a VM using its name

  Note

  If `soft=True` then issues a command to the guest operating system asking it to perform a clean shutdown of all services. Default is soft=False

  For `soft=True` vmtools should be installed on guest system.

  CLI Example:

      salt-cloud -a stop vmname
      salt-cloud -a stop vmname soft=True

salt.cloud.clouds.vmware.suspend(name, call=None)

  To suspend a VM using its name

  CLI Example:

      salt-cloud -a suspend vmname

salt.cloud.clouds.vmware.terminate(name, call=None)

  To do an immediate power off of a VM using its name. A `SIGKILL` is issued to the vmx process of the VM

  CLI Example:

      salt-cloud -a terminate vmname

salt.cloud.clouds.vmware.test_vcenter_connection(kwargs=None, call=None)

  Test if the connection can be made to the vCenter server using the specified credentials inside `/etc/salt/cloud.providers` or `/etc/salt/cloud.providers.d/vmware.conf`

  CLI Example:

      salt-cloud -f test_vcenter_connection my-vmware-config

salt.cloud.clouds.vmware.upgrade_tools(name, reboot=False, call=None)

  To upgrade VMware Tools on a specified virtual machine.

  Note

  If the virtual machine is running Windows OS, use `reboot=True` to reboot the virtual machine after VMware tools upgrade. Default is `reboot=False`

  CLI Example:

      salt-cloud -a upgrade_tools vmname
      salt-cloud -a upgrade_tools vmname reboot=True

salt.cloud.clouds.vmware.upgrade_tools_all(call=None)

  To upgrade VMware Tools on all virtual machines present in the specified provider

  Note

  If the virtual machine is running Windows OS, this function will attempt to suppress the automatic reboot caused by a VMware Tools upgrade.

  CLI Example:

      salt-cloud -f upgrade_tools_all my-vmware-config