Skip to content

Commit 48b2a25

Browse files
author
Will Miller
committed
Update README to reflect new API for multiple VMs
1 parent 3e886a7 commit 48b2a25

File tree

1 file changed

+83
-56
lines changed

1 file changed

+83
-56
lines changed

‎README.md

Lines changed: 83 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Libvirt VM
22
==========
33

4-
This role configures an creates (or destroys) a VM on a KVM hypervisor.
4+
This role configures and creates (or destroys) VMs on a KVM hypervisor.
55

66
Requirements
77
------------
@@ -12,48 +12,60 @@ be preconfigured with libvirt/KVM.
1212
Role Variables
1313
--------------
1414

15-
`libvirt_vm_state`: set to `present` to create or `absent` to destroy the VM.
16-
Defaults to `present`.
17-
18-
`libvirt_vm_name`: the name to assign to the VM.
19-
20-
`libvirt_vm_memory_mb`: the memory to assign to the VM, in megabytes.
21-
22-
`libvirt_vm_vcpus`: the number of VCPU cores to assign to the VM.
23-
24-
`libvirt_vm_engine`: virtualisation engine. If not set, the role will attempt
25-
to auto-detect the optimal engine to use.
26-
27-
`libvirt_vm_emulator`: path to emulator binary. If not set, the role will
28-
attempt to auto-detect the correct emulator to use.
29-
30-
`libvirt_vm_arch`: CPU architecture, default is `x86_64`.
31-
32-
`libvirt_vm_machine`: Virtual machine type. Default is `None` if
33-
`libvirt_vm_engine` is `kvm`, otherwise `pc-1.0`.
34-
35-
`libvirt_vm_cpu_mode`: Virtual machine CPU mode. Default is `host-passthrough`
36-
if `libvirt_vm_engine` is `kvm`, otherwise `host-model`.
37-
38-
`libvirt_vm_volumes`: a list of volumes to attach to the VM. Each volume is
39-
defined with the following dict:
40-
- `name`: Name to associate with the volume being created.
41-
- `device`: `disk`
42-
- `format`: options include `raw`, `qcow2`, `vmdk`. See `man virsh` for the
43-
full range. Default is `qcow2`
44-
- `capacity`: volume capacity (can be suffixed with M,G,T or MB,GB,TB, etc)
45-
- `image`: (optional) a URL to an image with which the volume is initalised.
46-
- `pool`: Name or UUID of the storage pool from which the volume should be
47-
allocated.
48-
49-
`libvirt_vm_interfaces`: a list of network interfaces to attach to the VM.
50-
Each network interface is defined with the following dict:
51-
- `network`: Name of the network to which an interface should be attached.
52-
53-
`libvirt_vm_console_log_path`: Path to console log file. Default is
54-
`/var/log/libvirt/qemu/{{ libvirt_vm_name }}-console.log`.
55-
56-
`libvirt_vm_image_cache_path`: path to cache downloaded images.
15+
- `libvirt_vm_engine`: virtualisation engine. If not set, the role will attempt
16+
to auto-detect the optimal engine to use.
17+
18+
- `libvirt_vm_emulator`: path to emulator binary. If not set, the role will
19+
attempt to auto-detect the correct emulator to use.
20+
21+
- `libvirt_vms`: list of VMs to be created/destroyed. Each one may have the
22+
following attributes:
23+
24+
- `state`: set to `present` to create or `absent` to destroy the VM.
25+
Defaults to `present`.
26+
27+
- `name`: the name to assign to the VM.
28+
29+
- `memory_mb`: the memory to assign to the VM, in megabytes.
30+
31+
- `vcpus`: the number of VCPU cores to assign to the VM.
32+
33+
- `arch`: CPU architecture, default is `x86_64`.
34+
35+
- `machine`: Virtual machine type. Default is `None` if
36+
`engine` is `kvm`, otherwise `pc-1.0`.
37+
38+
- `cpu_mode`: Virtual machine CPU mode. Default is
39+
`host-passthrough` if `engine` is `kvm`, otherwise `host-model`.
40+
41+
- `volumes`: a list of volumes to attach to the VM. Each volume is
42+
defined with the following dict:
43+
- `name`: Name to associate with the volume being created.
44+
- `device`: `disk`
45+
- `format`: options include `raw`, `qcow2`, `vmdk`. See `man virsh` for the
46+
full range. Default is `qcow2`
47+
- `capacity`: volume capacity (can be suffixed with M,G,T or MB,GB,TB, etc)
48+
- `image`: (optional) a URL to an image with which the volume is initalised.
49+
- `pool`: Name or UUID of the storage pool from which the volume should be
50+
allocated.
51+
52+
- `interfaces`: a list of network interfaces to attach to the VM.
53+
Each network interface is defined with the following dict:
54+
- `network`: Name of the network to which an interface should be attached.
55+
56+
- `console_log_path`: Path to console log file. Default is
57+
`/var/log/libvirt/qemu/{{ libvirt_vm_name }}-console.log`.
58+
59+
- `image_cache_path`: path to cache downloaded images.
60+
61+
62+
N.B. the following variables are deprecated: `libvirt_vm_state`,
63+
`libvirt_vm_name`, `libvirt_vm_memory_mb`, `libvirt_vm_vcpus`,
64+
`libvirt_vm_engine`, `libvirt_vm_arch`, `libvirt_vm_machine`,
65+
`libvirt_vm_cpu_mode`, `libvirt_vm_volumes`, `libvirt_vm_interfaces` and
66+
`libvirt_vm_console_log_path`. If the variable `libvirt_vms` is left unset, its
67+
default value will be a singleton list containing a VM specification using
68+
these deprecated variables.
5769

5870
Dependencies
5971
------------
@@ -64,22 +76,37 @@ Example Playbook
6476
----------------
6577

6678
---
67-
- name: Create a VM
79+
- name: Create VMs
6880
hosts: hypervisor
6981
roles:
7082
- role: stackhpc.libvirt-vm
71-
libvirt_vm_state: present
72-
libvirt_vm_name: 'my-vm'
73-
libvirt_vm_memory_mb: 512
74-
libvirt_vm_vcpus: 2
75-
libvirt_vm_volumes:
76-
- name: 'data'
77-
device: 'disk'
78-
format: 'qcow2'
79-
capacity: '400GB'
80-
pool: 'my-pool'
81-
libvirt_vm_interfaces:
82-
- network: 'br-datacentre'
83+
libvirt_vms:
84+
- state: present
85+
name: 'vm1'
86+
memory_mb: 512
87+
vcpus: 2
88+
volumes:
89+
- name: 'data1'
90+
device: 'disk'
91+
format: 'qcow2'
92+
capacity: '400GB'
93+
pool: 'my-pool'
94+
interfaces:
95+
- network: 'br-datacentre'
96+
97+
- state: present
98+
name: 'vm2'
99+
memory_mb: 1024
100+
vcpus: 1
101+
volumes:
102+
- name: 'data2'
103+
device: 'disk'
104+
format: 'qcow2'
105+
capacity: '200GB'
106+
pool: 'my-pool'
107+
interfaces:
108+
- network: 'br-datacentre'
109+
83110

84111
Author Information
85112
------------------

0 commit comments

Comments
 (0)