Libvirt/KVM Management Substrate
ObjLibvirt is a concrete implementation of the ObjSubstrate base class that provides an interface for managing virtual machines (referred to as "domains") through the Libvirt API. It is primarily intended for controlling KVM hypervisors but can be used with any hypervisor supported by Libvirt.
This class allows you to list, create, start, stop, and delete virtual machines using the unified ObjSubstrate interface.
ObjLibvirt can be configured to connect to different Libvirt daemons (local or remote) via the config.yaml file.
config.yaml Example:
libvirt:
# URI for the libvirt connection.
# Local KVM/QEMU session: "qemu:///session"
# Local system-wide KVM/QEMU: "qemu:///system"
# Remote over SSH: "qemu+ssh://user@host/system"
uri: "qemu:///system"
If no configuration is found, it defaults to qemu:///system.
ObjLibvirt provides concrete implementations for the core methods in ObjSubstrate.
| Method | Libvirt Implementation Details |
|---|---|
connect() |
Establishes a connection to the Libvirt daemon using the URI from config.yaml. |
list_instances() |
Lists all defined domains (both active and inactive), returning their name, ID, UUID, and status. |
get_instance(name) |
Retrieves detailed information for a specific domain, including its full XML description. |
create_instance(config) |
Creates (defines) a new persistent domain from an XML configuration. The config dictionary must contain an xml key with the full domain XML. |
start_instance(name) |
Starts an inactive (but defined) domain. |
stop_instance(name, force) |
Stops a running domain. If force=True, it performs a hard power-off (destroy); otherwise, it attempts a graceful shutdown. |
delete_instance(name, force) |
Deletes (undefines) a domain. If the domain is active, it must be stopped first, or force=True must be used to destroy it before undefining. |
execute_command(name, command) |
Not Implemented. This method returns an error, as command execution is intended to be handled via SSH, which is outside the scope of this class. |
ObjLibvirt.py includes a CLI for managing Libvirt domains.
listLists all defined domains (active and inactive).
python3 factory.deploy/ObjLibvirt.py list
statusGets detailed information for a specific domain.
python3 factory.deploy/ObjLibvirt.py status <domain-name>
startStarts a specified domain.
python3 factory.deploy/ObjLibvirt.py start <domain-name>
stopStops a specified domain.
python3 factory.deploy/ObjLibvirt.py stop <domain-name> [--force]
--force / -f: (Optional) Forcefully destroy the domain instead of attempting a graceful shutdown.deleteDeletes (undefines) a domain. The domain must be inactive.
python3 factory.deploy/ObjLibvirt.py delete <domain-name> [--force]
--force / -f: (Optional) Forcefully stop the domain before deleting it.create (from file)While not a direct CLI command, you can create a domain by piping an XML file to the create_instance method via a helper script or another Python module.
<!-- my-vm.xml -->
<domain type='kvm'>
<name>my-test-vm</name>
...
</domain>
# 💻 create_vm.py
from factory.deploy.ObjLibvirt import ObjLibvirt
with open("my-vm.xml", "r") as f:
xml_config = f.read()
controller = ObjLibvirt()
controller.create_instance({"xml": xml_config})