salt.modules.vsphere

Manage VMware vCenter servers and ESXi hosts.

New in version 2015.8.4.

codeauthor::email:`Alexandru Bleotu <alexandru.bleotu@morganstaley.com>`

Dependencies

  • pyVmomi Python Module
  • ESXCLI

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.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 vSphere Execution Module was developed against.

ESXCLI

Currently, about a third of the functions used in the vSphere Execution Module require the ESXCLI package be installed on the machine running the Proxy Minion process.

The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware provides vCLI package installation instructions for vSphere 5.5 and vSphere 6.0.

Once all of the required dependencies are in place and the vCLI package is installed, you can check to see if you can connect to your ESXi host or vCenter server by running the following command:

esxcli -s <host-location> -u <username> -p <password> system syslog config get

If the connection was successful, ESXCLI was successfully installed on your system. You should see output related to the ESXi host's syslog configuration.

Note

Be aware that some functionality in this execution module may depend on the type of license attached to a vCenter Server or ESXi host(s).

For example, certain services are only available to manipulate service state or policies with a VMware vSphere Enterprise or Enterprise Plus license, while others are available with a Standard license. The ntpd service is restricted to an Enterprise Plus license, while ssh is available via the Standard license.

Please see the vSphere Comparison page for more information.

About

This execution module was designed to be able to handle connections both to a vCenter Server, as well as to an ESXi host. It utilizes the pyVmomi Python library and the ESXCLI package to run remote execution functions against either the defined vCenter server or the ESXi host.

Whether or not the function runs against a vCenter Server or an ESXi host depends entirely upon the arguments passed into the function. Each function requires a host location, username, and password. If the credentials provided apply to a vCenter Server, then the function will be run against the vCenter Server. For example, when listing hosts using vCenter credentials, you'll get a list of hosts associated with that vCenter Server:

# salt my-minion vsphere.list_hosts <vcenter-ip> <vcenter-user> <vcenter-password>
my-minion:
- esxi-1.example.com
- esxi-2.example.com

However, some functions should be used against ESXi hosts, not vCenter Servers. Functionality such as getting a host's coredump network configuration should be performed against a host and not a vCenter server. If the authentication information you're using is against a vCenter server and not an ESXi host, you can provide the host name that is associated with the vCenter server in the command, as a list, using the host_names or esxi_host kwarg. For example:

# salt my-minion vsphere.get_coredump_network_config <vcenter-ip> <vcenter-user>         <vcenter-password> esxi_hosts='[esxi-1.example.com, esxi-2.example.com]'
my-minion:
----------
    esxi-1.example.com:
        ----------
        Coredump Config:
            ----------
            enabled:
                False
    esxi-2.example.com:
        ----------
        Coredump Config:
            ----------
            enabled:
                True
            host_vnic:
                vmk0
            ip:
                coredump-location.example.com
            port:
                6500

You can also use these functions against an ESXi host directly by establishing a connection to an ESXi host using the host's location, username, and password. If ESXi connection credentials are used instead of vCenter credentials, the host_names and esxi_hosts arguments are not needed.

# salt my-minion vsphere.get_coredump_network_config esxi-1.example.com root <host-password>
local:
----------
    10.4.28.150:
        ----------
        Coredump Config:
            ----------
            enabled:
                True
            host_vnic:
                vmk0
            ip:
                coredump-location.example.com
            port:
                6500
salt.modules.vsphere.add_capacity_to_diskgroup(*args, **kwargs)

Adds capacity disks to the disk group with the specified cache disk.

cache_disk_id
The canonical name of the cache disk.
capacity_disk_ids
A list containing canonical names of the capacity disks to add.
safety_checks
Specify whether to perform safety check or to skip the checks and try performing the required task. Default value is True.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.add_capacity_to_diskgroup
    cache_disk_id='naa.000000000000001'
    capacity_disk_ids='[naa.000000000000002, naa.000000000000003]'
salt.modules.vsphere.add_license(*args, **kwargs)

Adds a license to the vCenter or ESXi host

key
License key.
description
License description added in as a label.
safety_checks
Specify whether to perform safety check or to skip the checks and try performing the required task
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.add_license key=<license_key> desc='License desc'
salt.modules.vsphere.assign_default_storage_policy_to_datastore(*args, **kwargs)

Assigns a storage policy as the default policy to a datastore.

policy
Name of the policy to assign.
datastore
Name of the datastore to assign. The datastore needs to be visible to the VMware entity the proxy points to.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.assign_storage_policy_to_datastore
    policy='policy name' datastore=ds1
salt.modules.vsphere.assign_license(*args, **kwargs)

Assigns a license to an entity

license_key
Key of the license to assign See _get_entity docstrings for format.
license_name
Display name of license
entity
Dictionary representation of an entity
entity_display_name
Entity name used in logging
safety_checks
Specify whether to perform safety check or to skip the checks and try performing the required task. Default is False.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.assign_license license_key=00000:00000
    license name=test entity={type:cluster,datacenter:dc,cluster:cl}
salt.modules.vsphere.compare_vm_configs(new_config, current_config)

Compares virtual machine current and new configuration, the current is the one which is deployed now, and the new is the target config. Returns the differences between the objects in a dictionary, the keys are the configuration parameter keys and the values are differences objects: either list or recursive difference

new_config:
New config dictionary with every available parameter
current_config
Currently deployed configuration
salt.modules.vsphere.configure_host_cache(*args, **kwargs)

Configures the host cache on the selected host.

enabled
Boolean flag specifying whether the host cache is enabled.
datastore
Name of the datastore that contains the host cache. Must be set if enabled is true.
swap_size_MiB
Swap size in Mibibytes. Needs to be set if enabled is true. Must be smaller thant the datastore size.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.configure_host_cache enabled=False

salt '*' vsphere.configure_host_cache enabled=True datastore=ds1
    swap_size_MiB=1024
salt.modules.vsphere.coredump_network_enable(host, username, password, enabled, protocol=None, port=None, esxi_hosts=None, credstore=None)

Enable or disable ESXi core dump collection. Returns True if coredump is enabled and returns False if core dump is not enabled. If there was an error, the error will be the value printed in the Error key dictionary for the given host.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
enabled
Python True or False to enable or disable coredumps.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.coredump_network_enable my.esxi.host root bad-password True

# Used for connecting to a vCenter Server
salt '*' vsphere.coredump_network_enable my.vcenter.location root bad-password True             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.create_cluster(*args, **kwargs)

Creates a cluster.

Note: cluster_dict['name'] will be overridden by the cluster param value

config_dict
Dictionary with the config values of the new cluster.
datacenter
Name of datacenter containing the cluster. Ignored if already contained by proxy details. Default value is None.
cluster
Name of cluster. Ignored if already contained by proxy details. Default value is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
# esxdatacenter proxy
salt '*' vsphere.create_cluster cluster_dict=$cluster_dict cluster=cl1

# esxcluster proxy
salt '*' vsphere.create_cluster cluster_dict=$cluster_dict
salt.modules.vsphere.create_datacenter(*args, **kwargs)

Creates a datacenter.

Supported proxies: esxdatacenter

datacenter_name
The datacenter name
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.create_datacenter dc1
salt.modules.vsphere.create_diskgroup(*args, **kwargs)

Creates disk group on an ESXi host with the specified cache and capacity disks.

cache_disk_id
The canonical name of the disk to be used as a cache. The disk must be ssd.
capacity_disk_ids
A list containing canonical names of the capacity disks. Must contain at least one id. Default is True.
safety_checks
Specify whether to perform safety check or to skip the checks and try performing the required task. Default value is True.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.create_diskgroup cache_disk_id='naa.000000000000001'
    capacity_disk_ids='[naa.000000000000002, naa.000000000000003]'
salt.modules.vsphere.create_dvportgroup(*args, **kwargs)

Creates a distributed virtual portgroup.

Note: The portgroup_name param will override any name already set in portgroup_dict.

portgroup_dict
Dictionary with the config values the portgroup should be created with (exmaple in salt.states.dvs).
portgroup_name
Name of the portgroup to be created.
dvs
Name of the DVS that will contain the portgroup.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.create_dvportgroup portgroup_dict=<dict>
    portgroup_name=pg1 dvs=dvs1
salt.modules.vsphere.create_dvs(*args, **kwargs)

Creates a distributed virtual switch (DVS).

Note: The dvs_name param will override any name set in dvs_dict.

dvs_dict
Dict representation of the new DVS (exmaple in salt.states.dvs)
dvs_name
Name of the DVS to be created.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.create_dvs dvs dict=$dvs_dict dvs_name=dvs_name
salt.modules.vsphere.create_storage_policy(*args, **kwargs)

Creates a storage policy.

Supported capability types: scalar, set, range.

policy_name
Name of the policy to create. The value of the argument will override any existing name in policy_dict.
policy_dict
Dictionary containing the changes to apply to the policy. (exmaple in salt.states.pbm)
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.create_storage_policy policy_name='policy name'
    policy_dict="$policy_dict"
salt.modules.vsphere.create_vm(*args, **kwargs)

Creates a virtual machine container.

CLI Example:

salt vm_minion vsphere.create_vm vm_name=vmname         cpu='{count: 2, nested: True}' ...
vm_name
Name of the virtual machine
cpu
Properties of CPUs for freshly created machines
memory
Memory size for freshly created machines
image
Virtual machine guest OS version identifier VirtualMachineGuestOsIdentifier
version
Virtual machine container hardware version
datacenter
Datacenter where the virtual machine will be deployed (mandatory)
datastore
Datastore where the virtual machine files will be placed
placement
Resource pool or cluster or host or folder where the virtual machine will be deployed
devices

interfaces .. code-block:: bash

interfaces:

adapter: 'Network adapter 1' name: vlan100 switch_type: distributed or standard adapter_type: vmxnet3 or vmxnet, vmxnet2, vmxnet3, e1000, e1000e mac: '00:11:22:33:44:55' connectable:

allow_guest_control: True connected: True start_connected: True

disks .. code-block:: bash

disks:
adapter: 'Hard disk 1' size: 16 unit: GB address: '0:0' controller: 'SCSI controller 0' thin_provision: False eagerly_scrub: False datastore: 'myshare' filename: 'vm/mydisk.vmdk'

scsi_devices .. code-block:: bash

scsi_devices:
controller: 'SCSI controller 0' type: paravirtual bus_sharing: no_sharing

serial_ports .. code-block:: bash

serial_ports:

adapter: 'Serial port 1' type: network backing:

uri: 'telnet://something:port' direction: <client|server> filename: 'service_uri'
connectable:
allow_guest_control: True connected: True start_connected: True

yield: False

cd_drives .. code-block:: bash

cd_drives:

adapter: 'CD/DVD drive 0' controller: 'IDE 0' device_type: datastore_iso_file datastore_iso_file:

path: path_to_iso
connectable:
allow_guest_control: True connected: True start_connected: True
advanced_config
Advanced config parameters to be set for the virtual machine
salt.modules.vsphere.create_vmfs_datastore(*args, **kwargs)

Creates a ESXi host disk group with the specified cache and capacity disks.

datastore_name
The name of the datastore to be created.
disk_id
The disk id (canonical name) on which the datastore is created.
vmfs_major_version
The VMFS major version.
safety_checks
Specify whether to perform safety check or to skip the checks and try performing the required task. Default is True.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.create_vmfs_datastore datastore_name=ds1 disk_id=
    vmfs_major_version=5
salt.modules.vsphere.delete_advanced_configs(*args, **kwargs)

Removes extra config parameters from a virtual machine

vm_name
Virtual machine name
datacenter
Datacenter name where the virtual machine is available
advanced_configs
List of advanced config values to be removed
service_instance
vCenter service instance for connection and configuration
salt.modules.vsphere.delete_vm(*args, **kwargs)

Deletes a virtual machine defined by name and placement

name
Name of the virtual machine
datacenter
Datacenter of the virtual machine
placement
Placement information of the virtual machine
service_instance
vCenter service instance for connection and configuration
salt '*' vsphere.delete_vm name=my_vm datacenter=my_datacenter
salt.modules.vsphere.disconnect(*args, **kwargs)

Disconnects from a vCenter or ESXi host

Note

Should be used by state functions, not invoked directly.

service_instance
Service instance (vim.ServiceInstance)

CLI Example:

See note above.
salt.modules.vsphere.enable_firewall_ruleset(host, username, password, ruleset_enable, ruleset_name, protocol=None, port=None, esxi_hosts=None, credstore=None)

Enable or disable an ESXi firewall rule set.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
ruleset_enable
True to enable the ruleset, false to disable.
ruleset_name
Name of ruleset to target.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.
Returns:A standard cmd.run_all dictionary, per host.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.enable_firewall_ruleset my.esxi.host root bad-password True 'syslog'

# Used for connecting to a vCenter Server
salt '*' vsphere.enable_firewall_ruleset my.vcenter.location root bad-password True 'syslog'             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.erase_disk_partitions(*args, **kwargs)

Erases the partitions on a disk. The disk can be specified either by the canonical name, or by the scsi_address.

disk_id
Canonical name of the disk. Either disk_id or scsi_address needs to be specified (disk_id supersedes scsi_address.
scsi_address
Scsi address of the disk. disk_id or scsi_address needs to be specified (disk_id supersedes scsi_address.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.erase_disk_partitions scsi_address='vmhaba0:C0:T0:L0'

salt '*' vsphere.erase_disk_partitions disk_id='naa.000000000000001'
salt.modules.vsphere.esxcli_cmd(cmd_str, host=None, username=None, password=None, protocol=None, port=None, esxi_hosts=None, credstore=None)

Run an ESXCLI command directly on the host or list of hosts.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
cmd_str
The ESXCLI command to run. Note: This should not include the -s, -u, -p, -h, --protocol, or --portnumber arguments that are frequently passed when using a bare ESXCLI command from the command line. Those arguments are handled by this function via the other args and kwargs.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.esxcli_cmd my.esxi.host root bad-password             'system coredump network get'

# Used for connecting to a vCenter Server
salt '*' vsphere.esxcli_cmd my.vcenter.location root bad-password             'system coredump network get' esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.get_advanced_configs(*args, **kwargs)

Returns extra config parameters from a virtual machine advanced config list

vm_name
Virtual machine name
datacenter
Datacenter name where the virtual machine is available
service_instance
vCenter service instance for connection and configuration
salt.modules.vsphere.get_coredump_network_config(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None)

Retrieve information on ESXi or vCenter network dump collection and format it into a dictionary.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.
Returns:A dictionary with the network configuration, or, if getting the network config failed, a an error message retrieved from the standard cmd.run_all dictionary, per host.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.get_coredump_network_config my.esxi.host root bad-password

# Used for connecting to a vCenter Server
salt '*' vsphere.get_coredump_network_config my.vcenter.location root bad-password             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.get_firewall_status(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None)

Show status of all firewall rule sets.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.
Returns:Nested dictionary with two toplevel keys rulesets and success success will be True or False depending on query success rulesets will list the rulesets and their statuses if success was true, per host.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.get_firewall_status my.esxi.host root bad-password

# Used for connecting to a vCenter Server
salt '*' vsphere.get_firewall_status my.vcenter.location root bad-password             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.get_host_cache(*args, **kwargs)

Returns the host cache configuration on the proxy host.

service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.get_host_cache
salt.modules.vsphere.get_proxy_type()

Returns the proxy type retrieved either from the pillar of from the proxy minion's config. Returns <undefined> otherwise.

CLI Example:

salt '*' vsphere.get_proxy_type
salt.modules.vsphere.get_service_instance_via_proxy(*args, **kwargs)

Returns a service instance to the proxied endpoint (vCenter/ESXi host).

service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.

Note

Should be used by state functions not invoked directly.

CLI Example:
See note above
salt.modules.vsphere.get_syslog_config(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None)

Retrieve the syslog configuration.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.
Returns:Dictionary with keys and values corresponding to the syslog configuration, per host.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.get_syslog_config my.esxi.host root bad-password

# Used for connecting to a vCenter Server
salt '*' vsphere.get_syslog_config my.vcenter.location root bad-password             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.get_vm(*args, **kwargs)

Returns vm object properties.

name
Name of the virtual machine.
datacenter
Datacenter name
vm_properties
List of vm properties.
traversal_spec
Traversal Spec object(s) for searching.
parent_ref
Container Reference object for searching under a given object.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt.modules.vsphere.get_vm_config(*args, **kwargs)

Queries and converts the virtual machine properties to the available format from the schema. If the objects attribute is True the config objects will have extra properties, like 'object' which will include the vim.vm.device.VirtualDevice, this is necessary for deletion and update actions.

name
Name of the virtual machine
datacenter
Datacenter's name where the virtual machine is available
objects
Indicates whether to return the vmware object properties (eg. object, key) or just the properties which can be set
service_instance
vCenter service instance for connection and configuration
salt.modules.vsphere.get_vm_config_file(*args, **kwargs)

Queries the virtual machine config file and returns vim.host.DatastoreBrowser.SearchResults object on success None on failure

name
Name of the virtual machine
datacenter
Datacenter name
datastore
Datastore where the virtual machine files are stored
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt.modules.vsphere.gets_service_instance_via_proxy(fn)

Decorator that connects to a target system (vCenter or ESXi host) using the proxy details and passes the connection (vim.ServiceInstance) to the decorated function.

Supported proxies: esxi, esxcluster, esxdatacenter.

Notes

1. The decorated function must have a service_instance parameter or a **kwarg type argument (name of argument is not important); 2. If the service_instance parameter is already defined, the value is passed through to the decorated function; 3. If the service_instance parameter in not defined, the connection is created using the proxy details and the service instance is returned.

CLI Example:
None, this is a decorator
salt.modules.vsphere.list_assigned_licenses(*args, **kwargs)

Lists the licenses assigned to an entity

entity
Dictionary representation of an entity. See _get_entity docstrings for format.
entity_display_name
Entity name used in logging
license_keys:
List of license keys to be retrieved. Default is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.list_assigned_licenses
    entity={type:cluster,datacenter:dc,cluster:cl}
    entiy_display_name=cl
salt.modules.vsphere.list_capability_definitions(*args, **kwargs)

Returns a list of the metadata of all capabilities in the vCenter.

service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.list_capabilities
salt.modules.vsphere.list_cluster(*args, **kwargs)

Returns a dict representation of an ESX cluster.

datacenter
Name of datacenter containing the cluster. Ignored if already contained by proxy details. Default value is None.
cluster
Name of cluster. Ignored if already contained by proxy details. Default value is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
# vcenter proxy
salt '*' vsphere.list_cluster datacenter=dc1 cluster=cl1

# esxdatacenter proxy
salt '*' vsphere.list_cluster cluster=cl1

# esxcluster proxy
salt '*' vsphere.list_cluster
salt.modules.vsphere.list_datacenters_via_proxy(*args, **kwargs)

Returns a list of dict representations of VMware datacenters. Connection is done via the proxy details.

Supported proxies: esxdatacenter

datacenter_names
List of datacenter names. Default is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.list_datacenters_via_proxy

salt '*' vsphere.list_datacenters_via_proxy dc1

salt '*' vsphere.list_datacenters_via_proxy dc1,dc2

salt '*' vsphere.list_datacenters_via_proxy datacenter_names=[dc1, dc2]
salt.modules.vsphere.list_datastores_via_proxy(*args, **kwargs)

Returns a list of dict representations of the datastores visible to the proxy object. The list of datastores can be filtered by datastore names, backing disk ids (canonical names) or backing disk scsi addresses.

Supported proxy types: esxi, esxcluster, esxdatacenter

datastore_names
List of the names of datastores to filter on
backing_disk_ids
List of canonical names of the backing disks of the datastores to filer. Default is None.
backing_disk_scsi_addresses
List of scsi addresses of the backing disks of the datastores to filter. Default is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.list_datastores_via_proxy

salt '*' vsphere.list_datastores_via_proxy datastore_names=[ds1, ds2]
salt.modules.vsphere.list_default_storage_policy_of_datastore(*args, **kwargs)

Returns a list of datastores assign the the storage policies.

datastore
Name of the datastore to assign. The datastore needs to be visible to the VMware entity the proxy points to.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.list_default_storage_policy_of_datastore datastore=ds1
salt.modules.vsphere.list_default_vsan_policy(*args, **kwargs)

Returns the default vsan storage policy.

service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.list_storage_policies

salt '*' vsphere.list_storage_policy policy_names=[policy_name]
salt.modules.vsphere.list_disk_partitions(*args, **kwargs)

Lists the partitions on a disk. The disk can be specified either by the canonical name, or by the scsi_address.

disk_id
Canonical name of the disk. Either disk_id or scsi_address needs to be specified (disk_id supersedes scsi_address.
scsi_address`
Scsi address of the disk. disk_id or scsi_address needs to be specified (disk_id supersedes scsi_address.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.list_disk_partitions scsi_address='vmhaba0:C0:T0:L0'

salt '*' vsphere.list_disk_partitions disk_id='naa.000000000000001'
salt.modules.vsphere.list_diskgroups(*args, **kwargs)

Returns a list of disk group dict representation on an ESXi host. The list of disk groups can be filtered by the cache disks canonical names. If no filtering is applied, all disk groups are returned.

cache_disk_ids:
List of cache disk canonical names of the disk groups to be retrieved. Default is None.
use_proxy_details
Specify whether to use the proxy minion's details instead of the arguments
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.list_diskgroups

salt '*' vsphere.list_diskgroups cache_disk_ids='[naa.000000000000001]'
salt.modules.vsphere.list_disks(*args, **kwargs)

Returns a list of dict representations of the disks in an ESXi host. The list of disks can be filtered by disk canonical names or scsi addresses.

disk_ids:
List of disk canonical names to be retrieved. Default is None.
scsi_addresses
List of scsi addresses of disks to be retrieved. Default is None
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.list_disks

salt '*' vsphere.list_disks disk_ids='[naa.00, naa.001]'

salt '*' vsphere.list_disks
    scsi_addresses='[vmhba0:C0:T0:L0, vmhba1:C0:T0:L0]'
salt.modules.vsphere.list_dvportgroups(*args, **kwargs)

Returns a list of distributed virtual switch portgroups. The list can be filtered by the portgroup names or by the DVS.

dvs
Name of the DVS containing the portgroups. Default value is None.
portgroup_names
List of portgroup names to look for. If None, all portgroups are returned. Default value is None
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.list_dvporgroups

salt '*' vsphere.list_dvportgroups dvs=dvs1

salt '*' vsphere.list_dvportgroups portgroup_names=[pg1]

salt '*' vsphere.list_dvportgroups dvs=dvs1 portgroup_names=[pg1]
salt.modules.vsphere.list_dvss(*args, **kwargs)

Returns a list of distributed virtual switches (DVSs). The list can be filtered by the datacenter or DVS names.

datacenter
The datacenter to look for DVSs in. Default value is None.
dvs_names
List of DVS names to look for. If None, all DVSs are returned. Default value is None.
salt '*' vsphere.list_dvss

salt '*' vsphere.list_dvss dvs_names=[dvs1,dvs2]
salt.modules.vsphere.list_hosts_via_proxy(*args, **kwargs)

Returns a list of hosts for the the specified VMware environment. The list of hosts can be filtered by datacenter name and/or cluster name

hostnames
Hostnames to filter on.
datacenter_name
Name of datacenter. Only hosts in this datacenter will be retrieved. Default is None.
cluster_name
Name of cluster. Only hosts in this cluster will be retrieved. If a datacenter is not specified the first cluster with this name will be considerred. Default is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.

CLI Example:

salt '*' vsphere.list_hosts_via_proxy

salt '*' vsphere.list_hosts_via_proxy hostnames=[esxi1.example.com]

salt '*' vsphere.list_hosts_via_proxy datacenter=dc1 cluster=cluster1
salt.modules.vsphere.list_licenses(*args, **kwargs)

Lists all licenses on a vCenter.

service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.list_licenses
salt.modules.vsphere.list_storage_policies(*args, **kwargs)

Returns a list of storage policies.

policy_names
Names of policies to list. If None, all policies are listed. Default is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.list_storage_policies

salt '*' vsphere.list_storage_policy policy_names=[policy_name]

Returns the uplink portgroup of a distributed virtual switch.

dvs
Name of the DVS containing the portgroup.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.list_uplink_dvportgroup dvs=dvs_name
salt.modules.vsphere.power_off_vm(*args, **kwargs)

Powers off a virtual machine specified by it's name.

name
Name of the virtual machine
datacenter
Datacenter of the virtual machine
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.power_off_vm name=my_vm
salt.modules.vsphere.power_on_vm(*args, **kwargs)

Powers on a virtual machine specified by it's name.

name
Name of the virtual machine
datacenter
Datacenter of the virtual machine
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.power_on_vm name=my_vm
salt.modules.vsphere.register_vm(*args, **kwargs)

Registers a virtual machine to the inventory with the given vmx file. Returns comments and change list

name
Name of the virtual machine
datacenter
Datacenter of the virtual machine
placement
Placement dictionary of the virtual machine, host or cluster
vmx_path:
Full path to the vmx file, datastore name should be included
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt.modules.vsphere.remove_capacity_from_diskgroup(*args, **kwargs)

Remove capacity disks from the disk group with the specified cache disk.

cache_disk_id
The canonical name of the cache disk.
capacity_disk_ids
A list containing canonical names of the capacity disks to add.
data_evacuation
Specifies whether to gracefully evacuate the data on the capacity disks before removing them from the disk group. Default value is True.
safety_checks
Specify whether to perform safety check or to skip the checks and try performing the required task. Default value is True.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.remove_capacity_from_diskgroup
    cache_disk_id='naa.000000000000001'
    capacity_disk_ids='[naa.000000000000002, naa.000000000000003]'
salt.modules.vsphere.remove_datastore(*args, **kwargs)

Removes a datastore. If multiple datastores an error is raised.

datastore
Datastore name
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.remove_datastore ds_name
salt.modules.vsphere.remove_diskgroup(*args, **kwargs)

Remove the diskgroup with the specified cache disk.

cache_disk_id
The canonical name of the cache disk.
data_accessibility
Specifies whether to ensure data accessibility. Default value is True.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.remove_diskgroup cache_disk_id='naa.000000000000001'
salt.modules.vsphere.remove_dvportgroup(*args, **kwargs)

Removes a distributed virtual portgroup.

portgroup
Name of the portgroup to be removed.
dvs
Name of the DVS containing the portgroups.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.remove_dvportgroup portgroup=pg1 dvs=dvs1
salt.modules.vsphere.rename_datastore(*args, **kwargs)

Renames a datastore. The datastore needs to be visible to the proxy.

datastore_name
Current datastore name.
new_datastore_name
New datastore name.
service_instance
Service instance (vim.ServiceInstance) of the vCenter/ESXi host. Default is None.
salt '*' vsphere.rename_datastore old_name new_name
salt.modules.vsphere.reset_syslog_config(host, username, password, protocol=None, port=None, syslog_config=None, esxi_hosts=None, credstore=None)

Reset the syslog service to its default settings.

Valid syslog_config values are logdir, loghost, logdir-unique, default-rotate, default-size, default-timeout, or all for all of these.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
syslog_config
List of parameters to reset, provided as a comma-delimited string, or 'all' to reset all syslog configuration parameters. Required.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.
Returns:Dictionary with a top-level key of 'success' which indicates if all the parameters were reset, and individual keys for each parameter indicating which succeeded or failed, per host.

CLI Example:

syslog_config can be passed as a quoted, comma-separated string, e.g.

# Used for ESXi host connection information
salt '*' vsphere.reset_syslog_config my.esxi.host root bad-password             syslog_config='logdir,loghost'

# Used for connecting to a vCenter Server
salt '*' vsphere.reset_syslog_config my.vcenter.location root bad-password             syslog_config='logdir,loghost' esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.set_advanced_configs(*args, **kwargs)

Appends extra config parameters to a virtual machine advanced config list

vm_name
Virtual machine name
datacenter
Datacenter name where the virtual machine is available
advanced_configs
Dictionary with advanced parameter key value pairs
service_instance
vCenter service instance for connection and configuration
salt.modules.vsphere.set_coredump_network_config(host, username, password, dump_ip, protocol=None, port=None, host_vnic='vmk0', dump_port=6500, esxi_hosts=None, credstore=None)

Set the network parameters for a network coredump collection. Note that ESXi requires that the dumps first be enabled (see coredump_network_enable) before these parameters may be set.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
dump_ip
IP address of host that will accept the dump.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
host_vnic
Host VNic port through which to communicate. Defaults to vmk0.
dump_port
TCP port to use for the dump, defaults to 6500.
credstore
Optionally set to path to the credential store file.
Returns:A standard cmd.run_all dictionary with a success key added, per host. success will be True if the set succeeded, False otherwise.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.set_coredump_network_config my.esxi.host root bad-password 'dump_ip.host.com'

# Used for connecting to a vCenter Server
salt '*' vsphere.set_coredump_network_config my.vcenter.location root bad-password 'dump_ip.host.com'             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.set_syslog_config(host, username, password, syslog_config, config_value, protocol=None, port=None, firewall=True, reset_service=True, esxi_hosts=None, credstore=None)

Set the specified syslog configuration parameter. By default, this function will reset the syslog service after the configuration is set.

host
ESXi or vCenter host to connect to.
username
User to connect as, usually root.
password
Password to connect with.
syslog_config

Name of parameter to set (corresponds to the command line switch for esxcli without the double dashes (--))

Valid syslog_config values are logdir, loghost, default-rotate`, ``default-size, default-timeout, and logdir-unique.

config_value

Value for the above parameter. For loghost, URLs or IP addresses to use for logging. Multiple log servers can be specified by listing them, comma-separated, but without spaces before or after commas.

(reference: https://blogs.vmware.com/vsphere/2012/04/configuring-multiple-syslog-servers-for-esxi-5.html)

protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
firewall
Enable the firewall rule set for syslog. Defaults to True.
reset_service
After a successful parameter set, reset the service. Defaults to True.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.
Returns:Dictionary with a top-level key of 'success' which indicates if all the parameters were reset, and individual keys for each parameter indicating which succeeded or failed, per host.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.set_syslog_config my.esxi.host root bad-password             loghost ssl://localhost:5432,tcp://10.1.0.1:1514

# Used for connecting to a vCenter Server
salt '*' vsphere.set_syslog_config my.vcenter.location root bad-password             loghost ssl://localhost:5432,tcp://10.1.0.1:1514             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.supports_proxies(*proxy_types)

Decorator to specify which proxy types are supported by a function

proxy_types:
Arbitrary list of strings with the supported types of proxies
salt.modules.vsphere.syslog_service_reload(host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None)

Reload the syslog service so it will pick up any changes.

host
The location of the host.
username
The username used to login to the host, such as root.
password
The password used to login to the host.
protocol
Optionally set to alternate protocol if the host is not using the default protocol. Default protocol is https.
port
Optionally set to alternate port if the host is not using the default port. Default port is 443.
esxi_hosts
If host is a vCenter host, then use esxi_hosts to execute this function on a list of one or more ESXi machines.
credstore
Optionally set to path to the credential store file.
Returns:A standard cmd.run_all dictionary. This dictionary will at least have a retcode key. If retcode is 0 the command was successful.

CLI Example:

# Used for ESXi host connection information
salt '*' vsphere.syslog_service_reload my.esxi.host root bad-password

# Used for connecting to a vCenter Server
salt '*' vsphere.syslog_service_reload my.vcenter.location root bad-password             esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.test_vcenter_connection(*args, **kwargs)

Checks if a connection is to a vCenter

CLI Example:

salt '*' vsphere.test_vcenter_connection
salt.modules.vsphere.unregister_vm(*args, **kwargs)

Unregisters a virtual machine defined by name and placement

name
Name of the virtual machine
datacenter
Datacenter of the virtual machine
placement
Placement information of the virtual machine
service_instance
vCenter service instance for connection and configuration
salt '*' vsphere.unregister_vm name=my_vm datacenter=my_datacenter
salt.modules.vsphere.update_cluster(*args, **kwargs)

Updates a cluster.

config_dict
Dictionary with the config values of the new cluster.
datacenter
Name of datacenter containing the cluster. Ignored if already contained by proxy details. Default value is None.
cluster
Name of cluster. Ignored if already contained by proxy details. Default value is None.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
# esxdatacenter proxy
salt '*' vsphere.update_cluster cluster_dict=$cluster_dict cluster=cl1

# esxcluster proxy
salt '*' vsphere.update_cluster cluster_dict=$cluster_dict
salt.modules.vsphere.update_dvportgroup(*args, **kwargs)

Updates a distributed virtual portgroup.

portgroup_dict
Dictionary with the values the portgroup should be update with (exmaple in salt.states.dvs).
portgroup
Name of the portgroup to be updated.
dvs
Name of the DVS containing the portgroups.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.update_dvportgroup portgroup_dict=<dict>
    portgroup=pg1

salt '*' vsphere.update_dvportgroup portgroup_dict=<dict>
    portgroup=pg1 dvs=dvs1
salt.modules.vsphere.update_dvs(*args, **kwargs)

Updates a distributed virtual switch (DVS).

Note: Updating the product info, capability, uplinks of a DVS is not
supported so the corresponding entries in dvs_dict will be ignored.
dvs_dict
Dictionary with the values the DVS should be update with (exmaple in salt.states.dvs)
dvs
Name of the DVS to be updated.
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.update_dvs dvs_dict=$dvs_dict dvs=dvs1
salt.modules.vsphere.update_storage_policy(*args, **kwargs)

Updates a storage policy.

Supported capability types: scalar, set, range.

policy
Name of the policy to update.
policy_dict
Dictionary containing the changes to apply to the policy. (exmaple in salt.states.pbm)
service_instance
Service instance (vim.ServiceInstance) of the vCenter. Default is None.
salt '*' vsphere.update_storage_policy policy='policy name'
    policy_dict="$policy_dict"
salt.modules.vsphere.update_vm(*args, **kwargs)

Updates the configuration of the virtual machine if the config differs

vm_name
Virtual Machine name to be updated
cpu
CPU configuration options
memory
Memory configuration options
version
Virtual machine container hardware version
image
Virtual machine guest OS version identifier VirtualMachineGuestOsIdentifier
interfaces
Network interfaces configuration options
disks
Disks configuration options
scsi_devices
SCSI devices configuration options
serial_ports
Serial ports configuration options
datacenter
Datacenter where the virtual machine is available
datastore
Datastore where the virtual machine config files are available
cd_dvd_drives
CD/DVD drives configuration options
advanced_config
Advanced config parameters to be set for the virtual machine
service_instance
vCenter service instance for connection and configuration