salt.states.virt module¶

Manage virt¶

For the key certificate this state uses the external pillar in the master to call for the generation and signing of certificates for systems running libvirt:

libvirt_keys:
  virt.keys

salt.states.virt.defined(name, cpu=None, mem=None, vm_type=None, disk_profile=None, disks=None, nic_profile=None, interfaces=None, graphics=None, seed=True, install=True, pub_key=None, priv_key=None, connection=None, username=None, password=None, os_type=None, arch=None, boot=None, update=True)¶

Starts an existing guest, or defines and starts a new VM with specified arguments.

New in version 3001.

Parameters

name -- name of the virtual machine to run
cpu -- number of CPUs for the virtual machine to create
mem -- amount of memory in MiB for the new virtual machine
vm_type -- force virtual machine type for the new VM. The default value is taken from the host capabilities. This could be useful for example to use 'qemu' type instead of the 'kvm' one.
disk_profile -- Name of the disk profile to use for the new virtual machine
disks -- List of disk to create for the new virtual machine. See Disks Definitions for more details on the items on this list.
nic_profile -- Name of the network interfaces profile to use for the new virtual machine
interfaces -- List of network interfaces to create for the new virtual machine. See Network Interfaces Definitions for more details on the items on this list.
graphics -- Graphics device to create for the new virtual machine. See Graphics Definition for more details on this dictionary
saltenv -- Fileserver environment (Default: 'base'). See cp module for more details
seed -- True to seed the disk image. Only used when the image parameter is provided. (Default: True)
install -- install salt minion if absent (Default: True)
pub_key -- public key to seed with (Default: None)
priv_key -- public key to seed with (Default: None)
seed_cmd -- Salt command to execute to seed the image. (Default: 'seed.apply')
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults
os_type -- type of virtualization as found in the //os/type element of the libvirt definition. The default value is taken from the host capabilities, with a preference for hvm. Only used when creating a new virtual machine.
arch -- architecture of the virtual machine. The default value is taken from the host capabilities, but x86_64 is prefed over i686. Only used when creating a new virtual machine.
boot --
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 parameters description.

To update any boot parameters, specify the new path for each. To remove any boot parameters, pass a None object, for instance: 'kernel': None.

New in version 3000.
update --
set to False to prevent updating a defined domain. (Default: True)

Deprecated since version 3001.

Example States

Make sure a virtual machine called domain_name is defined:

domain_name:
  virt.defined:
    - cpu: 2
    - mem: 2048
    - disk_profile: prod
    - disks:
      - name: system
        size: 8192
        overlay_image: True
        pool: default
        image: /path/to/image.qcow2
      - name: data
        size: 16834
    - nic_profile: prod
    - interfaces:
      - name: eth0
        mac: 01:23:45:67:89:AB
      - name: eth1
        type: network
        source: admin
    - graphics:
        type: spice
        listen:
            type: address
            address: 192.168.0.125

salt.states.virt.keys(name, basepath='/etc/pki', **kwargs)¶

Manage libvirt keys.

name: The name variable used to track the execution
basepath: Defaults to /etc/pki, this is the root location used for libvirt keys on the hypervisor

The following parameters are optional:

country
The country that the certificate should use. Defaults to US.

New in version 2018.3.0.

state
The state that the certificate should use. Defaults to Utah.

New in version 2018.3.0.

locality
The locality that the certificate should use. Defaults to Salt Lake City.

New in version 2018.3.0.

organization
The organization that the certificate should use. Defaults to Salted.

New in version 2018.3.0.

expiration_days
The number of days that the certificate should be valid for. Defaults to 365 days (1 year)

New in version 2018.3.0.

salt.states.virt.network_defined(name, bridge, forward, vport=None, tag=None, ipv4_config=None, ipv6_config=None, autostart=True, connection=None, username=None, password=None)¶

Defines a new network with specified arguments.

Parameters

bridge -- Bridge name
forward -- Forward mode(bridge, router, nat)
vport -- Virtualport type (Default: 'None')
tag -- Vlan tag (Default: 'None')
ipv4_config -- IPv4 network configuration. See the :py:func`virt.network_define <salt.modules.virt.network_define>` function corresponding parameter documentation for more details on this dictionary. (Default: None).
ipv6_config -- IPv6 network configuration. See the :py:func`virt.network_define <salt.modules.virt.network_define>` function corresponding parameter documentation for more details on this dictionary. (Default: None).
autostart -- Network autostart (default 'True')
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults

New in version 3001.

network_name:
  virt.network_defined

network_name:
  virt.network_defined:
    - bridge: main
    - forward: bridge
    - vport: openvswitch
    - tag: 180
    - autostart: True

network_name:
  virt.network_defined:
    - bridge: natted
    - forward: nat
    - ipv4_config:
        cidr: 192.168.42.0/24
        dhcp_ranges:
          - start: 192.168.42.10
            end: 192.168.42.25
          - start: 192.168.42.100
            end: 192.168.42.150
    - autostart: True

salt.states.virt.network_running(name, bridge, forward, vport=None, tag=None, ipv4_config=None, ipv6_config=None, autostart=True, connection=None, username=None, password=None)¶

Defines and starts a new network with specified arguments.

Parameters

bridge -- Bridge name
forward -- Forward mode(bridge, router, nat)
vport -- Virtualport type (Default: 'None')
tag -- Vlan tag (Default: 'None')
ipv4_config --
IPv4 network configuration. See the :py:func`virt.network_define <salt.modules.virt.network_define>` function corresponding parameter documentation for more details on this dictionary. (Default: None).

New in version 3000.
ipv6_config --
IPv6 network configuration. See the :py:func`virt.network_define <salt.modules.virt.network_define>` function corresponding parameter documentation for more details on this dictionary. (Default: None).

New in version 3000.
autostart -- Network autostart (default 'True')
connection --
libvirt connection URI, overriding defaults

New in version 2019.2.0.
username --
username to connect with, overriding defaults

New in version 2019.2.0.
password --
password to connect with, overriding defaults

New in version 2019.2.0.

network_name:
  virt.network_running

network_name:
  virt.network_running:
    - bridge: main
    - forward: bridge
    - vport: openvswitch
    - tag: 180
    - autostart: True

network_name:
  virt.network_running:
    - bridge: natted
    - forward: nat
    - ipv4_config:
        cidr: 192.168.42.0/24
        dhcp_ranges:
          - start: 192.168.42.10
            end: 192.168.42.25
          - start: 192.168.42.100
            end: 192.168.42.150
    - autostart: True

salt.states.virt.pool_defined(name, ptype=None, target=None, permissions=None, source=None, transient=False, autostart=True, connection=None, username=None, password=None)¶

Defines a new pool with specified arguments.

New in version 3001.

Parameters

ptype -- libvirt pool type
target -- full path to the target device or folder. (Default: None)
permissions -- target permissions. See Permissions definition for more details on this structure.
source -- dictionary containing keys matching the source_* parameters in function salt.modules.virt.pool_define().
transient -- when set to True, the pool will be automatically undefined after being stopped. (Default: False)
autostart -- Whether to start the pool when booting the host. (Default: True)
start -- When True, define and start the pool, otherwise the pool will be left stopped.
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults

pool_name:
  virt.pool_defined:
    - ptype: netfs
    - target: /mnt/cifs
    - permissions:
        - mode: 0770
        - owner: 1000
        - group: 100
    - source:
        dir: samba_share
        hosts:
          - one.example.com
          - two.example.com
        format: cifs
    - autostart: True

salt.states.virt.pool_deleted(name, purge=False, connection=None, username=None, password=None)¶

Deletes a virtual storage pool.

Parameters

name -- the name of the pool to delete.
purge -- if True, the volumes contained in the pool will be deleted as well as the pool itself. Note that these will be lost for ever. If False the pool will simply be undefined. (Default: False)
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults

In order to be purged a storage pool needs to be running to get the list of volumes to delete.

Some libvirt storage drivers may not implement deleting, those actions are implemented on a best effort idea. In any case check the result's comment property to see if any of the action was unsupported.

New in version 3000.

salt.states.virt.pool_running(name, ptype=None, target=None, permissions=None, source=None, transient=False, autostart=True, connection=None, username=None, password=None)¶

Defines and starts a new pool with specified arguments.

New in version 2019.2.0.

Parameters

ptype -- libvirt pool type
target -- full path to the target device or folder. (Default: None)
permissions -- target permissions. See Permissions definition for more details on this structure.
source -- dictionary containing keys matching the source_* parameters in function salt.modules.virt.pool_define().
transient -- when set to True, the pool will be automatically undefined after being stopped. (Default: False)
autostart -- Whether to start the pool when booting the host. (Default: True)
start -- When True, define and start the pool, otherwise the pool will be left stopped.
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults

pool_name:
  virt.pool_running

pool_name:
  virt.pool_running:
    - ptype: netfs
    - target: /mnt/cifs
    - permissions:
        - mode: 0770
        - owner: 1000
        - group: 100
    - source:
        dir: samba_share
        hosts:
          - one.example.com
          - two.example.com
        format: cifs
    - autostart: True

salt.states.virt.powered_off(name, connection=None, username=None, password=None)¶

Stops a VM by power off.

New in version 2016.3.0.

Parameters

connection --
libvirt connection URI, overriding defaults

New in version 2019.2.0.
username --
username to connect with, overriding defaults

New in version 2019.2.0.
password --
password to connect with, overriding defaults

New in version 2019.2.0.

domain_name:
  virt.stopped

salt.states.virt.rebooted(name, connection=None, username=None, password=None)¶

Reboots VMs

New in version 2016.3.0.

Parameters

name --
connection --
libvirt connection URI, overriding defaults

New in version 2019.2.0.
username --
username to connect with, overriding defaults

New in version 2019.2.0.
password --
password to connect with, overriding defaults

New in version 2019.2.0.

salt.states.virt.reverted(name, snapshot=None, cleanup=False)¶

Deprecated since version 2016.3.0.

Reverts to the particular snapshot.

New in version 2016.3.0.

domain_name:
  virt.reverted:
    - cleanup: True

domain_name_1:
  virt.reverted:
    - snapshot: snapshot_name
    - cleanup: False

salt.states.virt.running(name, cpu=None, mem=None, vm_type=None, disk_profile=None, disks=None, nic_profile=None, interfaces=None, graphics=None, seed=True, install=True, pub_key=None, priv_key=None, update=False, connection=None, username=None, password=None, os_type=None, arch=None, boot=None)¶

Starts an existing guest, or defines and starts a new VM with specified arguments.

New in version 2016.3.0.

Parameters

name -- name of the virtual machine to run
cpu -- number of CPUs for the virtual machine to create
mem -- amount of memory in MiB for the new virtual machine
vm_type --
force virtual machine type for the new VM. The default value is taken from the host capabilities. This could be useful for example to use 'qemu' type instead of the 'kvm' one.

New in version 2019.2.0.
disk_profile --
Name of the disk profile to use for the new virtual machine

New in version 2019.2.0.
disks --
List of disk to create for the new virtual machine. See Disks Definitions for more details on the items on this list.

New in version 2019.2.0.
nic_profile --
Name of the network interfaces profile to use for the new virtual machine

New in version 2019.2.0.
interfaces --
List of network interfaces to create for the new virtual machine. See Network Interfaces Definitions for more details on the items on this list.

New in version 2019.2.0.
graphics --
Graphics device to create for the new virtual machine. See Graphics Definition for more details on this dictionary

New in version 2019.2.0.
saltenv --
Fileserver environment (Default: 'base'). See cp module for more details

New in version 2019.2.0.
seed --

True to seed the disk image. Only used when the image parameter is provided.
(Default: True)

New in version 2019.2.0.
install --
install salt minion if absent (Default: True)

New in version 2019.2.0.
pub_key --
public key to seed with (Default: None)

New in version 2019.2.0.
priv_key --
public key to seed with (Default: None)

New in version 2019.2.0.
seed_cmd --
Salt command to execute to seed the image. (Default: 'seed.apply')

New in version 2019.2.0.
update --
set to True to update a defined domain. (Default: False)

New in version 2019.2.0.

Deprecated since version 3001.
connection --
libvirt connection URI, overriding defaults

New in version 2019.2.0.
username --
username to connect with, overriding defaults

New in version 2019.2.0.
password --
password to connect with, overriding defaults

New in version 2019.2.0.
os_type --
type of virtualization as found in the //os/type element of the libvirt definition. The default value is taken from the host capabilities, with a preference for hvm. Only used when creating a new virtual machine.

New in version 3000.
arch --
architecture of the virtual machine. The default value is taken from the host capabilities, but x86_64 is prefed over i686. Only used when creating a new virtual machine.

New in version 3000.
boot --
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 parameters description.

To update any boot parameters, specify the new path for each. To remove any boot parameters, pass a None object, for instance: 'kernel': None.

New in version 3000.

Example States

Make sure an already-defined virtual machine called domain_name is running:

domain_name:
  virt.running

Do the same, but define the virtual machine if needed:

domain_name:
  virt.running:
    - cpu: 2
    - mem: 2048
    - disk_profile: prod
    - disks:
      - name: system
        size: 8192
        overlay_image: True
        pool: default
        image: /path/to/image.qcow2
      - name: data
        size: 16834
    - nic_profile: prod
    - interfaces:
      - name: eth0
        mac: 01:23:45:67:89:AB
      - name: eth1
        type: network
        source: admin
    - graphics:
        type: spice
        listen:
            type: address
            address: 192.168.0.125

salt.states.virt.saved(name, suffix=None)¶

Deprecated since version 2016.3.0: Use snapshot() instead.

Takes a snapshot of a particular VM or by a UNIX-style wildcard.

New in version 2016.3.0.

domain_name:
  virt.saved:
    - suffix: periodic

domain*:
  virt.saved:
    - suffix: periodic

salt.states.virt.snapshot(name, suffix=None, connection=None, username=None, password=None)¶

Takes a snapshot of a particular VM or by a UNIX-style wildcard.

New in version 2016.3.0.

Parameters

connection --
libvirt connection URI, overriding defaults

New in version 2019.2.0.
username --
username to connect with, overriding defaults

New in version 2019.2.0.
password --
password to connect with, overriding defaults

New in version 2019.2.0.

domain_name:
  virt.snapshot:
    - suffix: periodic

domain*:
  virt.snapshot:
    - suffix: periodic

salt.states.virt.stopped(name, connection=None, username=None, password=None)¶

Stops a VM by shutting it down nicely.

New in version 2016.3.0.

Parameters

connection --
libvirt connection URI, overriding defaults

New in version 2019.2.0.
username --
username to connect with, overriding defaults

New in version 2019.2.0.
password --
password to connect with, overriding defaults

New in version 2019.2.0.

domain_name:
  virt.stopped

salt.states.virt.unpowered(name)¶

Deprecated since version 2016.3.0: Use powered_off() instead.

Stops a VM by power off.

New in version 2016.3.0.

domain_name:
  virt.stopped

salt.states.virt.volume_defined(pool, name, size, allocation=0, format=None, type=None, permissions=None, backing_store=None, nocow=False, connection=None, username=None, password=None)¶

Ensure a disk volume is existing.

Parameters

pool -- name of the pool containing the volume
name -- name of the volume
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.
permissions -- Permissions to set on the target folder. This is mostly used for filesystem-based pool types. See Permissions definition for more details on this structure.
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.
connection -- libvirt connection URI, overriding defaults
username -- username to connect with, overriding defaults
password -- password to connect with, overriding defaults

CLI Example:

Volume on ESX:

esx_volume:
  virt.volume_defined:
    - pool: "[local-storage]"
    - name: myvm/myvm.vmdk
    - size: 8192

QCow2 volume with backing file:

myvolume:
  virt.volume_defined:
    - pool: default
    - name: myvm.qcow2
    - format: qcow2
    - size: 8192
    - permissions:
        mode: '0775'
        owner: '123'
        group: '345'
    - backing_store:
        path: /path/to/base.img
        format: raw
    - nocow: True

New in version 3001.

Generated on June 18, 2020 at 04:09:58 UTC.

You are viewing docs for the latest stable release, 3001. Switch to docs for the previous stable release, 3000.3, or to a recent doc build from the master branch.

saltstack.com