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