neulab/tldr huggingface dataset:
source_auth={ 'type': 'ceph', 'username': 'admin', 'secret': { 'type': 'uuid', 'value': '2ec115d7-3a88-3ceb-bc12-0ac909a6fd87' } }
source_auth={ 'type': 'chap', 'username': 'myname', 'secret': { 'type': 'usage', 'value': 'mycluster_myname' } }
Since 3000, instead the source authentication can only contain username and password properties. In this case the libvirt secret will be defined and used.  For Ceph authentications a base64 encoded key is expected.
• source_name -- Identifier of name-based sources.
• source_format --
String representing the source format. The possible values are depending on the source type. See libvirt documentation for the possible values.
• start -- Pool start (default True)
• transient -- When True, the pool will be automatically undefined after being stopped.  Note that a transient pool will force start to True. (Default: False)
The permissions are described by a dictionary containing the following keys:
mode   The octal representation of the permissions. (Default: 0711)
owner  the numeric user ID of the owner. (Default: from the parent folder)
group  the numeric ID of the group. (Default: from the parent folder)
label  the SELinux label. (Default: None)
Local folder pool:
salt '*' virt.pool_define somepool dir target=/srv/mypool                                   permissions="{'mode': '0744' 'ower': 107, 'group': 107 }"
CIFS backed pool:
salt '*' virt.pool_define myshare netfs source_format=cifs                                   source_dir=samba_share source_hosts="['example.com']" target=/mnt/cifs
salt.modules.virt.pool_delete(name, **kwargs) Delete the resources of a defined libvirt storage pool.
salt '*' virt.pool_delete default
salt.modules.virt.pool_get_xml(name, **kwargs) Return the XML definition of a virtual storage pool
salt '*' virt.pool_get_xml default
salt.modules.virt.pool_info(name=None, **kwargs) Return information on a storage pool provided its name.
If no name is provided, return the infos for all defined storage pools.
salt '*' virt.pool_info default
salt.modules.virt.pool_list_volumes(name, **kwargs) List the volumes contained in a defined libvirt storage pool.
salt "*" virt.pool_list_volumes <pool>
salt.modules.virt.pool_refresh(name, **kwargs) Refresh a defined libvirt storage pool.
salt '*' virt.pool_refresh default
salt.modules.virt.pool_set_autostart(name, state='on', **kwargs) Set the autostart flag on a libvirt storage pool so that the storage pool will start with the host system on reboot.
• state -- 'on' to auto start the pool, anything else to mark the pool not to be started when the host boots
salt "*" virt.pool_set_autostart <pool> <on | off>
salt.modules.virt.pool_start(name, **kwargs) Start a defined libvirt storage pool.
salt '*' virt.pool_start default
salt.modules.virt.pool_stop(name, **kwargs) Stop a defined libvirt storage pool.
salt '*' virt.pool_stop default
salt.modules.virt.pool_undefine(name, **kwargs) Remove a defined libvirt storage pool. The pool needs to be stopped before calling.
salt '*' virt.pool_undefine default
salt.modules.virt.pool_update(name, ptype, target=None, permissions=None, source_devices=None, source_dir=None, source_initiator=None, source_adapter=None, source_hosts=None, source_auth=None, source_name=None, source_format=None, test=False, **kwargs) Update a libvirt storage pool if needed.  If called with test=True, this is also reporting whether an update would be performed.
• ptype --
Pool type. See libvirt documentation  for the possible values.
source_auth={ 'type': 'ceph', 'username': 'admin', 'secret': { 'type': 'uuid', 'uuid': '2ec115d7-3a88-3ceb-bc12-0ac909a6fd87' } }
source_auth={ 'type': 'chap', 'username': 'myname', 'secret': { 'type': 'usage', 'uuid': 'mycluster_myname' } }
• test -- run in dry-run mode if set to True
salt '*' virt.pool_update somepool dir target=/srv/mypool                                   permissions="{'mode': '0744' 'ower': 107, 'group': 107 }"
salt '*' virt.pool_update myshare netfs source_format=cifs                                   source_dir=samba_share source_hosts="['example.com']" target=/mnt/cifs
salt.modules.virt.purge(vm_, dirs=False, removables=False, **kwargs) Recursively destroy and delete a persistent virtual machine, pass True for dir's to also delete the directories containing the virtual machine disk images - USE WITH EXTREME CAUTION!
• dirs -- pass True to remove containing directories
• removables --
pass True to remove removable devices
salt '*' virt.purge <domain>
salt.modules.virt.reboot(name, **kwargs) Reboot a domain via ACPI request
salt.modules.virt.reset(vm_, **kwargs) Reset a VM by emulating the reset button on a physical machine
salt '*' virt.reset <domain>
salt.modules.virt.resume(vm_, **kwargs) Resume the named vm
salt '*' virt.resume <domain>
salt.modules.virt.revert_snapshot(name, vm_snapshot=None, cleanup=False, **kwargs) Revert snapshot to the previous from current (if available) or to the specific.
• vm_snapshot -- name of the snapshot to revert
• cleanup -- Remove all newer than reverted snapshots. Values: True or False (default False).
salt '*' virt.revert <domain> salt '*' virt.revert <domain> <snapshot>
salt.modules.virt.seed_non_shared_migrate(disks, force=False) Non shared migration requires that the disks be present on the migration destination, pass the disks information via this function, to the migration destination before executing the migration.
• disks -- the list of disk data as provided by virt.get_disks
• force -- skip checking the compatibility of source and target disk images if True. (default: False)
salt '*' virt.seed_non_shared_migrate <disks>
salt.modules.virt.set_autostart(vm_, state='on', **kwargs) Set the autostart flag on a VM so that the VM will start with the host system on reboot.
salt "*" virt.set_autostart <domain> <on | off>
salt.modules.virt.setmem(vm_, memory, config=False, **kwargs) Changes the amount of memory allocated to VM. The VM must be shutdown for this to work.
• memory -- memory amount to set in MB
• config -- if True then libvirt will be asked to modify the config as well
salt '*' virt.setmem <domain> <size> salt '*' virt.setmem my_domain 768
salt.modules.virt.setvcpus(vm_, vcpus, config=False, **kwargs) Changes the amount of vcpus allocated to VM. The VM must be shutdown for this to work.
If config is True then we ask libvirt to modify the config as well
• vcpus -- integer representing the number of CPUs to be assigned
salt '*' virt.setvcpus <domain> <amount> salt '*' virt.setvcpus my_domain 4
salt.modules.virt.shutdown(vm_, **kwargs) Send a soft shutdown signal to the named vm
salt.modules.virt.snapshot(domain, name=None, suffix=None, **kwargs) Create a snapshot of a VM.
• name -- Name of the snapshot. If the name is omitted, then will be used original domain name with ISO 8601 time as a suffix.
• suffix -- Add suffix for the new name. Useful in states, where such snapshots can be distinguished from manually created.
salt '*' virt.snapshot <domain>
salt.modules.virt.start(name, **kwargs) Start a defined domain
salt.modules.virt.stop(name, **kwargs) Hard power down the virtual machine, this is equivalent to pulling the power.
salt '*' virt.stop <domain>
salt.modules.virt.undefine(vm_, **kwargs) Remove a defined vm, this does not purge the virtual machine image, and this only works if the vm is powered down
salt '*' virt.undefine <domain>
salt.modules.virt.update(name, cpu=0, mem=0, disk_profile=None, disks=None, nic_profile=None, interfaces=None, graphics=None, live=True, boot=None, numatune=None, test=False, boot_dev=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, host_devices=None, **kwargs) Update the definition of an existing domain.
• name -- Name of the domain to update
To update any cpu parameters specify the new values to the corresponding tag. To remove any element or attribute, specify None object. Please note that None object is mapped to null in yaml, use null in sls file instead.
To remove any parameters, pass a None object, for instance: 'soft_limit': None. Please note  that None is mapped to null in sls file, pass null in sls file instead.
- mem: hard_limit: null soft_limit: null
• disk_profile -- disk profile to use
• disks -- Disk definitions as documented in the init() function.  If neither the profile nor this parameter are defined, the disk devices will not be changed. However to clear disks set this parameter to empty list.
• nic_profile -- network interfaces profile to use
• interfaces -- Network interface definitions as documented in the init() function.  If neither the profile nor this parameter are defined, the interface devices will not be changed. However to clear network interfaces set this parameter to empty list.
• graphics -- The new graphics definition as defined in Graphics Definition. If not set, the graphics will not be changed. To remove a graphics device, set this parameter to {'type': 'none'}.
• live -- False to avoid trying to live update the definition. In such a case, the new definition is applied at the next start of the virtual machine. If True, not all aspects of the definition can be live updated, but as much as possible will be attempted. (Default: True)
Specifies kernel, initial ramdisk and kernel command line parameters for the virtual machine.  This is an optional parameter, all of the keys are optional within the dictionary.
Refer to Boot parameters definition for the complete boot parameter description.
To update any boot parameters, specify the new path for each. To remove any boot parameters, pass None object, for instance: 'kernel': None. To switch back to BIOS boot, specify ('loader': None and 'nvram': None) or 'efi': False. Please note that None is mapped to null in sls file, pass null in sls file instead.
SLS file Example:
- boot: loader: null nvram: null
To update any numatune parameters, specify the new value. To remove any numatune parameters, pass a None object, for instance: 'numatune': None. Please note that None is mapped to null in sls file, pass null in sls file instead.
• test --
run in dry-run mode if set to True
Returns Returns a dictionary indicating the status of what has been done. It is structured in the following way:
{ 'definition': True, 'cpu': True, 'mem': True, 'disks': {'attached': [list of actually attached disks], 'detached': [list of actually detached disks]}, 'nics': {'attached': [list of actually attached nics], 'detached': [list of actually detached nics]}, 'errors': ['error messages for failures'] }
salt '*' virt.update domain cpu=2 mem=1024
salt.modules.virt.virt_type() Returns the virtual machine type as a string
salt '*' virt.virt_type
salt.modules.virt.vm_cputime(vm_=None, **kwargs) Return cputime used by the vms on this hyper in a list of dicts:
[ 'your-vm': { 'cputime' <int> 'cputime_percent' <int> }, ... ]
If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs.
salt '*' virt.vm_cputime
salt.modules.virt.vm_diskstats(vm_=None, **kwargs) Return disk usage counters used by the vms on this hyper in a list of dicts:
[ 'your-vm': { 'rd_req'   : 0, 'rd_bytes' : 0, 'wr_req'   : 0, 'wr_bytes' : 0, 'errs'     : 0 }, ... ]
salt '*' virt.vm_blockstats
salt.modules.virt.vm_info(vm_=None, **kwargs) Return detailed information about the vms on this hyper in a list of dicts:
[ 'your-vm': { 'cpu': <int>, 'maxMem': <int>, 'mem': <int>, 'state': '<state>', 'cputime' <int> }, ... ]
salt '*' virt.vm_info
salt.modules.virt.vm_netstats(vm_=None, **kwargs) Return combined network counters used by the vms on this hyper in a list of dicts:
[ 'your-vm': { 'rx_bytes'   : 0, 'rx_packets' : 0, 'rx_errs'    : 0, 'rx_drop'    : 0, 'tx_bytes'   : 0, 'tx_packets' : 0, 'tx_errs'    : 0, 'tx_drop'    : 0 }, ... ]
salt '*' virt.vm_netstats
salt.modules.virt.vm_state(vm_=None, **kwargs) Return list of all the vms and their state.
salt '*' virt.vm_state <domain>
salt.modules.virt.volume_define(pool, name, size, allocation=0, format=None, type=None, permissions=None, backing_store=None, nocow=False, **kwargs) Create libvirt volume.
• pool -- name of the pool to create the volume in
• name -- name of the volume to define
• size -- capacity of the volume to define in MiB
• allocation -- allocated size of the volume in MiB. Defaults to 0.
• format -- volume format. The allowed values are depending on the pool type.  Check the virt.pool_capabilities output for the possible values and the default.
• type -- type of the volume. One of file, block, dir, network, netdiri, ploop or None.  By default, the type is guessed by libvirt from the pool type.
• backing_store --
dictionary describing a backing file for the volume. It must contain a path property pointing to the base volume and a format property defining the format of the base volume.
The base volume format will not be guessed for security reasons and is thus mandatory.
• nocow -- disable COW for the volume.
Volume on ESX:
salt '*' virt.volume_define "[local-storage]" myvm/myvm.vmdk vmdk 8192
QCow2 volume with backing file:
salt '*' virt.volume_define default myvm.qcow2 qcow2 8192                             permissions="{'mode': '0775', 'owner': '123', 'group': '345'"}"                             backing_store="{'path': '/path/to/base.img', 'format': 'raw'}"                             nocow=True
salt.modules.virt.volume_delete(pool, volume, **kwargs) Delete a libvirt managed volume.
• pool -- libvirt storage pool name
• volume -- name of the volume to delete
salt "*" virt.volume_delete <pool> <volume>
salt.modules.virt.volume_infos(pool=None, volume=None, **kwargs) Provide details on a storage volume. If no volume name is provided, the infos all the volumes contained in the pool are provided. If no pool is provided, the infos of the volumes of all pools are output.
• pool -- libvirt storage pool name (default: None)
• volume -- name of the volume to get infos from (default: None)
salt "*" virt.volume_infos <pool> <volume>
salt.modules.virt.volume_upload(pool, volume, file, offset=0, length=0, sparse=False, **kwargs) Create libvirt volume.
• file -- the file to upload to the volume
• offset -- where to start writing the data in the volume
• length -- amount of bytes to transfer to the volume
• sparse -- set to True to preserve data sparsiness.
salt '*' virt.volume_upload default myvm.qcow2 /path/to/disk.qcow2
salt.modules.virtualenv Create virtualenv environments.
salt.modules.virtualenv_mod.create(path, venv_bin=None, system_site_packages=False, distribute=False, clear=False, python=None, extra_search_dir=None, never_download=None, prompt=None, pip=False, symlinks=None, upgrade=None, user=None, use_vt=False, saltenv='base', **kwargs) Create a virtualenv
path   The path to the virtualenv to be created
venv_bin The name (and optionally path) of the virtualenv command. This can also be set globally in the minion config file as virtualenv.venv_bin.  Defaults to virtualenv.
system_site_packages False Passthrough argument given to virtualenv or pyvenv
distribute False Passthrough argument given to virtualenv
pip    False Install pip after creating a virtual environment. Implies distribute=True
clear  False Passthrough argument given to virtualenv or pyvenv
python None (default) Passthrough argument given to virtualenv
extra_search_dir None (default) Passthrough argument given to virtualenv
never_download None (default) Passthrough argument given to virtualenv if True
prompt None (default) Passthrough argument given to virtualenv if not None
symlinks None Passthrough argument given to pyvenv if True
upgrade None Passthrough argument given to pyvenv if True
user   None Set ownership for the virtualenv
NOTE: On Windows you must also pass a password parameter. Additionally, the user must have permissions to the location where the virtual environment is being created
runas  None Set ownership for the virtualenv
Deprecated since version 2014.1.0: user should be used instead
use_vt False Use VT terminal emulation (see output while installing)
saltenv 'base' Specify a different environment. The default environment is base.
NOTE: The runas argument is deprecated as of 2014.1.0. user should be used instead.
salt '*' virtualenv.create /path/to/new/virtualenv
Example of using --always-copy environment variable (in case your fs doesn't support symlinks). This will copy files into the virtualenv instead of symlinking them.
- env: - VIRTUALENV_ALWAYS_COPY: 1
salt.modules.virtualenv_mod.get_distribution_path(venv, distribution) Return the path to a distribution installed inside a virtualenv
venv   Path to the virtualenv.
distribution Name of the distribution. Note, all non-alphanumeric characters will be converted to dashes.
salt '*' virtualenv.get_distribution_path /path/to/my/venv my_distribution
salt.modules.virtualenv_mod.get_resource_content(venv, package=None, resource=None) Return the content of a package resource installed inside a virtualenv
venv   Path to the virtualenv
package Name of the package in which the resource resides
resource Name of the resource of which the content is to be returned
salt '*' virtualenv.get_resource_content /path/to/my/venv my_package my/resource.xml
salt.modules.virtualenv_mod.get_resource_path(venv, package=None, resource=None) Return the path to a package resource installed inside a virtualenv
resource Name of the resource of which the path is to be returned
salt '*' virtualenv.get_resource_path /path/to/my/venv my_package my/resource.xml
salt.modules.virtualenv_mod.get_site_packages(venv) Return the path to the site-packages directory of a virtualenv
salt '*' virtualenv.get_site_packages /path/to/my/venv
salt.modules.virtualenv_mod.virtualenv_ver(venv_bin, user=None, **kwargs) return virtualenv version if exists
salt.modules.vmctl Manage vms running on the OpenBSD VMM hypervisor using vmctl(8).
codeauthor Jasper Lievisse Adriaanse <jasper@openbsd.org>
NOTE: This module requires the vmd service to be running on the OpenBSD target machine.
salt.modules.vmctl.create_disk(name, size) Create a VMM disk with the specified name and size.
size:  Size in megabytes, or use a specifier such as M, G, T.
salt '*' vmctl.create_disk /path/to/disk.img size=10G
salt.modules.vmctl.load(path) Load additional configuration from the specified file.
path   Path to the configuration file.
salt '*' vmctl.load path=/etc/vm.switches.conf
salt.modules.vmctl.reload() Remove all stopped VMs and reload configuration from the default configuration file.
salt '*' vmctl.reload
salt.modules.vmctl.reset(all=False, vms=False, switches=False) Reset the running state of VMM or a subsystem.
all:   Reset the running state.
switches: Reset the configured switches.
vms:   Reset and terminate all VMs.
salt '*' vmctl.reset all=True
salt.modules.vmctl.start(name=None, id=None, bootpath=None, disk=None, disks=None, local_iface=False, memory=None, nics=0, switch=None) Starts a VM defined by the specified parameters.  When both a name and id are provided, the id is ignored.
name:  Name of the defined VM.
id:    VM id.
bootpath: Path to a kernel or BIOS image to load.
disk:  Path to a single disk to use.
disks: List of multiple disks to use.
local_iface: Whether to add a local network interface. See "LOCAL INTERFACES" in the vmctl(8) manual page for more information.
memory: Memory size of the VM specified in megabytes.
switch: Add a network interface that is attached to the specified virtual switch on the host.
salt '*' vmctl.start 2   # start VM with id 2 salt '*' vmctl.start name=web1 bootpath='/bsd.rd' nics=2 memory=512M disk='/disk.img'
salt.modules.vmctl.status(name=None, id=None) List VMs running on the host, or only the VM specified by id. When both a name and id are provided, the id is ignored.
salt '*' vmctl.status           # to list all VMs salt '*' vmctl.status name=web1 # to get a single VM
salt.modules.vmctl.stop(name=None, id=None) Stop (terminate) the VM identified by the given id or name.  When both a name and id are provided, the id is ignored.
salt '*' vmctl.stop name=alpine
salt.modules.vsphere Manage VMware vCenter servers and ESXi hosts.
codeauthor Alexandru Bleotu <alexandru.bleotu@morganstaley.com>
• ESXCLI
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.
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.
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:
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).
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, verify_ssl=True) 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
verify_ssl Verify the SSL certificate. Default: True
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
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.
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, verify_ssl=None, ca_bundle=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.
salt vm_minion vsphere.attach_tag domain-c2283                 urn:vmomi:InventoryServiceTag:b55ecc77-f4a5-49f8-ab52-38865467cfbe:GLOBAL
• 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.
• verify_ssl (boolean) -- Verify the SSL certificate. Default: True
• ca_bundle (basestring) -- Path to the ca bundle to use when verifying SSL certificates.
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.
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.
# 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.
# 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
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.
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.
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.
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)
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, verify_ssl=None, ca_bundle=None) Create a tag under a category with given description.
salt vm_minion vsphere.create_tag
• 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.
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, verify_ssl=None, ca_bundle=None) Create a category with given cardinality.
salt vm_minion vsphere.create_tag_category
• cardinality (str) -- The associated cardinality (SINGLE, MULTIPLE) of the category.
Returns Identifier of the created category.
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.
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: 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.
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, verify_ssl=None, ca_bundle=None) Delete a tag.
salt vm_minion vsphere.delete_tag
• 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.
Raise  AlreadyExists if the name provided in the create_spec is the name of an already existing category.
salt.modules.vsphere.delete_tag_category(category_id, server=None, username=None, password=None, service_instance=None, verify_ssl=None, ca_bundle=None) Delete a category.
salt vm_minion vsphere.delete_tag_category
• 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.
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.
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
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.
ruleset_enable True to enable the ruleset, false to disable.
ruleset_name Name of ruleset to target.
Returns A standard cmd.run_all dictionary, per host.
# 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.
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.
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.
# 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
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.
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.
# 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.
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.
# 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.
salt '*' vsphere.get_host_cache
salt.modules.vsphere.get_host_datetime(host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True) Get the date/time information for a given host or list of host_names.
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.
# 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, verify_ssl=True) Get the NTP configuration information for a given host or list of host_names.
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.
# 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]'