Skip to content

Latest commit

 

History

History
121 lines (92 loc) · 6.45 KB

README.md

File metadata and controls

121 lines (92 loc) · 6.45 KB
Raw

Ansible Role jm1.cloudy.libvirt_domain_state

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

Available on Ansible Galaxy in Collection jm1.cloudy.

Requirements

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.

Variables

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

Dependencies

None.

Example Playbook

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.

License

GNU General Public License v3.0 or later

See LICENSE.md to see the full text.

Author

Jakob Meng @jm1 (github, galaxy, web)

Footnotes

  1. Domain state pmsuspended is currently not supported by release version 1.0.0 of module community.libvirt.virt and so this role respectively. ↩