community.libvirt.virt_install module – Provision new virtual machines using virt-install tool

Note

This module is part of the community.libvirt collection (version 2.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.libvirt. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.libvirt.virt_install.

New in community.libvirt 2.0.0

Synopsis

• Create and install virtual machines using virt-install with a declarative configuration.

Requirements

The below requirements are needed on the host that executes this module.

• libvirt python bindings

• lxml

• python >= 2.6

• virt-install

Parameters

Parameter	Comments
arch string	Request a non-native CPU architecture for the guest virtual machine. If omitted, the host CPU architecture will be used in the guest.
audio dictionary	Configure host audio output for the guest’s sound hardware. The dictionary contains key/value pairs that define individual audio backend properties.
audio_devices list / elements=dictionary	Configure multiple audio backends for the guest.
autostart boolean	Set the autostart flag for a domain. Choices: false true
blkiotune dictionary	Tune block I/O policy for the domain process.
devices list / elements=dictionary	Tune the weights for individual host block device used by the guest. Each dictionary entry contains a property name and its corresponding value.
weight integer	The overall I/O weight of the guest. The value should be in the range [100, 1000]. After kernel 2.6.39, the value could be in the range [10, 1000].
boot string	Set the boot device priority for post-install configuration.
boot_opts dictionary	Additional options for boot configuration. The dictionary contains key/value pairs that define individual boot options.
cdrom string	ISO file or CDROM device to use for VM install media.
channel dictionary	Attach a communication channel device to connect the guest and host machine. The dictionary contains key/value pairs that define individual channel properties.
channel_devices list / elements=dictionary	Configure multiple channel devices for the guest.
clock dictionary	Configure the clock for the guest.
offset string	Set the clock offset, e.g. utc or localtime.
timers list / elements=dictionary	Tweak the guest’s timer settings on the specific hypervisor. Each dictionary entry contains a property name and its corresponding value.
cloud_init dictionary	Pass cloud-init metadata to the VM. A cloud-init NoCloud ISO file is generated, and attached to the VM as a CDROM device.
clouduser_ssh_key string	Specify a public key file to inject into the guest, providing ssh access to the default cloud-init user account.
disable boolean	Disable cloud-init in the VM for subsequent boots. Without this, cloud-init may reset auth on each boot. Choices: false true
meta_data dictionary	Specify a cloud-init meta-data file content.
network_config string	Specify a cloud-init network-config file content.
root_password_file string	A file used to set the VM root password from.
root_password_generate boolean	Generate a new root password for the VM. Choices: false true
root_ssh_key string	Specify a public key file to inject into the guest.
user_data dictionary	Specify a cloud-init user-data file content.
console dictionary	Connect a text console between the guest and host. The dictionary contains key/value pairs that define individual console properties. Common properties include type and target for different console types.
console_devices list / elements=dictionary	Configure multiple console devices for the guest.
container boolean	This guest should be a container type guest. Choices: false true
controller dictionary	Attach a controller device to the guest. The dictionary contains key/value pairs that define individual controller properties. Examples include type=usb,model=none to disable USB, or type=scsi,model=virtio-scsi for VirtIO SCSI.
controller_devices list / elements=dictionary	Configure multiple controller devices for the guest.
cpu dictionary	Configure the CPU model and CPU features exposed to the guest.
cache dictionary	vCPU cache configuration for the guest.
level integer	Specify the level of CPU cache.
mode string	If set to emulate, the hypervisor will provide a fake CPU cache data. If set to passthrough, the host CPU cache data reported by the host CPU will be passed through to the vCPU. If set to disable, the vCPU will report no CPU cache at all. Choices: "emulate" "passthrough" "disable"
features dictionary	Fine-tune features provided by the selected CPU model. The value should be a dictionary where each key is a feature name and the value is a dictionary of options for that feature. An empty object {} for a feature indicates to enable that feature.
policy string	The policy for the CPU feature. If set to force, the vCPU will claim the feature is supported regardless of it being supported by host CPU. If set to require, guest creation will fail unless the feature is supported by the host CPU or the hypervisor is able to emulate it. If set to optional, the feature will be supported by vCPU if and only if it is supported by host CPU. If set to disable, the feature will not be supported by virtual CPU. If set to forbid, guest creation will fail if the feature is supported by host CPU. Choices: "force" "require" "optional" "disable" "forbid"
match string	Specify how strictly the CPU model should be matched. Choices: "exact" "minimum" "strict"
migratable boolean	Specify whether this CPU model is migratable. Choices: false true
model string	A valid CPU model or configuration mode for the guest. The possible values include: host-model, host-passthrough and maximum.
model_opts dictionary	Additional options for CPU model configuration.
fallback string	Specify whether to automatically fall back to the closest model supported by the hypervisor if unable to use the exact CPU model. Choices: "forbid" "allow"
vendor_id string	Set the vendor id seen by the guest. It must be exactly 12 characters long. Typical possible values are AuthenticAMD and GenuineIntel.
numa dictionary	Configure NUMA topology for the guest.
cell_specs list / elements=dictionary	Specify a NUMA cell configuration.
cache_specs list / elements=dictionary	Describe memory side cache for memory proximity domains. Each dictionary entry contains a property name and its corresponding value.
cpus string	Specify the CPU or range of CPUs that are part of this node.
discard boolean	Fine tune the discard feature for given NUMA node. Choices: false true
distances dictionary	Define the distance between NUMA cells.
sibling_specs list / elements=dictionary	Specify the distance value between sibling NUMA cells. Each dictionary entry contains a property name and its corresponding value.
id integer	Specify the NUMA node ID.
mem_access string	Specify the memory access mode for the NUMA node. This is valid only for hugepages-backed memory and nvdimm modules. Choices: "shared" "private"
memory integer	Specify the node memory size with a unit suffix.
interconnects list / elements=dictionary	Describes the normalized memory read/write latency and bandwidth between Initiator Proximity Domains and Target Proximity Domains.
bandwidth_specs list / elements=dictionary	Describe bandwidth between two memory nodes. Each dictionary entry contains a property name and its corresponding value.
latency_specs list / elements=dictionary	Describe latency between two memory nodes. Each dictionary entry contains a property name and its corresponding value.
vendor string	Specify CPU vendor requested by the guest The list of supported vendors can be found in cpu_map/*_vendors.xml.
cputune dictionary	Tune CPU parameters for the guest.
emulator_period integer	Specify the enforcement interval (unit: microseconds) for domain’s emulator threads.
emulator_quota integer	Specify the maximum allowed bandwidth (unit: microseconds) for domain’s emulator threads.
emulatorpin dictionary	Specify which host CPUs the domain emulator will be pinned to.
cpuset string	Specify which physical CPUs to pin to.
emulatorsched dictionary	Specify the scheduler type for emulator thread.
priority integer	For real-time schedulers (fifo, rr), priority must be specified as well (and is ignored for non-real-time ones). The value range for the priority depends on the host kernel (usually 1-99).
scheduler string	The scheduler type. Choices: "batch" "idle" "fifo" "rr"
global_period integer	Specify the enforcement CFS scheduler interval (unit: microseconds) for the whole domain.
global_quota integer	Specify the maximum allowed bandwidth (unit: microseconds) within a period for the whole domain.
iothread_period integer	Specify the enforcement interval (unit: microseconds) for domain’s IOThreads.
iothread_quota integer	Specify the maximum allowed bandwidth (unit: microseconds) for domain’s IOThreads.
iothreadpin_specs list / elements=dictionary	Specify which of host physical CPUs the IOThreads will be pinned to.
cpuset string	Specify which physical CPUs to pin to.
iothread integer	Specify the IOThread ID.
iothreadsched_specs list / elements=dictionary	Specify the scheduler type for particular IOThreads.
iothreads string	Select which IOThreads this setting applies to.
priority integer	For real-time schedulers (fifo, rr), priority must be specified as well (and is ignored for non-real-time ones). The value range for the priority depends on the host kernel (usually 1-99).
scheduler string	The scheduler type. Choices: "batch" "idle" "fifo" "rr"
period integer	Specify the enforcement interval (unit: microseconds). The value should be in range [1000, 1000000]. A period with value 0 means no value.
quota integer	Specify the maximum allowed bandwidth (unit: microseconds). A domain with quota as any negative value indicates that the domain has infinite bandwidth for vCPU threads.
shares integer	Specify the proportional weighted share for the domain.
vcpupin_specs list / elements=dictionary	Specify which of host’s physical CPUs the domain vCPU will be pinned to
cpuset string	A comma-separated list of physical CPU numbers.
vcpu integer	Specify the vCPU ID.
vcpusched_specs list / elements=dictionary	Specify the scheduler type for particular vCPUs.
priority integer	For real-time schedulers (fifo, rr), priority must be specified as well (and is ignored for non-real-time ones). The value range for the priority depends on the host kernel (usually 1-99).
scheduler string	The scheduler type. Choices: "batch" "idle" "fifo" "rr"
vcpus string	Select which vCPUs this setting applies to.
destroy_on_exit boolean	If set to true, the VM will be destroyed when the console window is exited. Choices: false true
disks list / elements=dictionary	Specify the storage devices for the guest.
address dictionary	Specify the controller properties where the disk should be attached. The dictionary contains key/value pairs that define individual properties.
backing_format string	Disk image format of backing_store.
backing_store string	Path to a disk to use as the backing store for the newly created image.
blockio dictionary	Override the default block device properties for the disk. The dictionary contains key/value pairs that define individual properties.
boot dictionary	Specify the boot order for the disk device. The dictionary contains key/value pairs that define individual properties. The per-device boot elements cannot be used together with general boot elements in the OS bootloader section.
bus string	Disk bus type. (e.g. ide, sata, scsi, usb, virtio, xen)
cache string	The cache mode to be used. Choices: "none" "writethrough" "directsync" "unsafe" "writeback"
driver dictionary	Specify the details of the hypervisor disk driver. The dictionary contains key/value pairs that define individual properties.
format string	Disk image format. For file volumes, this can be raw, qcow2, vmdk, etc.
geometry dictionary	Override geometry settings for the disk. The dictionary contains key/value pairs that define individual properties.
iotune dictionary	Specify additional per-device I/O tuning. The dictionary contains key/value pairs that define individual properties.
path string	The path to some storage media to use, existing or not.
pool string	An existing libvirt storage pool name to create new storage on.
rawio boolean	Specify whether the disk needs rawio capability. Choices: false true
readonly boolean	Set drive as readonly Choices: false true
serial string	Serial number of the emulated disk device.
sgio string	Specify whether unprivileged SG_IO commands are filtered for the disk. Only available when the device is ‘lun’. Choices: "filtered" "unfiltered"
shareable boolean	Set drive as shareable Choices: false true
size integer	The size (in GiB) to use if creating new storage.
snapshot string	Indicates the default behavior of the disk during disk snapshots. Choices: "internal" "external" "no"
source dictionary	Specify the details of the disk source. The dictionary contains key/value pairs that define individual properties.
sparse boolean	Whether to skip fully allocating newly created storage. Choices: false true
target dictionary	Specify the details of the target disk device. The dictionary contains key/value pairs that define individual properties.
transient boolean	If true, this indicates that changes to the device contents should be reverted automatically when the guest exits. Choices: false true
transient_opts dictionary	Additional options for transient disk configuration.
share_backing boolean	If true, the transient disk is supposed to be shared between multiple concurrently running VMs. Choices: false true
vol string	An existing libvirt storage volume to use.
events dictionary	Specify events values for the guest.
on_crash string	Action to take when the guest crashes. Choices: "destroy" "restart" "preserve" "rename-restart" "coredump-destroy" "coredump-restart"
on_lockfailure string	Action to take when when a lock manager loses resource locks. Choices: "poweroff" "restart" "pause" "ignore"
on_poweroff string	Action to take when the guest requests a poweroff. Choices: "destroy" "restart" "preserve" "rename-restart"
on_reboot string	Action to take when the guest requests a reboot. Choices: "destroy" "restart" "preserve" "rename-restart"
extra_args string	Additional kernel command line arguments to pass to the installer when performing a guest install with location.
features dictionary	Enable or disable certain machine features. The value should be a dictionary where each key is a feature name and the value is a dictionary of options for that feature. An empty object {} for a feature indicates to turn on that feature with default options. Example: hyperv.spinlocks: {state: off}, pvspinlock: {}
filesystems list / elements=dictionary	Specifies directories on the host to export to the guest.
accessmode string	Specify the security mode for accessing the source. Choices: "passthrough" "mapped" "squash"
address dictionary	Specify the controller properties where the filesystem should be attached. The dictionary contains key/value pairs that define individual properties.
binary dictionary	Tune the options for virtiofsd. The dictionary contains key/value pairs that define individual properties.
dmode string	The creation mode for directories when used with the mapped value for accessmode.
driver dictionary	Specify the details of the hypervisor driver. The dictionary contains key/value pairs that define individual properties.
fmode string	The creation mode for files when used with the mapped value for accessmode.
multidevs string	Specify how to deal with a filesystem export containing more than one device. Choices: "default" "remap" "forbid" "warn"
readonly boolean	Enable exporting filesystem as a readonly mount for guest. Choices: false true
source dictionary	The source directory configuration on the host. The dictionary contains key/value pairs that define individual properties.
space_hard_limit integer	Maximum space available to this guest’s filesystem
space_soft_limit integer	Maximum space available to this guest’s filesystem.
target dictionary	The mount target configuration in the guest. The dictionary contains key/value pairs that define individual properties.
type string	Specify the source type of the filesystem. Choices: "mount" "template" "file" "block" "ram" "bind"
graphics dictionary	Configure the graphical display for the guest virtual machine. The dictionary contains key/value pairs that define individual properties. Common properties include type (e.g. vnc, spice) and listen.
graphics_devices list / elements=dictionary	Configure multiple graphics devices for the guest.
host_devices list / elements=dictionary	Configure multiple host devices for the guest.
hostdev dictionary	Attach a physical host device to the guest. The dictionary contains key/value pairs that define individual host device properties.
hvm boolean	Request the use of full virtualization. Choices: false true
idmap dictionary	Configure the UID or GID mapping for the guest.
gid dictionary	The GID mapping configuration.
count integer	How many groups in container are allowed to map to host’s user.
start integer	First group ID in container.
target integer	The first group ID in container will be mapped to this target user ID in host.
uid dictionary	The UID mapping configuration.
count integer	How many users in container are allowed to map to host’s user.
start integer	First user ID in container.
target integer	The first user ID in container will be mapped to this target user ID in host.
import boolean	Skip the OS installation process, and build a guest around an existing disk image. Choices: false true
initrd_inject string	Add PATH to the root of the initrd fetched with location.
input dictionary	Attach an input device to the guest. Input device types include mouse, tablet, or keyboard. The dictionary contains key/value pairs that define individual input device properties.
input_devices list / elements=dictionary	Configure multiple input devices for the guest.
install dictionary	Additional options for the installation. This option is strictly for VM install operations, essentially configuring the first boot.
bootdev string	Specify the install bootdev to boot for the install phase.
initrd string	Specify a kernel and initrd pair to use as install media.
kernel string	Specify a kernel and initrd pair to use as install media.
kernel_args string	Specify the installation-time kernel arguments.
kernel_args_overwrite boolean	Override the virt-install default kernel arguments rather than appending to them. Choices: false true
no_install boolean	Tell virt-install that there isn’t actually any install happening, and you just want to create the VM. Choices: false true
os string / required	The OS name from libosinfo, e.g. fedora29.
iommu dictionary	Add an IOMMU device to the guest. The dictionary contains key/value pairs that define individual IOMMU properties.
iommu_devices list / elements=dictionary	Configure multiple IOMMU devices for the guest.
iothreads integer	Number of I/O threads to configure for the guest.
iothreads_opts dictionary	Additional options for I/O threads configuration.
defaultiothread dictionary	Provide the capability to define the default event loop within hypervisor.
thread_pool_max integer	Set upper boundary for number of worker threads for given IOThread.
thread_pool_min integer	Set lower boundary for number of worker threads for given IOThread.
iothread_specs list / elements=dictionary	Provide the capability to specifically define the IOThread ID’s for the domain.
id integer	Define the IOThread ID.
thread_pool_max integer	Set upper boundary for number of worker threads for given IOThread.
thread_pool_min integer	Set lower boundary for number of worker threads for given IOThread.
keywrap dictionary	Configure domain keywrap settings used for S390 cryptographic key management operations.
ciphers list / elements=dictionary	Specify the cipher settings for the domain. Each dictionary entry contains a property name and its corresponding value.
launch_security dictionary	Enable launch security for the guest.
cbitpos integer	The C-bit (aka encryption bit) location in guest page table entry.
dh_cert string	The guest owners base64 encoded Diffie-Hellman (DH) key.
policy string	The guest policy which must be maintained by the SEV firmware, e.g. 0x01.
reduced_phys_bits integer	The physical address bit reduction, e.g. 1.
session string	The guest owners base64 encoded session blob defined in the SEV API spec.
type string / required	The type of launch security to enable, e.g. sev.
location string	The installation source, which can be a URL or a directory path containing the OS distribution installation media.
location_opts dictionary	Additional options for the installation source.
initrd string	The initrd path relative to the specified location.
kernel string	The kernel path relative to the specified location.
machine string	The machine type to emulate. This will typically not need to be specified for Xen or KVM.
memballoon dictionary	Attach a virtual memory balloon device to the guest. The dictionary contains key/value pairs that define individual memory balloon properties. Common properties include model (e.g. virtio, xen).
memballoon_devices list / elements=dictionary	Configure multiple memory balloon devices for the guest.
memory integer	Memory to allocate for the guest, in MiB.
memory_opts dictionary	Additional options for memory allocation.
current_memory integer	The actual allocation of memory for the guest, in MiB.
max_memory integer	The run time maximum memory allocation of the guest, in MiB.
max_memory_opts dictionary	Additional options for maximum memory configuration.
slots integer	The number of slots available for adding memory to the guest.
memorybacking dictionary	Specify how virtual memory pages are backed by host pages
access dictionary	Configure memory access permissions.
mode string	The access mode for the memory. Choices: "shared" "private"
allocation dictionary	Configure memory allocation behavior.
mode string	Specify when to allocate the memory by supplying either immediate or ondemand. Choices: "immediate" "ondemand"
threads integer	The number of threads that hypervisor uses to allocate memory.
discard boolean	If set to true, the memory content is discarded just before guest shuts down (or when DIMM module is unplugged). Choices: false true
hugepage_specs list / elements=dictionary	Configure hugepage specifications for memory backing.
nodeset string	Specify the guest’s NUMA nodes to certain hugepage sizes.
page_size integer	Specify the hugepage size with a unit suffix.
hugepages boolean	Use huge pages for memory backing. Choices: false true
locked boolean	Memory pages will be locked in host’s memory and will not be swapped out. Choices: false true
nosharepages boolean	Instructs hypervisor to disable shared pages (memory merge, KSM) for this domain. Choices: false true
memtune dictionary	Tune memory policy for the domain process. The dictionary contains key/value pairs that define individual memtune entries.
metadata dictionary	Specify the metadata for the guest virtual machine. The dictionary contains key/value pairs that define individual metadata entries. e.g. {uuid: 4dea22b3-1d52-d8f3-2516-782e98ab3fa0} Use virt-install --metadata=? to see a list of all available sub options.
name string / required	Name of the new guest virtual machine instance.
networks list / elements=dictionary	Connect the guest to the host network. Empty list [] means no default network interface.
address dictionary	Specify the controller properties where the filesystem should be attached. The dictionary contains key/value pairs that define individual properties.
boot dictionary	Specify the boot order for the network interface. The dictionary contains key/value pairs that define individual properties. The per-device boot elements cannot be used together with general boot elements in the OS bootloader section.
bridge string	Name of the host bridge device to connect to.
driver dictionary	Specify the details of the hypervisor driver. The dictionary contains key/value pairs that define individual properties.
filterref dictionary	Configure network traffic filter rules for the guest. The dictionary contains key/value pairs that define individual properties.
hostdev string	Name of the host device to connect to for type=hostdev. This uses PCI passthrough to directly assign a network device.
mac dictionary	MAC address configuration for the network interface.
address string	Fixed MAC address for the guest interface. If not specified, a suitable address will be randomly generated.
model dictionary	Network device model configuration.
type string	Network device model as seen by the guest. Examples include virtio, e1000, rtl8139.
mtu dictionary	Configure MTU settings for the virtual network link. - The dictionary contains key/value pairs that define individual properties.
network string	Name of the libvirt virtual network to connect to.
rom dictionary	Specify the interface ROM BIOS configuration The dictionary contains key/value pairs that define individual properties.
source dictionary	Specify the details of the source network interface. The dictionary contains key/value pairs that define individual properties.
state dictionary	Set state of the virtual network link The dictionary contains key/value pairs that define individual properties.
target dictionary	Specify the details of the target network device. The dictionary contains key/value pairs that define individual properties.
trust_guest_rx_filters boolean	When set to true, enables the host to trust and accept MAC address changes and receive filter modifications reported by the guest VM. Choices: false true
type string	The type of network interface. direct provides direct attachment to host network interface using macvtap. If omitted, the type of network interface is determined by other options. Choices: "direct"
virtualport dictionary	Configure virtual port settings for the network interface. The dictionary contains key/value pairs that define individual properties. Common properties include type (e.g. 802.1Qbg, 802.1Qbh, openvswitch, midonet) and parameters containing type-specific settings.
noreboot boolean	If set to true, the VM will not automatically reboot after the install has completed. Choices: false true
numatune dictionary	Tune NUMA policy for the domain process.
memnode_specs list / elements=dictionary	Specify memory allocation policies per each guest NUMA node.
cellid integer	Specify the NUMA node ID.
mode string	Can be one of interleave, preferred, or strict (the default) Choices: "interleave" "preferred" "strict"
nodeset string	Specifies the NUMA nodes to allocate memory from.
memory dictionary	Specifies how to allocate memory for the domain process on a NUMA host.
mode string	Can be one of interleave, preferred, or strict (the default) Choices: "interleave" "preferred" "strict"
nodeset string	Specifies the NUMA nodes to allocate memory from.
placement string	Indicate the memory placement mode for domain process. Choices: "static" "auto"
osinfo dictionary	Optimize the guest configuration for a specific operating system.
detect boolean	Whether virt-install should attempt OS detection from the specified install media. Choices: false true
id string	The full URL style libosinfo ID.
name aliases: short_id string	The OS name from libosinfo. (e.g. fedora32, win10)
require boolean	Whether virt-install should fail if OS detection fails. Choices: false true
panic dictionary	Attach a panic notifier device to the guest. The dictionary contains key/value pairs that define individual panic device properties.
panic_devices list / elements=dictionary	Configure multiple panic devices for the guest.
parallel dictionary	Attach a parallel device to the guest. The dictionary contains key/value pairs that define individual parallel device properties.
parallel_devices list / elements=dictionary	Configure multiple parallel devices for the guest.
paravirt boolean	This guest should be a paravirtualized guest. Choices: false true
pm dictionary	Configure the power management for the guest.
suspend_to_disk dictionary	Configure BIOS support for S4 (suspend-to-disk) ACPI sleep states.
enabled boolean	Enable or disable this sleep state. Choices: false true
suspend_to_mem dictionary	Configure BIOS support for S3 (suspend-to-mem) ACPI sleep states.
enabled boolean	Enable or disable this sleep state. Choices: false true
pxe boolean	Install the guest from PXE. Choices: false true
qemu_commandline string	Pass options directly to the qemu emulator. Only works for the libvirt qemu driver.
recreate boolean	Use with present to force the re-creation of an existing VM. Choices: false ← (default) true
redirdev dictionary	Add a redirected device for USB or other device redirection. The dictionary contains key/value pairs that define individual redirection properties. Common properties include bus=usb, type=tcp or type=spicevmc.
redirected_devices list / elements=dictionary	Configure multiple redirected devices for the guest.
resource dictionary	Specify resource partitioning for the guest. The dictionary contains key/value pairs that define individual resource entries. Use virt-install --resource=? to see a list of all available sub options.
rng dictionary	Configure a virtual random number generator (RNG) device. The dictionary contains key/value pairs that define individual RNG properties.
rng_devices list / elements=dictionary	Configure multiple RNG devices for the guest.
security dictionary	Configure domain seclabel domain settings. The dictionary contains key/value pairs that define individual security entries.
serial dictionary	Attach a serial device to the guest with various redirection options. The dictionary contains key/value pairs that define individual serial device properties.
serial_devices list / elements=dictionary	Configure multiple serial devices for the guest.
shmem dictionary	Attach a shared memory device to the guest. The dictionary contains key/value pairs that define individual shared memory properties.
shmem_devices list / elements=dictionary	Configure multiple shared memory devices for the guest.
smartcard dictionary	Configure a virtual smartcard device. The dictionary contains key/value pairs that define individual smartcard properties.
smartcard_devices list / elements=dictionary	Configure multiple smartcard devices for the guest.
sound dictionary	Attach a virtual audio device to the guest. The dictionary contains key/value pairs that define individual sound device properties. Common properties include model (e.g. ich6, ich9, ac97).
sound_devices list / elements=dictionary	Configure multiple sound devices for the guest.
state string	If set to present, create the VM if it does not exist. If set to absent, remove the VM if it exists. Choices: "present" ← (default) "absent"
sysinfo dictionary	Configure sysinfo/SMBIOS values exposed to the VM OS. The dictionary contains key/value pairs that define individual sysinfo entries. Use virt-install --sysinfo=? to see a list of all available sub options.
tpm dictionary	Configure a virtual TPM (Trusted Platform Module) device. The dictionary contains key/value pairs that define individual TPM properties.
tpm_devices list / elements=dictionary	Configure multiple TPM devices for the guest.
transient boolean	If set to true, libvirt forgets the XML configuration of the VM after shutdown or host restart. Choices: false true
unattended dictionary	Perform an unattended install using libosinfo’s install script support.
admin_password_file string	A file used to set the VM OS admin/root password from.
product_key string	Set a Windows product key.
profile string	Choose which libosinfo unattended profile to use.
user_login string	The user login name to be used in the VM.
user_password_file string	A file used to set the VM user password.
uri string	Libvirt connection uri. Default: "qemu:///system"
vcpus integer	Number of virtual cpus to configure for the guest.
vcpus_opts dictionary	Additional options for virtual CPU configuration.
clusters integer	number of clusters per die
cores integer	Number of cores per cluster
cpuset string	A comma-separated list of physical CPU numbers that domain process and virtual CPUs can be pinned to by default.
current integer	Specify whether fewer than the maximum number of virtual CPUs should be enabled.
dies integer	Number of dies per socket
maxvcpus integer	If specified, the guest will be able to hotplug up to MAX vcpus while the guest is running.
placement string	Indicate the CPU placement mode for domain process Choices: "static" "auto"
sockets integer	Total number of CPU sockets
threads integer	Number of threads per core
vcpu_specs list / elements=dictionary	Configure individual vCPU properties. Each dictionary entry contains a property name and its corresponding value.
video dictionary	Specify what video device model will be attached to the guest. The dictionary contains key/value pairs that define individual video device properties.
video_devices list / elements=dictionary	Configure multiple video devices for the guest.
virt_type string	The hypervisor used to create the VM guest. Example choices are kvm, qemu, or xen.
vsock dictionary	Configure a vsock host/guest interface. The dictionary contains key/value pairs that define individual vsock properties.
vsock_devices list / elements=dictionary	Configure multiple vsock devices for the guest.
watchdog dictionary	Attach a virtual hardware watchdog device to the guest. The dictionary contains key/value pairs that define individual watchdog properties.
watchdog_devices list / elements=dictionary	Configure multiple watchdog devices for the guest.

Attributes

Attribute	Support	Description
check_mode	Support: full	Supports check_mode.

Notes

Note

• The virt-install command is provided by different packages on different distributions.

• On Debian/Ubuntu, install the virtinst package.

• On RHEL/CentOS/Fedora and openSUSE, install the virt-install package.

See Also

See also

virt-install Man Page

Ubuntu manpage of virt-install tool.

Examples

# Basic VM creation with Fedora installation
- name: Create a basic Fedora VM
  community.libvirt.virt_install:
    name: my-fedora-vm
    memory: 2048
    vcpus: 2
    disks:
      - size: 20
    osinfo:
      name: fedora39
    location: https://download.fedoraproject.org/pub/fedora/linux/releases/39/Server/x86_64/
    graphics:
      type: spice
    networks:
      - network: default

# Windows 10 VM with CDROM installation
- name: Create Windows 10 VM
  community.libvirt.virt_install:
    name: my-win10-vm
    memory: 4096
    vcpus: 4
    disks:
      - size: 40
        format: qcow2
    osinfo:
      name: win10
    cdrom: /path/to/my/win10.iso
    graphics:
      type: vnc
      password: mypassword
    networks:
      - network: default
        model:
          type: e1000

# Import existing disk image
- name: Import existing Debian VM
  community.libvirt.virt_install:
    name: my-debian-vm
    memory: 1024
    vcpus: 2
    disks:
      - path: /home/user/VMs/my-debian9.img
    osinfo:
      name: debian9
    import: true
    networks:
      - bridge: br0

# CentOS installation with custom storage and network configuration
- name: Create CentOS VM with custom configuration
  community.libvirt.virt_install:
    name: centos-server
    memory: 8192
    vcpus: 8
    disks:
      - pool: default
        size: 50
        format: qcow2
        cache: writeback
      - pool: default
        size: 100
        format: qcow2
        bus: virtio
    osinfo:
      name: centos7.0
    location: http://mirror.centos.org/centos-7/7/os/x86_64/
    extra_args: "ks=http://myserver/centos7.ks"
    graphics:
      type: vnc
      listen: 0.0.0.0
      port: 5901
    networks:
      - bridge: br0
        model:
          type: virtio
      - network: isolated-net

# Ubuntu server with unattended installation
- name: Create Ubuntu server with unattended install
  community.libvirt.virt_install:
    name: ubuntu-server
    memory: 2048
    vcpus: 2
    disks:
      - size: 25
    osinfo:
      name: ubuntu20.04
    location: http://archive.ubuntu.com/ubuntu/dists/focal/main/installer-amd64/
    unattended:
      profile: jeos
      admin_password_file: /tmp/root_password
      user_login: ansible
      user_password_file: /tmp/user_password
    networks:
      - network: default

# ARM VM with custom kernel
- name: Create ARM VM with custom kernel
  community.libvirt.virt_install:
    name: arm-test-vm
    memory: 1024
    vcpus: 2
    arch: armv7l
    machine: vexpress-a9
    disks:
      - path: /home/user/VMs/myarmdisk.img
    boot:
      kernel: /tmp/my-arm-kernel
      initrd: /tmp/my-arm-initrd
      dtb: /tmp/my-arm-dtb
      kernel_args: "console=ttyAMA0 rw root=/dev/mmcblk0p3"
    graphics:
      type: none
    networks:
      - network: default

# VM with SEV launch security (AMD)
- name: Create SEV-enabled VM
  community.libvirt.virt_install:
    name: sev-vm
    memory: 4096
    memtune:
      hard_limit: 4563402
    vcpus: 4
    machine: q35
    boot: uefi
    disks:
      - size: 15
        bus: scsi
    controller_devices:
      - type: scsi
        model: virtio-scsi
        driver:
          iommu: "on"
      - type: virtio-serial
        driver:
          iommu: "on"
    networks:
      - network: default
        model:
          type: virtio
        driver:
          iommu: "on"
    rng:
      backend:
        type: random
        source: /dev/random
      driver:
        iommu: "on"
    memballoon:
      model: virtio
      driver:
        iommu: "on"
    launch_security:
      type: sev
      policy: "0x01"
    osinfo:
      name: fedora39
    import: true


# Recreate existing VM
- name: Recreate existing VM with new configuration
  community.libvirt.virt_install:
    name: existing-vm
    state: present
    recreate: true
    memory: 4096
    vcpus: 4
    disks:
      - size: 40
    osinfo:
      name: fedora39
    cdrom: /path/to/fedora39.iso
    networks:
      - network: default

# Remove VM
- name: Remove VM
  community.libvirt.virt_install:
    name: unwanted-vm
    state: absent

Authors

• Joey Zhang (@thinkdoggie)

Collection links

• Issue Tracker
• Repository (Sources)