Work with virtual machines managed by libvirt
depends: | libvirt Python module |
---|
The connection to the virtualization host can be either setup in the minion configuration, pillar data or overridden for each individual call.
By default, the libvirt connection URL will be guessed: the first available libvirt hypervisor driver will be used. This can be overridden like this:
virt:
connection:
uri: lxc:///
If the connection requires an authentication like for ESXi, this can be defined in the minion pillar data like this:
virt:
connection:
uri: esx://10.1.1.101/?no_verify=1&auto_answer=1
auth:
username: user
password: secret
Libvirt can connect to remote hosts using SSH using one of the ssh
, libssh
and
libssh2
transports. Note that libssh2
is likely to fail as it doesn't read the
known_hosts
file. Libvirt may also have been built without libssh
or libssh2
support.
To use the SSH transport, on the minion setup an SSH agent with a key authorized on the remote libvirt machine.
New in version 2019.2.0.
All the calls requiring the libvirt connection configuration as mentioned above can
override this configuration using connection
, username
and password
parameters.
This means that the following will list the domains on the local LXC libvirt driver,
whatever the virt:connection
is.
salt 'hypervisor' virt.list_domains connection=lxc:///
The calls not using the libvirt connection setup are:
seed_non_shared_migrate
virt_type
is_*hyper
salt.modules.virt.
all_capabilities
(**kwargs)¶Return the host and domain capabilities in a single call.
New in version Neon.
Parameters: |
|
---|
CLI Example:
salt '*' virt.all_capabilities
salt.modules.virt.
capabilities
(**kwargs)¶Return the hypervisor connection capabilities.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.capabilities
salt.modules.virt.
cpu_baseline
(full=False, migratable=False, out=u'libvirt', **kwargs)¶Return the optimal 'custom' CPU baseline config for VM's on this minion
New in version 2016.3.0.
Parameters: |
|
---|
CLI Example:
salt '*' virt.cpu_baseline
salt.modules.virt.
create_xml_path
(path, **kwargs)¶Start a transient domain based on the XML-file path passed to the function
Parameters: |
|
---|
CLI Example:
salt '*' virt.create_xml_path <path to XML file on the node>
salt.modules.virt.
create_xml_str
(xml, **kwargs)¶Start a transient domain based on the XML passed to the function
Parameters: |
|
---|
CLI Example:
salt '*' virt.create_xml_str <XML in string format>
salt.modules.virt.
ctrl_alt_del
(vm_, **kwargs)¶Sends CTRL+ALT+DEL to a VM
Parameters: |
|
---|
CLI Example:
salt '*' virt.ctrl_alt_del <domain>
salt.modules.virt.
define_vol_xml_path
(path, **kwargs)¶Define a volume based on the XML-file path passed to the function
Parameters: |
|
---|
CLI Example:
salt '*' virt.define_vol_xml_path <path to XML file on the node>
salt.modules.virt.
define_vol_xml_str
(xml, **kwargs)¶Define a volume based on the XML passed to the function
Parameters: |
|
---|
CLI Example:
salt '*' virt.define_vol_xml_str <XML in string format>
The storage pool where the disk image will be defined is default
unless changed with a configuration like this:
virt:
storagepool: mine
salt.modules.virt.
define_xml_path
(path, **kwargs)¶Define a persistent domain based on the XML-file path passed to the function
Parameters: |
|
---|
CLI Example:
salt '*' virt.define_xml_path <path to XML file on the node>
salt.modules.virt.
define_xml_str
(xml, **kwargs)¶Define a persistent domain based on the XML passed to the function
Parameters: |
|
---|
CLI Example:
salt '*' virt.define_xml_str <XML in string format>
salt.modules.virt.
delete_snapshots
(name, *names, **kwargs)¶Delete one or more snapshots of the given VM.
Parameters: |
|
---|
New in version 2016.3.0.
CLI Example:
salt '*' virt.delete_snapshots <domain> all=True
salt '*' virt.delete_snapshots <domain> <snapshot>
salt '*' virt.delete_snapshots <domain> <snapshot1> <snapshot2> ...
salt.modules.virt.
domain_capabilities
(emulator=None, arch=None, machine=None, domain=None, **kwargs)¶Return the domain capabilities given an emulator, architecture, machine or virtualization type.
New in version 2019.2.0.
Parameters: |
|
---|
The list of the possible emulator, arch, machine and domain can be found in the host capabilities output.
If none of the parameters is provided, the libvirt default one is returned.
CLI Example:
salt '*' virt.domain_capabilities arch='x86_64' domain='kvm'
salt.modules.virt.
freecpu
(**kwargs)¶Return an int representing the number of unallocated cpus on this hypervisor
Parameters: |
|
---|
CLI Example:
salt '*' virt.freecpu
salt.modules.virt.
freemem
(**kwargs)¶Return an int representing the amount of memory (in MB) that has not been given to virtual machines on this node
Parameters: |
|
---|
CLI Example:
salt '*' virt.freemem
salt.modules.virt.
full_info
(**kwargs)¶Return the node_info, vm_info and freemem
Parameters: |
|
---|
CLI Example:
salt '*' virt.full_info
salt.modules.virt.
get_disks
(vm_, **kwargs)¶Return the disks of a named vm
Parameters: |
|
---|
CLI Example:
salt '*' virt.get_disks <domain>
salt.modules.virt.
get_graphics
(vm_, **kwargs)¶Returns the information on vnc for a given vm
Parameters: |
|
---|
CLI Example:
salt '*' virt.get_graphics <domain>
salt.modules.virt.
get_hypervisor
()¶Returns the name of the hypervisor running on this node or None
.
Detected hypervisors:
CLI Example:
salt '*' virt.get_hypervisor
New in version 2019.2.0: the function and the kvm
, xen
and bhyve
hypervisors support
salt.modules.virt.
get_loader
(vm_, **kwargs)¶Returns the information on the loader for a given vm
Parameters: |
|
---|
CLI Example:
salt '*' virt.get_loader <domain>
New in version 2019.2.0.
salt.modules.virt.
get_macs
(vm_, **kwargs)¶Return a list off MAC addresses from the named vm
Parameters: |
|
---|
CLI Example:
salt '*' virt.get_macs <domain>
salt.modules.virt.
get_nics
(vm_, **kwargs)¶Return info about the network interfaces of a named vm
Parameters: |
|
---|
CLI Example:
salt '*' virt.get_nics <domain>
salt.modules.virt.
get_profiles
(hypervisor=None, **kwargs)¶Return the virt profiles for hypervisor.
Currently there are profiles for:
Parameters: |
|
---|
CLI Example:
salt '*' virt.get_profiles
salt '*' virt.get_profiles hypervisor=esxi
salt.modules.virt.
get_xml
(vm_, **kwargs)¶Returns the XML for a given vm
Parameters: |
|
---|
CLI Example:
salt '*' virt.get_xml <domain>
salt.modules.virt.
init
(name, cpu, mem, image=None, nic=u'default', interfaces=None, hypervisor=None, start=True, disk=u'default', disks=None, saltenv=u'base', seed=True, install=True, pub_key=None, priv_key=None, seed_cmd=u'seed.apply', enable_vnc=False, enable_qcow=False, graphics=None, os_type=None, arch=None, loader=None, **kwargs)¶Initialize a new vm
Parameters: |
|
---|
New in version 2019.2.0.
Parameters: | username -- username to connect with, overriding defaults |
---|
New in version 2019.2.0.
Parameters: | password -- password to connect with, overriding defaults |
---|
New in version 2019.2.0.
Network Interface Definitions
Network interfaces dictionaries can contain the following properties:
'bridge'
, 'network'
None
(Default: None
).Disk Definitions
Disk dictionaries can contain the following properties:
'qcow2'
, 'raw'
, 'vmdk'
.
(Default: depends on the hypervisor)One of the disk busses allowed by libvirt (Default: depends on hypervisor)
See the libvirt disk element documentation for the allowed bus types.
None
)True
to create a QCOW2 disk image with image
as backing file. If False
the file pointed to by the image
property will simply be copied. (Default: False
)None
)Boolean to specify whether to use a thin provisioned ZFS volume.
Example profile for a bhyve VM with two ZFS disks. The first is cloned from the specified image. The second disk is a thin provisioned volume.
virt:
disk:
two_zvols:
- system:
image: zroot/bhyve/CentOS-7-x86_64-v1@v1.0.5
hostname_property: virt:hostname
pool: zroot/bhyve/guests
- data:
pool: tank/disks
size: 20G
hostname_property: virt:hostname
sparse_volume: True
image
parameter. This
parameter is useful to use disk images that are created outside of this module. Can also
be None
for devices that have no associated image like cdroms.'disk'
)Graphics Definition
The graphics dictionnary can have the following properties:
Graphics type. The possible values are none
, 'spice'
, 'vnc'
and other values
allowed as a libvirt graphics type (Default: None
)
See the libvirt graphics element documentation for more details on the possible types.
vnc
, spice
and rdp
types.spice
type.Dictionary defining on what address to listen on for vnc
, spice
and rdp
.
It has a type
property with address
and None
as possible values, and an
address
property holding the IP or hostname to listen on.
By default, not setting the listen
part of the dictionary will default to
listen on all addresses.
Loader Definition
The loader dictionary must have the following property:
Optionally, you can provide arbitrary attributes such as readonly
or type
. See
the libvirt documentation for all supported loader parameters.
CLI Example:
salt 'hypervisor' virt.init vm_name 4 512 salt://path/to/image.raw
salt 'hypervisor' virt.init vm_name 4 512 /var/lib/libvirt/images/img.raw
salt 'hypervisor' virt.init vm_name 4 512 nic=profile disk=profile
The disk images will be created in an image folder within the directory
defined by the virt:images
option. Its default value is
/srv/salt-images/
but this can changed with such a configuration:
virt:
images: /data/my/vm/images/
salt.modules.virt.
is_hyper
()¶Returns a bool whether or not this node is a hypervisor of any kind
CLI Example:
salt '*' virt.is_hyper
salt.modules.virt.
is_kvm_hyper
()¶Returns a bool whether or not this node is a KVM hypervisor
CLI Example:
salt '*' virt.is_kvm_hyper
Deprecated since version 2019.2.0.
salt.modules.virt.
is_xen_hyper
()¶Returns a bool whether or not this node is a XEN hypervisor
CLI Example:
salt '*' virt.is_xen_hyper
Deprecated since version 2019.2.0.
salt.modules.virt.
list_active_vms
(**kwargs)¶Return a list of names for active virtual machine on the minion
Parameters: |
|
---|
CLI Example:
salt '*' virt.list_active_vms
salt.modules.virt.
list_domains
(**kwargs)¶Return a list of available domains.
Parameters: |
|
---|
CLI Example:
salt '*' virt.list_domains
salt.modules.virt.
list_inactive_vms
(**kwargs)¶Return a list of names for inactive virtual machine on the minion
Parameters: |
|
---|
CLI Example:
salt '*' virt.list_inactive_vms
salt.modules.virt.
list_networks
(**kwargs)¶List all virtual networks.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.list_networks
salt.modules.virt.
list_pools
(**kwargs)¶List all storage pools.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.list_pools
salt.modules.virt.
list_snapshots
(domain=None, **kwargs)¶List available snapshots for certain vm or for all.
Parameters: |
|
---|
New in version 2016.3.0.
CLI Example:
salt '*' virt.list_snapshots
salt '*' virt.list_snapshots <domain>
salt.modules.virt.
migrate
(vm_, target, ssh=False)¶Shared storage migration
Parameters: |
|
---|
CLI Example:
salt '*' virt.migrate <domain> <target hypervisor>
A tunnel data migration can be performed by setting this in the configuration:
virt:
tunnel: True
For more details on tunnelled data migrations, report to https://libvirt.org/migration.html#transporttunnel
Attempt to execute non-shared storage "all" migration
Parameters: |
|
---|
CLI Example:
salt '*' virt.migrate_non_shared <vm name> <target hypervisor>
A tunnel data migration can be performed by setting this in the configuration:
virt:
tunnel: True
For more details on tunnelled data migrations, report to https://libvirt.org/migration.html#transporttunnel
Attempt to execute non-shared storage "all" migration
Parameters: |
|
---|
CLI Example:
salt '*' virt.migrate_non_shared_inc <vm name> <target hypervisor>
A tunnel data migration can be performed by setting this in the configuration:
virt:
tunnel: True
For more details on tunnelled data migrations, report to https://libvirt.org/migration.html#transporttunnel
salt.modules.virt.
network_define
(name, bridge, forward, **kwargs)¶Create libvirt network.
Parameters: |
|
---|
CLI Example:
salt '*' virt.network_define network main bridge openvswitch
New in version 2019.2.0.
salt.modules.virt.
network_info
(name=None, **kwargs)¶Return informations on a virtual network provided its name.
Parameters: |
|
---|
If no name is provided, return the infos for all defined virtual networks.
New in version 2019.2.0.
CLI Example:
salt '*' virt.network_info default
salt.modules.virt.
network_set_autostart
(name, state=u'on', **kwargs)¶Set the autostart flag on a virtual network so that the network will start with the host system on reboot.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt "*" virt.network_set_autostart <pool> <on | off>
salt.modules.virt.
network_start
(name, **kwargs)¶Start a defined virtual network.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.network_start default
salt.modules.virt.
network_stop
(name, **kwargs)¶Stop a defined virtual network.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.network_stop default
salt.modules.virt.
network_undefine
(name, **kwargs)¶Remove a defined virtual network. This does not stop the virtual network.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.network_undefine default
salt.modules.virt.
node_info
(**kwargs)¶Return a dict with information about this node
Parameters: |
|
---|
CLI Example:
salt '*' virt.node_info
salt.modules.virt.
pause
(vm_, **kwargs)¶Pause the named vm
Parameters: |
|
---|
CLI Example:
salt '*' virt.pause <domain>
salt.modules.virt.
pool_build
(name, **kwargs)¶Build a defined libvirt storage pool.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.pool_build default
salt.modules.virt.
pool_define
(name, ptype, target=None, permissions=None, source_devices=None, source_dir=None, source_adapter=None, source_hosts=None, source_auth=None, source_name=None, source_format=None, transient=False, start=True, **kwargs)¶Create libvirt pool.
Parameters: |
|
---|
Permissions definition
The permissions are described by a dictionary containing the following keys:
CLI Example:
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
New in version 2019.2.0.
salt.modules.virt.
pool_delete
(name, fast=True, **kwargs)¶Delete the resources of a defined libvirt storage pool.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.pool_delete default
salt.modules.virt.
pool_info
(name=None, **kwargs)¶Return informations on a storage pool provided its name.
Parameters: |
|
---|
If no name is provided, return the infos for all defined storage pools.
New in version 2019.2.0.
CLI Example:
salt '*' virt.pool_info default
salt.modules.virt.
pool_list_volumes
(name, **kwargs)¶List the volumes contained in a defined libvirt storage pool.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt "*" virt.pool_list_volumes <pool>
salt.modules.virt.
pool_refresh
(name, **kwargs)¶Refresh a defined libvirt storage pool.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.pool_refresh default
salt.modules.virt.
pool_set_autostart
(name, state=u'on', **kwargs)¶Set the autostart flag on a libvirt storage pool so that the storage pool will start with the host system on reboot.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt "*" virt.pool_set_autostart <pool> <on | off>
salt.modules.virt.
pool_start
(name, **kwargs)¶Start a defined libvirt storage pool.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.pool_start default
salt.modules.virt.
pool_stop
(name, **kwargs)¶Stop a defined libvirt storage pool.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
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.
Parameters: |
|
---|
New in version 2019.2.0.
CLI Example:
salt '*' virt.pool_undefine default
salt.modules.virt.
purge
(vm_, dirs=False, removables=None, **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!
Pass removables=False to avoid deleting cdrom and floppy images. To avoid disruption, the default but dangerous value is True. This will be changed to the safer False default value in Sodium.
Parameters: |
|
---|
CLI Example:
salt '*' virt.purge <domain> removables=False
salt.modules.virt.
reboot
(name, **kwargs)¶Reboot a domain via ACPI request
Parameters: |
|
---|
CLI Example:
salt '*' virt.reboot <domain>
salt.modules.virt.
reset
(vm_, **kwargs)¶Reset a VM by emulating the reset button on a physical machine
Parameters: |
|
---|
CLI Example:
salt '*' virt.reset <domain>
salt.modules.virt.
resume
(vm_, **kwargs)¶Resume the named vm
Parameters: |
|
---|
CLI Example:
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.
Parameters: |
|
---|
New in version 2016.3.0.
CLI Example:
salt '*' virt.revert <domain>
salt '*' virt.revert <domain> <snapshot>
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.
Parameters: |
|
---|
CLI Example:
salt '*' virt.seed_non_shared_migrate <disks>
salt.modules.virt.
set_autostart
(vm_, state=u'on', **kwargs)¶Set the autostart flag on a VM so that the VM will start with the host system on reboot.
Parameters: |
|
---|
CLI Example:
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.
Parameters: |
|
---|
CLI Example:
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
Parameters: |
|
---|
CLI Example:
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
Parameters: |
|
---|
CLI Example:
salt '*' virt.shutdown <domain>
salt.modules.virt.
snapshot
(domain, name=None, suffix=None, **kwargs)¶Create a snapshot of a VM.
Parameters: |
|
---|
New in version 2016.3.0.
CLI Example:
salt '*' virt.snapshot <domain>
salt.modules.virt.
start
(name, **kwargs)¶Start a defined domain
Parameters: |
|
---|
CLI Example:
salt '*' virt.start <domain>
salt.modules.virt.
stop
(name, **kwargs)¶Hard power down the virtual machine, this is equivalent to pulling the power.
Parameters: |
|
---|
CLI Example:
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
Parameters: |
|
---|
CLI Example:
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, **kwargs)¶Update the definition of an existing domain.
Parameters: |
|
---|---|
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']
}
|
New in version 2019.2.0.
CLI Example:
salt '*' virt.update domain cpu=2 mem=1024
salt.modules.virt.
virt_type
()¶Returns the virtual machine type as a string
CLI Example:
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:
Parameters: |
|
---|
[
'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.
CLI Example:
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:
Parameters: |
|
---|
[
'your-vm': {
'rd_req' : 0,
'rd_bytes' : 0,
'wr_req' : 0,
'wr_bytes' : 0,
'errs' : 0
},
...
]
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.
CLI Example:
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:
Parameters: |
|
---|
[
'your-vm': {
'cpu': <int>,
'maxMem': <int>,
'mem': <int>,
'state': '<state>',
'cputime' <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.
CLI Example:
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:
Parameters: |
|
---|
[
'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
},
...
]
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.
CLI Example:
salt '*' virt.vm_netstats
salt.modules.virt.
vm_state
(vm_=None, **kwargs)¶Return list of all the vms and their state.
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.
Parameters: |
|
---|
CLI Example:
salt '*' virt.vm_state <domain>
salt.modules.virt.
volume_delete
(pool, volume, **kwargs)¶Delete a libvirt managed volume.
Parameters: |
|
---|
New in version Neon.
CLI Example:
salt "*" virt.volume_delete <pool> <volume>
salt.modules.virt.
volume_infos
(pool, volume, **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.
Parameters: |
|
---|
New in version Neon.
CLI Example:
salt "*" virt.volume_infos <pool> <volume>