Ansible Collection for using libvirt

This repo hosts the Ansible collection jm1.libvirt.

The collection includes a variety of Ansible content to help automate the provisioning and maintenance of libvirt clusters.

It is inspired by the Ansible OpenStack collection. For example, jm1.libvirt.domain and jm1.libvirt.volume_cloudinit resemble openstack.cloud.server to create virtual machines with libvirt and cloud-init:

- hosts: all
  tasks:
    - name: Install software required by jm1.libvirt's roles and modules
      import_role:
        name: jm1.libvirt.setup

    - name: Fetch cloud image, create storage volumes and define domain (virtual machine)
      import_role:
        name: jm1.libvirt.server
      vars:
        userdata: |
            #cloud-config
            hostname: {{ inventory_hostname }}

In comparison to the community.libvirt.virt_* modules of the community.libvirt collection, all jm1.libvirt.* modules are idempotent, that is they can be applied multiple times without changing the result beyond the initial application. To create libvirt domains (virtual machines), storage pools or volumes you write virsh-like options in Ansible-idiomatic YAML lists. For example:

- jm1.libvirt.pool
    name: default
    hardware:
        # Commandline arguments of 'virsh pool-define-as' as key-value pairs without
        # the two leading dashs and all other dashs replaced by underscores.
        type: dir
        target: '/var/lib/libvirt/images'

No need to write XML documents as with e.g. community.libvirt.virt or community.libvirt.virt_pool.

Included content

Click on the name of a module or role to view that content's documentation:

Modules:
- domain
- net_xml
- pool
- pool_xml
- volume
- volume_cloudinit
- volume_import
- volume_snapshot
Module Utils:
- libvirt
Roles:
- server
- setup

Requirements and Installation

Installing necessary software

Content in this collection requires additional roles and collections, e.g. to collect operating system facts. You can fetch them from Ansible Galaxy using the provided requirements.yml:

ansible-galaxy collection install --requirements-file requirements.yml
ansible-galaxy role install --role-file requirements.yml
# or
make install-requirements

Content in this collection requires additional tools and libraries, e.g. to interact with libvirt's APIs. You can use role jm1.libvirt.setup to install necessary software packages:

- hosts: all
  roles:
    - jm1.libvirt.setup

Or to install these packages locally:

sudo -s

ansible-console localhost << EOF
gather_facts
include_role name=jm1.libvirt.setup
EOF

The exact requirements for every module and role are listed in the corresponding documentation. See the module documentations for the minimal version supported for each module.

Installing the Collection from Ansible Galaxy

Before using the jm1.libvirt collection, you need to install it with the Ansible Galaxy CLI:

ansible-galaxy collection install jm1.libvirt

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: jm1.libvirt
    version: 2024.5.30

Usage and Playbooks

You can either call modules by their Fully Qualified Collection Name (FQCN), like jm1.libvirt.domain, or you can call modules by their short name if you list the jm1.libvirt collection in the playbook's collections, like so:

---
- name: Using jm1.libvirt collection
  hosts: localhost

  collections:
    - jm1.libvirt

  tasks:
    - name: Satisfy software requirements
      import_role:
        name: setup

    - name: Create a new libvirt domain with cloud-init
      domain:
        name: 'vm.inf.h-brs.de'

For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README.

See Ansible Using collections for more details.

Contributing

There are many ways in which you can participate in the project, for example:

Submit bugs and feature requests, and help us verify them
Submit pull requests for new modules, roles and other content

We're following the general Ansible contributor guidelines; see Ansible Community Guide.

If you want to develop new content for this collection or improve what is already here, the easiest way to work on the collection is to clone this repository (or a fork of it) into one of the configured ANSIBLE_COLLECTIONS_PATHS and work on it there:

Create a directory ansible_collections/jm1;
In there, checkout this repository (or a fork) as libvirt;
Add the directory containing ansible_collections to your ANSIBLE_COLLECTIONS_PATHS.

Helpful tools for developing collections are ansible, ansible-doc, ansible-galaxy, ansible-lint, flake8, make and yamllint.

OS	Install Instructions
Debian 10 (Buster)	Enable Backports. `apt install ansible ansible-doc ansible-lint flake8 make yamllint`
Debian 11 (Bullseye)	`apt install ansible ansible-lint flake8 make yamllint`
Debian 12 (Bookworm)	`apt install ansible ansible-lint flake8 make yamllint`
Debian 13 (Trixie)	`apt install ansible ansible-lint flake8 make yamllint`
Fedora	`dnf install ansible python3-flake8 make yamllint`
Red Hat Enterprise Linux (RHEL) 7 / CentOS 7	Enable EPEL. `yum install ansible ansible-lint ansible-doc python-flake8 make yamllint`
Red Hat Enterprise Linux (RHEL) 8 / CentOS 8	Enable EPEL. `yum install ansible python3-flake8 make yamllint`
Red Hat Enterprise Linux (RHEL) 9 / CentOS 9	Enable EPEL. `yum install ansible python3-flake8 make yamllint`
Ubuntu 18.04 LTS (Bionic Beaver)	Enable Launchpad PPA Ansible by Ansible, Inc.. `apt install ansible ansible-doc ansible-lint flake8 make yamllint`
Ubuntu 20.04 LTS (Focal Fossa)	Enable Launchpad PPA Ansible by Ansible, Inc.. `apt install ansible ansible-doc ansible-lint flake8 make yamllint`
Ubuntu 22.04 LTS (Jammy Jellyfish)	`apt install ansible ansible-lint flake8 make yamllint`
Ubuntu 24.04 LTS (Noble Numbat)	`apt install ansible ansible-lint flake8 make yamllint`

Have a look at the included Makefile for several frequently used commands, to e.g. build and lint a collection.

More Information

License

GNU General Public License v3.0 or later

See LICENSE.md to see the full text.

Author

Jakob Meng @jm1 (github, galaxy, web)

ji-podhead/ansible-collection-jm1-libvirt