Installation

pip install molecule-libvirt-ng

You also need libvirt-python which requires system libvirt headers:

# Debian/Ubuntu
sudo apt install libvirt-dev pkg-config python3-dev

# RHEL/Fedora
sudo dnf install libvirt-devel pkg-config python3-devel

pip install libvirt-python

Install the required Ansible collections:

ansible-galaxy collection install -r test_requirements.yml

Example

Create a molecule/default/molecule.yml in your Ansible role:

---
driver:
  name: libvirt

platforms:
  - name: debian12-test
    image_url: "https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2"
    memory_size: 2
    vcpu: 2
    disk_size: "10G"
    qemu_user: "qemu"

provisioner:
  name: ansible

verifier:
  name: ansible

Then run:

molecule test

Required

image_url

URL to a cloud image (qcow2 format). Defaults to Debian 12 genericcloud.

Optional

memory_size

RAM in GB. Default: 1.

vcpu

Number of virtual CPUs. Default: 1.

disk_size

Disk size (qemu-img format). Default: 15G.

ssh_port

SSH port on the guest. Default: 22.

cpu_model

CPU model requested by the guest. Default: qemu64.

arch

CPU architecture. Default: x86_64.

timezone

VM timezone. Default: America/Toronto.

qemu_user

QEMU process user for filesystem ACLs. Varies by distro:

• RHEL/Fedora: qemu (default)

• Debian/Ubuntu: libvirt-qemu

• NixOS: root

image_volume

Partition to expand with virt-resize. Default: /dev/sda1.

network_name

Use an existing libvirt network instead of creating a molecule-managed one.

bridge_name

Use an existing bridge on a remote host. Makes the VM reachable via ARP.

libvirt_host and libvirt_user

Provision VMs on a remote libvirt host via qemu+ssh://.

Network Parameters

These apply when molecule manages its own network (no network_name or bridge_name):

molecule_bridge

Bridge interface name. Default: molecule-br0.

molecule_network_cidr

IP range for the molecule network. Default: 10.10.10.0/24.