This role helps with managing the state of libvirt domains aka virtual machines
from Ansible variables. It allows to start, pause, suspend and shutdown a domain with variable libvirt_domain_state
.
For example, to shutdown domain debian.home.arpa
which was launched in the introduction of role
jm1.cloudy.libvirt_domain
, define libvirt_domain_state
in group_vars
or
host_vars
as such:
# Possible domain states: [running, paused, pmsuspended, shutoff]
# Ref.: https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainState
libvirt_domain_state: shutoff
When this role is executed, it will first query the local libvirt daemon (run by current Ansible user on the Ansible
controller) for the current state of the libvirt domain named by libvirt_domain
. Next it will
perform domain commands such as starting or pausing to bring the domain into the desired state.
If libvirt_domain_state
is set to shutoff
, then this role will send a shutdown signal to the domain, then it will
wait for the domain to shutdown and if it is still running after 900 seconds it will be destroyed (killed). All
operations will be performed with module community.libvirt.virt
from collection
community.libvirt
.
If variable state
is absent
, then this role does nothing.
Tested OS images
- Cloud image (
amd64
) of Debian 10 (Buster) - Cloud image (
amd64
) of Debian 11 (Bullseye) - Cloud image (
amd64
) of Debian 12 (Bookworm) - Cloud image (
amd64
) of Debian 13 (Trixie) - Cloud image (
amd64
) of CentOS 7 (Core) - Cloud image (
amd64
) of CentOS 8 (Stream) - Cloud image (
amd64
) of CentOS 9 (Stream) - Cloud image (
amd64
) of Fedora Cloud Base 40 - Cloud image (
amd64
) of Ubuntu 18.04 LTS (Bionic Beaver) - Cloud image (
amd64
) of Ubuntu 20.04 LTS (Focal Fossa) - Cloud image (
amd64
) of Ubuntu 22.04 LTS (Jammy Jellyfish) - Cloud image (
amd64
) of Ubuntu 24.04 LTS (Noble Numbat)
Available on Ansible Galaxy in Collection jm1.cloudy.
This role uses module(s) from collections community.libvirt
and [jm1.libvirt
][
galaxy-jm1-libvirt]. To install these collections you may follow the steps described in README.md
using the provided requirements.yml
.
Name | Default value | Required | Description |
---|---|---|---|
libvirt_domain |
{{ inventory_hostname }} |
false | Name of the domain |
libvirt_domain_state |
running |
false | Possible domain states: [running, paused, pmsuspended, shutoff] 1 |
libvirt_uri |
qemu:///system |
false | libvirt connection uri |
state |
present |
false | Should the libvirt domain be present or absent |
None.
First, define and launch libvirt domain debian.home.arpa
as described in the introduction of role
jm1.cloudy.libvirt_domain
.
- hosts: all
# do not become root because connection is local
connection: local # Assign libvirt_uri to setup a connection to the libvirt host
vars:
# Variables are listed here for convenience and illustration.
# In a production setup, variables would be defined e.g. in
# group_vars and/or host_vars of an Ansible inventory.
# Ref.:
# https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html
# https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
# Possible domain states: [running, paused, pmsuspended, shutoff]
# Ref.: https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainState
libvirt_domain_state: shutoff
roles:
- name: Manage libvirt domain state
role: jm1.cloudy.libvirt_domain_state
tags: ["jm1.cloudy.libvirt_domain_state"]
For a complete example on how to use this role, refer to hosts lvrt-lcl-session-srv-*
from the provided examples
inventory. The top-level README.md
describes how these hosts can be
provisioned with playbook playbooks/site.yml
.
For instructions on how to run Ansible playbooks have look at Ansible's Getting Started Guide.
GNU General Public License v3.0 or later
See LICENSE.md to see the full text.
Jakob Meng @jm1 (github, galaxy, web)
Footnotes
-
Domain state
pmsuspended
is currently not supported by release version1.0.0
of modulecommunity.libvirt.virt
and so this role respectively. ↩