community.libvirt.virt_cloud_instance module – Provision new virtual machines from cloud images via libvirt

Note

This module is part of the community.libvirt collection (version 2.1.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_cloud_instance.

New in community.libvirt 2.1.0

Synopsis

• Create and customize virtual machines using pre-built cloud images with cloud-init support.

• Cloud images can be retrieved from local files and remote URLs.

• Supports automatic conversion and resizing of disk images.

Requirements

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

• libvirt python bindings

• lxml

• python >= 2.6

• qemu-img

• 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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
audio_devices list / elements=dictionary	Configure multiple audio backends for the guest.
autostart boolean	Set the autostart flag for a domain. Choices: false true
base_image string / required	Path or URL to the cloud image. Can be a local file path or a remote URL (http, https, ftp). The image will be automatically downloaded if a URL is provided.
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.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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 any	Specify a cloud-init meta-data file content. Can be provided as a YAML string (e.g., using the ‘|’ operator in Ansible) or as a dictionary structure. Note: String values are preferred as dictionary values cannot ensure order preservation.
network_config any	Specify a cloud-init network-config file content. Can be provided as a YAML string (e.g., using the ‘|’ operator in Ansible) or as a dictionary structure. Note: String values are preferred as dictionary values cannot ensure order preservation.
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 any	Specify a cloud-init user-data file content. Can be provided as a YAML string (e.g., using the ‘|’ operator in Ansible) or as a dictionary structure. Note: String values are preferred as dictionary values cannot ensure order preservation.
cloud_init_auto_reboot boolean	When wait_for_cloud_init_reboot=true, automatically inject a reboot instruction into the cloud-init user-data. If set to false, the reboot instructions should be included in the cloud-init user-data manually. Only applies when wait_for_cloud_init_reboot=true. Choices: false true ← (default)
cloud_init_reboot_timeout integer	Maximum time in seconds to wait for the cloud-init reboot cycle to complete. The timeout is checked at minute intervals, so the actual timeout may be up to 60 seconds longer. Only applies when wait_for_cloud_init_reboot=true. If the timeout is exceeded, the task will fail. Default: 600
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
console_devices list / elements=dictionary	Configure multiple console devices for the guest.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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.
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"
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"
force_disk boolean	Force deletion and recreation of existing disk files. When set to true, any existing disk files specified in disks will be removed and recreated. When set to false, the module will fail if any disk file already exists. This parameter only affects disk file creation, not VM definition. Use with recreate=true to recreate both the VM and its disk files. Choices: false ← (default) true
force_pull boolean	Force pull of the cloud image even if it already exists in the cache. Only used when base_image is a URL. Useful for updating cached images to their latest versions. Choices: false ← (default) true
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
hvm boolean	Request the use of full virtualization. Choices: false true
image_cache_dir path	Directory where downloaded cloud images will be cached. Only used when base_image is a URL. If not specified, the base image will be downloaded to the temporary directory and not be cached.
image_checksum string	If specified, the digest of the downloaded image will be calculated to verify the integrity of the downloaded image. Format: <algorithm>:<checksum|url>, e.g. sha256:D98291AC[…]B6DC7B97, sha256:http://example.com/path/sha256sum.txt. Only used when base_image is a URL. If you worry about portability, only the sha1 algorithm is available on all platforms and python versions.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
input_devices list / elements=dictionary	Configure multiple input devices for the guest.
iommu dictionary	Add an IOMMU device to the guest. The dictionary contains key/value pairs that define individual IOMMU properties. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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.
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). You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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
source dictionary added in community.libvirt 2.1.0	Configure the source of memory backing.
type string	The type of memory backing source. Choices: "anonymous" "file" "memfd"
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 direct attached macvtap interface. The dictionary contains key/value pairs that define individual properties. You can use the special attribute value to specify a primary value that appears before other properties in the command line. Example: source={value: bond0, mode: bridge}
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.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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). You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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. 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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
tpm_devices list / elements=dictionary	Configure multiple TPM devices for the guest.
uri string	Libvirt connection uri. Default: "qemu:///system"
url_password string	The password for HTTP basic authentication. Only used when base_image is a URL.
url_timeout integer	The timeout in seconds for downloading the base image from a URL. Only used when base_image is a URL. Default: 60
url_username string	The username for HTTP basic authentication. Only used when base_image is a URL.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
vsock_devices list / elements=dictionary	Configure multiple vsock devices for the guest.
wait_for_cloud_init_reboot boolean	If set to true, wait for cloud-init to trigger a reboot and for the VM to come back online. This requires that your cloud-init user-data includes a reboot action, or cloud_init_auto_reboot=true. Only applicable when cloud_init configuration is provided. Choices: false true ← (default)
watchdog dictionary	Attach a virtual hardware watchdog device to the guest. The dictionary contains key/value pairs that define individual watchdog properties. You can use the special attribute value to specify a primary value that appears before other properties in the command line.
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.

• When wait_for_cloud_init_reboot=true, ensure your cloud-init user-data includes appropriate reboot commands or set cloud_init_auto_reboot=true.

• The cloud_init_auto_reboot parameter automatically injects power_state.mode=reboot at the end of user-data when enabled.

• The module waits through the complete cloud-init process including any reboots specified in the user-data.

• Use cloud_init_reboot_timeout to control the maximum wait time for complex cloud-init configurations.

See Also

See also

community.libvirt.virt_install

More general VM installation module.

virt-install Man Page

Ubuntu manpage of virt-install tool.

Examples

# Basic example: Create a VM from a local cloud image
- name: Create Ubuntu VM from local cloud image
  community.libvirt.virt_cloud_instance:
    name: ubuntu-vm-01
    base_image: /srv/images/ubuntu-22.04-server-cloudimg-amd64.img
    disks:
      - path: /var/lib/libvirt/images/ubuntu-vm-01.qcow2
        size: 20
        format: qcow2
    memory: 2048
    vcpus: 2
    networks:
      - network: default

# Download cloud image from URL with checksum validation
- name: Create VM from remote Ubuntu cloud image
  community.libvirt.virt_cloud_instance:
    name: ubuntu-vm-02
    base_image: https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img
    image_cache_dir: /srv/cloud-images
    image_checksum: sha256:https://cloud-images.ubuntu.com/releases/22.04/release/SHA256SUMS
    disks:
      - path: /var/lib/libvirt/images/ubuntu-vm-02.qcow2
        size: 30
        format: qcow2
    memory: 4096
    vcpus: 4
    networks:
      - network: default

# Advanced example with cloud-init configuration
- name: Create VM with cloud-init user data
  community.libvirt.virt_cloud_instance:
    name: web-server-01
    base_image: /srv/images/ubuntu-22.04-server-cloudimg-amd64.img
    disks:
      - path: /var/lib/libvirt/images/web-server-01.qcow2
        size: 50
        format: qcow2
    memory: 8192
    vcpus: 4
    networks:
      - network: default
        mac: 52:54:00:12:34:56
    cloud_init:
      user_data: |
        #cloud-config
        users:
          - name: ansible
            groups: sudo
            shell: /bin/bash
            sudo: 'ALL=(ALL) NOPASSWD:ALL'
            ssh_authorized_keys:
              - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... user@host
        packages:
          - nginx
          - htop
          - vim
        runcmd:
          - systemctl enable nginx
          - systemctl start nginx
      meta_data:
        instance-id: web-server-01
        local-hostname: web-server-01

# Force overwrite existing disk files
- name: Create VM and force overwrite existing disk
  community.libvirt.virt_cloud_instance:
    name: test-vm
    base_image: /srv/images/ubuntu-22.04-server-cloudimg-amd64.img
    force_disk: true
    disks:
      - path: /var/lib/libvirt/images/test-vm.qcow2
        size: 20
        format: qcow2
    memory: 2048
    vcpus: 2
    networks:
      - network: default

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
base_image_path string	Path to the base cloud image file. This is the local path where the image was downloaded to (if URL was provided) or the original local path. Returned: success Sample: "/srv/cloud-images/ubuntu-20.04-server-cloudimg-amd64.img"

Authors

• Joey Zhang (@thinkdoggie)

Collection links

• Issue Tracker
• Repository (Sources)