salt.modules.vsphere

Manage VMware vCenter servers and ESXi hosts.

New in version 2015.8.4.

codeauthor

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.

vSphere Automation SDK

vSphere Automation SDK can be installed via pip:

pip install --upgrade pip setuptools
pip install --upgrade git+https://github.com/vmware/vsphere-automation-sdk-python.git

Note

The SDK also requires OpenSSL 1.0.1+ if you want to connect to vSphere 6.5+ in order to support TLS1.1 & 1.2.

In order to use the tagging functions in this module, vSphere Automation SDK is necessary to install.

The module is currently in version 1.0.3 (as of 8/26/2019)

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(cache_disk_id, capacity_disk_ids, safety_checks=True, service_instance=None)

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_host_to_dvs(host, username, password, vmknic_name, vmnic_name, dvs_name, target_portgroup_name, uplink_portgroup_name, protocol=None, port=None, host_names=None)

Adds an ESXi host to a vSphere Distributed Virtual Switch and migrates the desired adapters to the DVS from the standard switch.

host

The location of the vCenter server.

username

The username used to login to the vCenter server.

password

The password used to login to the vCenter server.

vmknic_name

The name of the virtual NIC to migrate.

vmnic_name

The name of the physical NIC to migrate.

dvs_name

The name of the Distributed Virtual Switch.

target_portgroup_name

The name of the distributed portgroup in which to migrate the virtual NIC.

uplink_portgroup_name

The name of the uplink portgroup in which to migrate the physical NIC.

protocol

Optionally set to alternate protocol if the vCenter server or ESX/ESXi host is not using the default protocol. Default protocol is https.

port

Optionally set to alternate port if the vCenter server or ESX/ESXi host is not using the default port. Default port is 443.

host_names:

An array of VMware host names to migrate

CLI Example:

salt some_host vsphere.add_host_to_dvs host='vsphere.corp.com'
    username='administrator@vsphere.corp.com' password='vsphere_password'
    vmknic_name='vmk0' vmnic_name='vnmic0' dvs_name='DSwitch'
    target_portgroup_name='DPortGroup' uplink_portgroup_name='DSwitch1-DVUplinks-181'
    protocol='https' port='443', host_names="['esxi1.corp.com','esxi2.corp.com','esxi3.corp.com']"

Return Example:

somehost:
    ----------
    esxi1.corp.com:
        ----------
        dvs:
            DSwitch
        portgroup:
            DPortGroup
        status:
            True
        uplink:
            DSwitch-DVUplinks-181
        vmknic:
            vmk0
        vmnic:
            vmnic0
    esxi2.corp.com:
        ----------
        dvs:
            DSwitch
        portgroup:
            DPortGroup
        status:
            True
        uplink:
            DSwitch-DVUplinks-181
        vmknic:
            vmk0
        vmnic:
            vmnic0
    esxi3.corp.com:
        ----------
        dvs:
            DSwitch
        portgroup:
            DPortGroup
        status:
            True
        uplink:
            DSwitch-DVUplinks-181
        vmknic:
            vmk0
        vmnic:
            vmnic0
    message:
    success:
        True

This was very difficult to figure out. VMware's PyVmomi documentation at

https://github.com/vmware/pyvmomi/blob/master/docs/vim/DistributedVirtualSwitch.rst (which is a copy of the official documentation here: https://www.vmware.com/support/developer/converter-sdk/conv60_apireference/vim.DistributedVirtualSwitch.html)

says to create the DVS, create distributed portgroups, and then add the host to the DVS specifying which physical NIC to use as the port backing. However, if the physical NIC is in use as the only link from the host to vSphere, this will fail with an unhelpful "busy" error.

There is, however, a Powershell PowerCLI cmdlet called Add-VDSwitchPhysicalNetworkAdapter that does what we want. I used Onyx (https://labs.vmware.com/flings/onyx) to sniff the SOAP stream from Powershell to our vSphere server and got this snippet out:

<UpdateNetworkConfig xmlns="urn:vim25">
  <_this type="HostNetworkSystem">networkSystem-187</_this>
  <config>
    <vswitch>
      <changeOperation>edit</changeOperation>
      <name>vSwitch0</name>
      <spec>
        <numPorts>7812</numPorts>
      </spec>
    </vswitch>
    <proxySwitch>
        <changeOperation>edit</changeOperation>
        <uuid>73 a4 05 50 b0 d2 7e b9-38 80 5d 24 65 8f da 70</uuid>
        <spec>
        <backing xsi:type="DistributedVirtualSwitchHostMemberPnicBacking">
            <pnicSpec><pnicDevice>vmnic0</pnicDevice></pnicSpec>
        </backing>
        </spec>
    </proxySwitch>
    <portgroup>
      <changeOperation>remove</changeOperation>
      <spec>
        <name>Management Network</name><vlanId>-1</vlanId><vswitchName /><policy />
      </spec>
    </portgroup>
    <vnic>
      <changeOperation>edit</changeOperation>
      <device>vmk0</device>
      <portgroup />
      <spec>
        <distributedVirtualPort>
          <switchUuid>73 a4 05 50 b0 d2 7e b9-38 80 5d 24 65 8f da 70</switchUuid>
          <portgroupKey>dvportgroup-191</portgroupKey>
        </distributedVirtualPort>
      </spec>
    </vnic>
  </config>
  <changeMode>modify</changeMode>
</UpdateNetworkConfig>

The SOAP API maps closely to PyVmomi, so from there it was (relatively) easy to figure out what Python to write.

salt.modules.vsphere.add_license(key, description, safety_checks=True, service_instance=None)

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(policy, datastore, service_instance=None)

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(license_key, license_name, entity, entity_display_name, safety_checks=True, service_instance=None)

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.attach_tag(object_id, tag_id, managed_obj='ClusterComputeResource', server=None, username=None, password=None, service_instance=None)

Attach an existing tag to an input object.

The tag needs to meet the cardinality (CategoryModel.cardinality) and associability (CategoryModel.associable_types) criteria in order to be eligible for attachment. If the tag is already attached to the object, then this method is a no-op and an error will not be thrown. To invoke this method, you need the attach tag privilege on the tag and the read privilege on the object.

CLI Example:

salt vm_minion vsphere.attach_tag domain-c2283                 urn:vmomi:InventoryServiceTag:b55ecc77-f4a5-49f8-ab52-38865467cfbe:GLOBAL
Parameters
  • object_id (str) -- The identifier of the input object.

  • tag_id (str) -- The identifier of the tag object.

  • managed_obj (str) -- Classes that contain methods for creating and deleting resources typically contain a class attribute specifying the resource type for the resources being created and deleted.

  • server (basestring) -- Target DNS or IP of vCenter center.

  • username (basestring) -- Username associated with the vCenter center.

  • password (basestring) -- Password associated with the vCenter center.

Returns

The list of all tag identifiers that correspond to the tags attached to the given object.

Return type

list of tags

Raise

Unauthorized if you do not have the privilege to read the object.

Raise

Unauthenticated if the user can not be authenticated.

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(enabled, datastore=None, swap_size_MiB=None, service_instance=None)

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 than 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(cluster_dict, datacenter=None, cluster=None, service_instance=None)

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(datacenter_name, service_instance=None)

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(cache_disk_id, capacity_disk_ids, safety_checks=True, service_instance=None)

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(portgroup_dict, portgroup_name, dvs, service_instance=None)

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 (example 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(dvs_dict, dvs_name, service_instance=None)

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 (example 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(policy_name, policy_dict, service_instance=None)

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. (example 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_tag(name, description, category_id, server=None, username=None, password=None, service_instance=None)

Create a tag under a category with given description.

CLI Example:

salt vm_minion vsphere.create_tag
Parameters
  • server (basestring) -- Target DNS or IP of vCenter client.

  • username (basestring) -- Username associated with the vCenter client.

  • password (basestring) -- Password associated with the vCenter client.

  • name (str) -- Name of tag category to create (ex. Machine, OS, Availability, etc.)

  • description (str) -- Given description of tag category.

  • category_id (str) -- Value of category_id representative of the category created previously.

Returns

The identifier of the created tag.

Return type

str

Raise

AlreadyExists if the name provided in the create_spec is the name of an already existing tag in the input category.

Raise

InvalidArgument if any of the input information in the create_spec is invalid.

Raise

NotFound if the category for in the given create_spec does not exist in the system.

Raise

Unauthorized if you do not have the privilege to create tag.

salt.modules.vsphere.create_tag_category(name, description, cardinality, server=None, username=None, password=None, service_instance=None)

Create a category with given cardinality.

CLI Example:

salt vm_minion vsphere.create_tag_category
Parameters
  • name (str) -- Name of tag category to create (ex. Machine, OS, Availability, etc.)

  • description (str) -- Given description of tag category.

  • cardinality (str) -- The associated cardinality (SINGLE, MULTIPLE) of the category.

  • server (basestring) -- Target DNS or IP of vCenter center.

  • username (basestring) -- Username associated with the vCenter center.

  • password (basestring) -- Password associated with the vCenter center.

Returns

Identifier of the created category.

Return type

str

Raise

AlreadyExists if the name` provided in the create_spec is the name of an already existing category.

Raise

InvalidArgument if any of the information in the create_spec is invalid.

Raise

Unauthorized if you do not have the privilege to create a category.

salt.modules.vsphere.create_vm(vm_name, cpu, memory, image, version, datacenter, datastore, placement, interfaces, disks, scsi_devices, serial_ports=None, ide_controllers=None, sata_controllers=None, cd_drives=None, advanced_configs=None, service_instance=None)

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

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

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

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

serial_ports

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

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(datastore_name, disk_id, vmfs_major_version, safety_checks=True, service_instance=None)

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(vm_name, datacenter, advanced_configs, service_instance=None)

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_tag(tag_id, server=None, username=None, password=None, service_instance=None)

Delete a tag.

CLI Example:

salt vm_minion vsphere.delete_tag
Parameters
  • tag_id (str) -- The identifier of tag to be deleted. The parameter must be an identifier for the resource type: com.vmware.cis.tagging.Tag.

  • server (basestring) -- Target DNS or IP of vCenter center.

  • username (basestring) -- Username associated with the vCenter center.

  • password (basestring) -- Password associated with the vCenter center.

Raise

AlreadyExists if the name provided in the create_spec is the name of an already existing category.

Raise

InvalidArgument if any of the information in the create_spec is invalid.

Raise

Unauthorized if you do not have the privilege to create a category.

salt.modules.vsphere.delete_tag_category(category_id, server=None, username=None, password=None, service_instance=None)

Delete a category.

CLI Example:

salt vm_minion vsphere.delete_tag_category
Parameters
  • category_id (str) -- The identifier of category to be deleted. The parameter must be an identifier for the resource type: com.vmware.cis.tagging.Category.

  • server (basestring) -- Target DNS or IP of vCenter center.

  • username (basestring) -- Username associated with the vCenter center.

  • password (basestring) -- Password associated with the vCenter center.

Raise

NotFound if the tag for the given tag_id does not exist in the system.

Raise

Unauthorized if you do not have the privilege to delete the tag.

Raise

Unauthenticated if the user can not be authenticated.

salt.modules.vsphere.delete_vm(name, datacenter, placement=None, power_off=False, service_instance=None)

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(service_instance)

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(disk_id=None, scsi_address=None, service_instance=None)

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(vm_name, datacenter, service_instance=None)

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(service_instance=None)

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_host_datetime(host, username, password, protocol=None, port=None, host_names=None)

Get the date/time information for a given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get date/time information.

If host_names is not provided, the date/time information will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Get the NTP configuration information for a given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get ntp configuration information.

If host_names is not provided, the NTP configuration will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

# Used for connecting to a vCenter Server
salt '*' vsphere.get_ntp_config my.vcenter.location root bad-password         host_names='[esxi-1.host.com, esxi-2.host.com]'
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(service_instance=None)

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_service_policy(host, username, password, service_name, protocol=None, port=None, host_names=None)

Get the service name's policy for a given 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.

service_name
The name of the service for which to retrieve the policy. Supported service names are:
  • DCUI

  • TSM

  • SSH

  • lbtd

  • lsassd

  • lwiod

  • netlogond

  • ntpd

  • sfcbd-watchdog

  • snmpd

  • vprobed

  • vpxa

  • xorg

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get service policy information.

If host_names is not provided, the service policy information will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Get the service name's running state for a given 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.

service_name
The name of the service for which to retrieve the policy. Supported service names are:
  • DCUI

  • TSM

  • SSH

  • lbtd

  • lsassd

  • lwiod

  • netlogond

  • ntpd

  • sfcbd-watchdog

  • snmpd

  • vprobed

  • vpxa

  • xorg

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to get the service's running state.

If host_names is not provided, the service's running state will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

# Used for connecting to a vCenter Server
salt '*' vsphere.get_service_running my.vcenter.location root bad-password 'ntpd'         host_names='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.get_ssh_key(host, username, password, protocol=None, port=None, certificate_verify=False)

Retrieve the authorized_keys entry for root. This function only works for ESXi, not vCenter.

Parameters
  • host -- The location of the ESXi Host

  • username -- Username to connect as

  • password -- Password for the ESXi web endpoint

  • protocol -- defaults to https, can be http if ssl is disabled on ESXi

  • port -- defaults to 443 for https

  • certificate_verify -- If true require that the SSL connection present a valid certificate

Returns

True if upload is successful

CLI Example:

salt '*' vsphere.get_ssh_key my.esxi.host root bad-password certificate_verify=True
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(name, datacenter=None, vm_properties=None, traversal_spec=None, parent_ref=None, service_instance=None)

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(name, datacenter=None, objects=True, service_instance=None)

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(name, datacenter, placement, datastore, service_instance=None)

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.get_vmotion_enabled(host, username, password, protocol=None, port=None, host_names=None)

Get the VMotion enabled status for a given host or a list of host_names. Returns True if VMotion is enabled, False if it is not enabled.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to check if VMotion is enabled.

If host_names is not provided, the VMotion status will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Returns a list of VSAN-eligible disks for a given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to check if any VSAN-eligible disks are available.

If host_names is not provided, the VSAN-eligible disks will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Get the VSAN enabled status for a given host or a list of host_names. Returns True if VSAN is enabled, False if it is not enabled, and None if a VSAN Host Config is unset, per 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.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to check if VSAN enabled.

If host_names is not provided, the VSAN status will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

# Used for connecting to a vCenter Server
salt '*' vsphere.get_vsan_enabled my.vcenter.location root bad-password         host_names='[esxi-1.host.com, esxi-2.host.com]'
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(entity, entity_display_name, license_keys=None, service_instance=None)

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_attached_tags(object_id, managed_obj='ClusterComputeResource', server=None, username=None, password=None, service_instance=None)

List existing tags a user has access to.

CLI Example:

salt vm_minion vsphere.list_attached_tags domain-c2283
Parameters
  • object_id (str) -- The identifier of the input object.

  • managed_obj (str) -- Classes that contain methods for creating and deleting resources typically contain a class attribute specifying the resource type for the resources being created and deleted.

  • server (basestring) -- Target DNS or IP of vCenter center.

  • username (basestring) -- Username associated with the vCenter center.

  • password (basestring) -- Password associated with the vCenter center.

Returns

The list of all tag identifiers that correspond to the tags attached to the given object.

Return type

list of tags

Raise

Unauthorized if you do not have the privilege to read the object.

Raise

Unauthenticated if the user can not be authenticated.

salt.modules.vsphere.list_capability_definitions(service_instance=None)

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(datacenter=None, cluster=None, service_instance=None)

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_clusters(host, username, password, protocol=None, port=None)

Returns a list of clusters for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_clusters 1.2.3.4 root bad-password
salt.modules.vsphere.list_datacenters(host, username, password, protocol=None, port=None)

Returns a list of datacenters for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_datacenters 1.2.3.4 root bad-password
salt.modules.vsphere.list_datacenters_via_proxy(datacenter_names=None, service_instance=None)

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_datastore_clusters(host, username, password, protocol=None, port=None)

Returns a list of datastore clusters for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_datastore_clusters 1.2.3.4 root bad-password
salt.modules.vsphere.list_datastores(host, username, password, protocol=None, port=None)

Returns a list of datastores for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_datastores 1.2.3.4 root bad-password
salt.modules.vsphere.list_datastores_via_proxy(datastore_names=None, backing_disk_ids=None, backing_disk_scsi_addresses=None, service_instance=None)

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(datastore, service_instance=None)

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(service_instance=None)

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(disk_id=None, scsi_address=None, service_instance=None)

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(cache_disk_ids=None, service_instance=None)

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(disk_ids=None, scsi_addresses=None, service_instance=None)

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(dvs=None, portgroup_names=None, service_instance=None)

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_dvs(host, username, password, protocol=None, port=None)

Returns a list of distributed virtual switches for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_dvs 1.2.3.4 root bad-password
salt.modules.vsphere.list_dvss(datacenter=None, dvs_names=None, service_instance=None)

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_folders(host, username, password, protocol=None, port=None)

Returns a list of folders for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_folders 1.2.3.4 root bad-password
salt.modules.vsphere.list_hosts(host, username, password, protocol=None, port=None)

Returns a list of hosts for the the specified VMware environment.

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.

CLI Example:

salt '*' vsphere.list_hosts 1.2.3.4 root bad-password
salt.modules.vsphere.list_hosts_via_proxy(hostnames=None, datacenter=None, cluster=None, service_instance=None)

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(service_instance=None)

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_networks(host, username, password, protocol=None, port=None)

Returns a list of networks for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_networks 1.2.3.4 root bad-password
salt.modules.vsphere.list_non_ssds(host, username, password, protocol=None, port=None, host_names=None)

Returns a list of Non-SSD disks for the given host or list of host_names.

Note

In the pyVmomi StorageSystem, ScsiDisks may, or may not have an ssd attribute. This attribute indicates if the ScsiDisk is SSD backed. As this option is optional, if a relevant disk in the StorageSystem does not have ssd = true, it will end up in the non_ssds list here.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to retrieve Non-SSD disks.

If host_names is not provided, Non-SSD disks will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Returns a list of resource pools for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_resourcepools 1.2.3.4 root bad-password
salt.modules.vsphere.list_ssds(host, username, password, protocol=None, port=None, host_names=None)

Returns a list of SSDs for the given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to retrieve SSDs.

If host_names is not provided, SSDs will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

# Used for connecting to a vCenter Server
salt '*' vsphere.list_ssds my.vcenter.location root bad-password         host_names='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.list_storage_policies(policy_names=None, service_instance=None)

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]
salt.modules.vsphere.list_tag_categories(server=None, username=None, password=None, service_instance=None)

List existing categories a user has access to.

CLI Example:

salt vm_minion vsphere.list_tag_categories
Parameters
  • server (basestring) -- Target DNS or IP of vCenter center.

  • username (basestring) -- Username associated with the vCenter center.

  • password (basestring) -- Password associated with the vCenter center.

Returns

Value(s) of category_id.

Return type

list of str

salt.modules.vsphere.list_tags(server=None, username=None, password=None, service_instance=None)

List existing tags a user has access to.

CLI Example:

salt vm_minion vsphere.list_tags
Parameters
  • server (basestring) -- Target DNS or IP of vCenter center.

  • username (basestring) -- Username associated with the vCenter center.

  • password (basestring) -- Password associated with the vCenter center.

Returns

Value(s) of tag_id.

Return type

list of str

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.list_vapps(host, username, password, protocol=None, port=None)

Returns a list of vApps for the the specified 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.

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.

CLI Example:

# List vapps from all minions
salt '*' vsphere.list_vapps 1.2.3.4 root bad-password
salt.modules.vsphere.list_vms(host, username, password, protocol=None, port=None)

Returns a list of VMs for the the specified 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.

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.

CLI Example:

salt '*' vsphere.list_vms 1.2.3.4 root bad-password
salt.modules.vsphere.power_off_vm(name, datacenter=None, service_instance=None)

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(name, datacenter=None, service_instance=None)

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(name, datacenter, placement, vmx_path, service_instance=None)

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(cache_disk_id, capacity_disk_ids, data_evacuation=True, safety_checks=True, service_instance=None)

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(datastore, service_instance=None)

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(cache_disk_id, data_accessibility=True, service_instance=None)

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(portgroup, dvs, service_instance=None)

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(datastore_name, new_datastore_name, service_instance=None)

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.service_restart(host, username, password, service_name, protocol=None, port=None, host_names=None)

Restart the named service for the given 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.

service_name
The name of the service for which to set the policy. Supported service names are:
  • DCUI

  • TSM

  • SSH

  • lbtd

  • lsassd

  • lwiod

  • netlogond

  • ntpd

  • sfcbd-watchdog

  • snmpd

  • vprobed

  • vpxa

  • xorg

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to restart the service.

If host_names is not provided, the service will be restarted for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Start the named service for the given 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.

service_name
The name of the service for which to set the policy. Supported service names are:
  • DCUI

  • TSM

  • SSH

  • lbtd

  • lsassd

  • lwiod

  • netlogond

  • ntpd

  • sfcbd-watchdog

  • snmpd

  • vprobed

  • vpxa

  • xorg

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to start the service.

If host_names is not provided, the service will be started for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Stop the named service for the given 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.

service_name
The name of the service for which to set the policy. Supported service names are:
  • DCUI

  • TSM

  • SSH

  • lbtd

  • lsassd

  • lwiod

  • netlogond

  • ntpd

  • sfcbd-watchdog

  • snmpd

  • vprobed

  • vpxa

  • xorg

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to stop the service.

If host_names is not provided, the service will be stopped for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

# Used for connecting to a vCenter Server
salt '*' vsphere.service_stop my.vcenter.location root bad-password 'ssh'         host_names='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.set_advanced_configs(vm_name, datacenter, advanced_configs, service_instance=None)

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_ntp_config(host, username, password, ntp_servers, protocol=None, port=None, host_names=None)

Set NTP configuration for a given host of list of host_names.

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.

ntp_servers

A list of servers that should be added to and configured for the specified host's NTP configuration.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts to configure ntp servers.

If host_names is not provided, the NTP servers will be configured for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

# Used for single ESXi host connection information
salt '*' vsphere.ntp_configure my.esxi.host root bad-password '[192.174.1.100, 192.174.1.200]'

# Used for connecting to a vCenter Server
salt '*' vsphere.ntp_configure my.vcenter.location root bad-password '[192.174.1.100, 192.174.1.200]'         host_names='[esxi-1.host.com, esxi-2.host.com]'
salt.modules.vsphere.set_service_policy(host, username, password, service_name, service_policy, protocol=None, port=None, host_names=None)

Set the service name's policy for a given 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.

service_name
The name of the service for which to set the policy. Supported service names are:
  • DCUI

  • TSM

  • SSH

  • lbtd

  • lsassd

  • lwiod

  • netlogond

  • ntpd

  • sfcbd-watchdog

  • snmpd

  • vprobed

  • vpxa

  • xorg

service_policy

The policy to set for the service. For example, 'automatic'.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter the hosts for which to set the service policy.

If host_names is not provided, the service policy information will be retrieved for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

# Used for single ESXi host connection information
salt '*' vsphere.set_service_policy my.esxi.host root bad-password 'ntpd' 'automatic'

# Used for connecting to a vCenter Server
salt '*' vsphere.set_service_policy my.vcenter.location root bad-password 'ntpd' 'automatic'         host_names='[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.system_info(host, username, password, protocol=None, port=None)

Return system information about a VMware environment.

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.

CLI Example:

salt '*' vsphere.system_info 1.2.3.4 root bad-password
salt.modules.vsphere.test_vcenter_connection(service_instance=None)

Checks if a connection is to a vCenter

CLI Example:

salt '*' vsphere.test_vcenter_connection
salt.modules.vsphere.unregister_vm(name, datacenter, placement=None, power_off=False, service_instance=None)

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(cluster_dict, datacenter=None, cluster=None, service_instance=None)

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(portgroup_dict, portgroup, dvs, service_instance=True)

Updates a distributed virtual portgroup.

portgroup_dict

Dictionary with the values the portgroup should be update with (example 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(dvs_dict, dvs, service_instance=None)

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 (example 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_host_datetime(host, username, password, protocol=None, port=None, host_names=None)

Update the date/time on the given host or list of host_names. This function should be used with caution since network delays and execution delays can result in time skews.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should update their date/time.

If host_names is not provided, the date/time will be updated for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Update the password for a given host.

Note

Currently only works with connections to ESXi hosts. Does not work with vCenter servers.

host

The location of the ESXi host.

username

The username used to login to the ESXi host, such as root.

password

The password used to login to the ESXi host.

new_password

The new password that will be updated for the provided username on the ESXi 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.

CLI Example:

salt '*' vsphere.update_host_password my.esxi.host root original-bad-password new-bad-password
salt.modules.vsphere.update_storage_policy(policy, policy_dict, service_instance=None)

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. (example 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(vm_name, cpu=None, memory=None, image=None, version=None, interfaces=None, disks=None, scsi_devices=None, serial_ports=None, datacenter=None, datastore=None, cd_dvd_drives=None, sata_controllers=None, advanced_configs=None, service_instance=None)

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

salt.modules.vsphere.upload_ssh_key(host, username, password, ssh_key=None, ssh_key_file=None, protocol=None, port=None, certificate_verify=False)

Upload an ssh key for root to an ESXi host via http PUT. This function only works for ESXi, not vCenter. Only one ssh key can be uploaded for root. Uploading a second key will replace any existing key.

Parameters
  • host -- The location of the ESXi Host

  • username -- Username to connect as

  • password -- Password for the ESXi web endpoint

  • ssh_key -- Public SSH key, will be added to authorized_keys on ESXi

  • ssh_key_file -- File containing the SSH key. Use 'ssh_key' or ssh_key_file, but not both.

  • protocol -- defaults to https, can be http if ssl is disabled on ESXi

  • port -- defaults to 443 for https

  • certificate_verify -- If true require that the SSL connection present a valid certificate

Returns

Dictionary with a 'status' key, True if upload is successful. If upload is unsuccessful, 'status' key will be False and an 'Error' key will have an informative message.

CLI Example:

salt '*' vsphere.upload_ssh_key my.esxi.host root bad-password ssh_key_file='/etc/salt/my_keys/my_key.pub'
salt.modules.vsphere.vmotion_disable(host, username, password, protocol=None, port=None, host_names=None)

Disable vMotion for a given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should disable VMotion.

If host_names is not provided, VMotion will be disabled for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Enable vMotion for a given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should enable VMotion.

If host_names is not provided, VMotion will be enabled for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

device

The device that uniquely identifies the VirtualNic that will be used for VMotion for each host. Defaults to vmk0.

CLI Example:

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

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

Add any VSAN-eligible disks to the VSAN System for the given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts need to add any VSAN-eligible disks to the host's VSAN system.

If host_names is not provided, VSAN-eligible disks will be added to the hosts's VSAN system for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Disable VSAN for a given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should disable VSAN.

If host_names is not provided, VSAN will be disabled for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

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

Enable VSAN for a given host or list of host_names.

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.

host_names

List of ESXi host names. When the host, username, and password credentials are provided for a vCenter Server, the host_names argument is required to tell vCenter which hosts should enable VSAN.

If host_names is not provided, VSAN will be enabled for the host location instead. This is useful for when service instance connection information is used for a single ESXi host.

CLI Example:

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

# Used for connecting to a vCenter Server
salt '*' vsphere.vsan_enable my.vcenter.location root bad-password         host_names='[esxi-1.host.com, esxi-2.host.com]'