various improvements

compute/__init__.py

@@ -0,0 +1,7 @@
+"""Compute Service library."""
+
+__version__ = '0.1.0'
+
+from .instance import Instance, InstanceConfig, InstanceSchema
+from .session import Session
+from .storage import StoragePool, Volume, VolumeConfig

compute/__main__.py

@@ -0,0 +1,6 @@
+"""Command line interface for compute module."""
+
+from compute.cli import control
+
+
+control.cli()

compute/cli/_create.py

@@ -0,0 +1,26 @@
+import argparse
+
+from compute import Session
+from compute.utils import identifiers
+
+
+def _create_instance(session: Session, args: argparse.Namespace) -> None:
+    """
+    Умолчания (достать информацию из либвирта):
+    - arch
+    - machine
+    - emulator
+    - CPU
+        - cpu_vendor
+        - cpu_model
+        - фичи
+    - max_memory
+    - max_vcpus
+
+    (сегнерировать):
+    - MAC адрес
+    - boot_order = ('cdrom', 'hd')
+    - title = ''
+    - name = uuid.uuid4().hex
+    """
+    print(args)

compute/cli/control.py

@@ -0,0 +1,319 @@
+"""Command line interface."""
+
+import argparse
+import logging
+import os
+import shlex
+import sys
+
+import libvirt
+
+from compute import __version__
+from compute.exceptions import (
+    ComputeServiceError,
+    GuestAgentTimeoutExceededError,
+)
+from compute.instance import GuestAgent
+from compute.session import Session
+
+from ._create import _create_instance
+
+
+log = logging.getLogger(__name__)
+log_levels = logging.getLevelNamesMapping()
+
+env_log_level = os.getenv('CMP_LOG')
+
+libvirt.registerErrorHandler(
+    lambda userdata, err: None,  # noqa: ARG005
+    ctx=None,
+)
+
+
+class Table:
+    """Minimalistic text table constructor."""
+
+    def __init__(self, whitespace: str | None = None):
+        """Initialise Table."""
+        self.whitespace = whitespace or '\t'
+        self.header = []
+        self._rows = []
+        self._table = ''
+
+    def row(self, row: list) -> None:
+        """Add table row."""
+        self._rows.append([str(col) for col in row])
+
+    def rows(self, rows: list[list]) -> None:
+        """Add multiple rows."""
+        for row in rows:
+            self.row(row)
+
+    def __str__(self) -> str:
+        """Build table and return."""
+        widths = [max(map(len, col)) for col in zip(*self._rows, strict=True)]
+        self._rows.insert(0, [str(h).upper() for h in self.header])
+        for row in self._rows:
+            self._table += self.whitespace.join(
+                (
+                    val.ljust(width)
+                    for val, width in zip(row, widths, strict=True)
+                )
+            )
+            self._table += '\n'
+        return self._table.strip()
+
+
+def _list_instances(session: Session) -> None:
+    table = Table()
+    table.header = ['NAME', 'STATE']
+    for instance in session.list_instances():
+        table.row(
+            [
+                instance.name,
+                instance.status,
+            ]
+        )
+    print(table)
+    sys.exit()
+
+
+def _exec_guest_agent_command(
+    session: Session, args: argparse.Namespace
+) -> None:
+    instance = session.get_instance(args.instance)
+    ga = GuestAgent(instance.domain, timeout=args.timeout)
+    arguments = args.arguments.copy()
+    if len(arguments) > 1:
+        arguments = [shlex.join(arguments)]
+    if not args.no_cmd_string:
+        arguments.insert(0, '-c')
+    stdin = None
+    if not sys.stdin.isatty():
+        stdin = sys.stdin.read()
+    try:
+        output = ga.guest_exec(
+            path=args.shell,
+            args=arguments,
+            env=args.env,
+            stdin=stdin,
+            capture_output=True,
+            decode_output=True,
+            poll=True,
+        )
+    except GuestAgentTimeoutExceededError as e:
+        sys.exit(
+            f'{e}. NOTE: command may still running in guest, '
+            f'PID={ga.last_pid}'
+        )
+    if output.stderr:
+        print(output.stderr.strip(), file=sys.stderr)
+    if output.stdout:
+        print(output.stdout.strip(), file=sys.stdout)
+    sys.exit(output.exitcode)
+
+
+def main(session: Session, args: argparse.Namespace) -> None:
+    """Perform actions."""
+    match args.command:
+        case 'create':
+            _create_instance(session, args)
+        case 'exec':
+            _exec_guest_agent_command(session, args)
+        case 'ls':
+            _list_instances(session)
+        case 'start':
+            instance = session.get_instance(args.instance)
+            instance.start()
+        case 'shutdown':
+            instance = session.get_instance(args.instance)
+            instance.shutdown(args.method)
+        case 'reboot':
+            instance = session.get_instance(args.instance)
+            instance.reboot()
+        case 'reset':
+            instance = session.get_instance(args.instance)
+            instance.reset()
+        case 'status':
+            instance = session.get_instance(args.instance)
+            print(instance.status)
+        case 'setvcpus':
+            instance = session.get_instance(args.instance)
+            instance.set_vcpus(args.nvcpus, live=True)
+
+
+def cli() -> None:  # noqa: PLR0915
+    """Parse command line arguments."""
+    root = argparse.ArgumentParser(
+        prog='compute',
+        description='manage compute instances and storage volumes.',
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    root.add_argument(
+        '-v',
+        '--verbose',
+        action='store_true',
+        default=False,
+        help='enable verbose mode',
+    )
+    root.add_argument(
+        '-c',
+        '--connect',
+        metavar='URI',
+        default='qemu:///system',
+        help='libvirt connection URI',
+    )
+    root.add_argument(
+        '-l',
+        '--log-level',
+        metavar='LEVEL',
+        choices=log_levels,
+        help='log level [envvar: CMP_LOG]',
+    )
+    root.add_argument(
+        '-V',
+        '--version',
+        action='version',
+        version=__version__,
+    )
+    subparsers = root.add_subparsers(dest='command', metavar='COMMAND')
+
+    # create command
+    create = subparsers.add_parser('create', help='create compute instance')
+    create.add_argument('image', nargs='?')
+    create.add_argument('--name', help='instance name, used as ID')
+    create.add_argument('--title', help='human-understandable instance title')
+    create.add_argument('--desc', default='', help='instance description')
+    create.add_argument('--memory', type=int, help='memory in MiB')
+    create.add_argument('--max-memory', type=int, help='max memory in MiB')
+    create.add_argument('--vcpus', type=int)
+    create.add_argument('--max-vcpus', type=int)
+    create.add_argument('--cpu-vendor')
+    create.add_argument('--cpu-model')
+    create.add_argument(
+        '--cpu-emulation-mode',
+        choices=['host-passthrough', 'host-model', 'custom'],
+        default='host-passthrough',
+    )
+    create.add_argument('--cpu-features')
+    create.add_argument('--cpu-topology')
+    create.add_argument('--mahine')
+    create.add_argument('--emulator')
+    create.add_argument('--arch')
+    create.add_argument('--boot-order')
+    create.add_argument('--volume')
+    create.add_argument('-f', '--file', help='create instance from YAML')
+
+    # exec subcommand
+    execute = subparsers.add_parser(
+        'exec',
+        help='execute command in guest via guest agent',
+        description=(
+            'NOTE: any argument after instance name will be passed into '
+            'guest as shell command.'
+        ),
+    )
+    execute.add_argument('instance')
+    execute.add_argument('arguments', nargs=argparse.REMAINDER)
+    execute.add_argument(
+        '-t',
+        '--timeout',
+        type=int,
+        default=60,
+        help=(
+            'waiting time in seconds for a command to be executed '
+            'in guest, 60 sec by default'
+        ),
+    )
+    execute.add_argument(
+        '-s',
+        '--shell',
+        default='/bin/sh',
+        help='path to executable in guest, /bin/sh by default',
+    )
+    execute.add_argument(
+        '-e',
+        '--env',
+        type=str,
+        nargs='?',
+        action='append',
+        help='environment variables to pass to executable in guest',
+    )
+    execute.add_argument(
+        '-n',
+        '--no-cmd-string',
+        action='store_true',
+        default=False,
+        help=(
+            "do not append '-c' option to arguments list, suitable "
+            'for non-shell executables and other specific cases.'
+        ),
+    )
+
+    # ls subcommand
+    listall = subparsers.add_parser('ls', help='list instances')
+    listall.add_argument(
+        '-a',
+        '--all',
+        action='store_true',
+        default=False,
+        help='list all instances including inactive',
+    )
+
+    # start subcommand
+    start = subparsers.add_parser('start', help='start instance')
+    start.add_argument('instance')
+
+    # shutdown subcommand
+    shutdown = subparsers.add_parser('shutdown', help='shutdown instance')
+    shutdown.add_argument('instance')
+    shutdown.add_argument(
+        '-m',
+        '--method',
+        choices=['soft', 'normal', 'hard', 'unsafe'],
+        default='normal',
+        help='use shutdown method',
+    )
+
+    # reboot subcommand
+    reboot = subparsers.add_parser('reboot', help='reboot instance')
+    reboot.add_argument('instance')
+
+    # reset subcommand
+    reset = subparsers.add_parser('reset', help='reset instance')
+    reset.add_argument('instance')
+
+    # status subcommand
+    status = subparsers.add_parser('status', help='display instance status')
+    status.add_argument('instance')
+
+    # setvcpus subcommand
+    setvcpus = subparsers.add_parser('setvcpus', help='set vCPU number')
+    setvcpus.add_argument('instance')
+    setvcpus.add_argument('nvcpus', type=int)
+
+    # Run parser
+    args = root.parse_args()
+    if args.command is None:
+        root.print_help()
+        sys.exit()
+
+    # Set logging level
+    log_level = args.log_level or env_log_level
+    if log_level in log_levels:
+        logging.basicConfig(level=log_levels[log_level])
+
+    # Perform actions
+    try:
+        with Session(args.connect) as session:
+            main(session, args)
+    except ComputeServiceError as e:
+        sys.exit(f'error: {e}')
+    except (KeyboardInterrupt, SystemExit):
+        sys.exit()
+    except Exception as e:  # noqa: BLE001
+        sys.exit(f'unexpected error {type(e)}: {e}')
+
+
+if __name__ == '__main__':
+    cli()

compute/exceptions.py

@@ -0,0 +1,49 @@
+"""Compute Service exceptions."""
+
+
+class ComputeServiceError(Exception):
+    """Basic exception class for Compute."""
+
+
+class ConfigLoaderError(ComputeServiceError):
+    """Something went wrong when loading configuration."""
+
+
+class SessionError(ComputeServiceError):
+    """Something went wrong while connecting to libvirtd."""
+
+
+class GuestAgentError(ComputeServiceError):
+    """Something went wring when QEMU Guest Agent call."""
+
+
+class GuestAgentUnavailableError(GuestAgentError):
+    """Guest agent is not connected or is unavailable."""
+
+
+class GuestAgentTimeoutExceededError(GuestAgentError):
+    """QEMU timeout exceeded."""
+
+    def __init__(self, msg: int):
+        """Initialise GuestAgentTimeoutExceededError."""
+        super().__init__(f'QEMU timeout ({msg} sec) exceeded')
+
+
+class GuestAgentCommandNotSupportedError(GuestAgentError):
+    """Guest agent command is not supported or blacklisted on guest."""
+
+
+class StoragePoolError(ComputeServiceError):
+    """Something went wrong when operating with storage pool."""
+
+
+class InstanceError(ComputeServiceError):
+    """Something went wrong while interacting with the domain."""
+
+
+class InstanceNotFoundError(InstanceError):
+    """Virtual machine or container not found on compute node."""
+
+    def __init__(self, msg: str):
+        """Initialise InstanceNotFoundError."""
+        super().__init__(f"compute instance '{msg}' not found")

compute/instance/__init__.py

@@ -0,0 +1,3 @@
+from .guest_agent import GuestAgent
+from .instance import Instance, InstanceConfig
+from .schemas import InstanceSchema

compute/instance/guest_agent.py

@@ -0,0 +1,197 @@
+"""Manage QEMU guest agent."""
+
+import json
+import logging
+from base64 import b64decode, standard_b64encode
+from time import sleep, time
+from typing import NamedTuple
+
+import libvirt
+import libvirt_qemu
+
+from compute.exceptions import (
+    GuestAgentCommandNotSupportedError,
+    GuestAgentError,
+    GuestAgentTimeoutExceededError,
+    GuestAgentUnavailableError,
+)
+
+
+log = logging.getLogger(__name__)
+
+QEMU_TIMEOUT = 60
+POLL_INTERVAL = 0.3
+
+
+class GuestExecOutput(NamedTuple):
+    """QEMU guest-exec command output."""
+
+    exited: bool | None = None
+    exitcode: int | None = None
+    stdout: str | None = None
+    stderr: str | None = None
+
+
+class GuestAgent:
+    """Class for interacting with QEMU guest agent."""
+
+    def __init__(self, domain: libvirt.virDomain, timeout: int | None = None):
+        """
+        Initialise GuestAgent.
+
+        :param domain: Libvirt domain object
+        :param timeout: QEMU timeout
+        """
+        self.domain = domain
+        self.timeout = timeout or QEMU_TIMEOUT
+        self.flags = libvirt_qemu.VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT
+        self.last_pid = None
+
+    def execute(self, command: dict) -> dict:
+        """
+        Execute QEMU guest agent command.
+
+        See: https://qemu-project.gitlab.io/qemu/interop/qemu-ga-ref.html
+
+        :param command: QEMU guest agent command as dict
+        :return: Command output
+        :rtype: dict
+        """
+        log.debug(command)
+        try:
+            output = libvirt_qemu.qemuAgentCommand(
+                self.domain, json.dumps(command), self.timeout, self.flags
+            )
+            return json.loads(output)
+        except libvirt.libvirtError as e:
+            if e.get_error_code() == libvirt.VIR_ERR_AGENT_UNRESPONSIVE:
+                log.exception(
+                    'Guest agent is unavailable on instanse=%s', self.name
+                )
+                raise GuestAgentUnavailableError(e) from e
+            raise GuestAgentError(e) from e
+
+    def is_available(self) -> bool:
+        """
+        Execute guest-ping.
+
+        :return: True or False if guest agent is unreachable.
+        :rtype: bool
+        """
+        try:
+            if self.execute({'execute': 'guest-ping', 'arguments': {}}):
+                return True
+        except GuestAgentError:
+            return False
+
+    def available_commands(self) -> set[str]:
+        """Return set of available guest agent commands."""
+        output = self.execute({'execute': 'guest-info', 'arguments': {}})
+        return {
+            cmd['name']
+            for cmd in output['return']['supported_commands']
+            if cmd['enabled'] is True
+        }
+
+    def raise_for_commands(self, commands: list[str]) -> None:
+        """
+        Check QEMU guest agent command availability.
+
+        Raise exception if command is not available.
+
+        :param commands: List of required commands
+        :raise: GuestAgentCommandNotSupportedError
+        """
+        for command in commands:
+            if command not in self.available_commands():
+                raise GuestAgentCommandNotSupportedError(command)
+
+    def guest_exec(  # noqa: PLR0913
+        self,
+        path: str,
+        args: list[str] | None = None,
+        env: list[str] | None = None,
+        stdin: str | None = None,
+        *,
+        capture_output: bool = False,
+        decode_output: bool = False,
+        poll: bool = False,
+    ) -> GuestExecOutput:
+        """
+        Execute qemu-exec command and return output.
+
+        :param path: Path ot executable on guest.
+        :param arg: List of arguments to pass to executable.
+        :param env: List of environment variables to pass to executable.
+            For example: ``['LANG=C', 'TERM=xterm']``
+        :param stdin: Data to pass to executable STDIN.
+        :param capture_output: Capture command output.
+        :param decode_output: Use base64_decode() to decode command output.
+            Affects only if `capture_output` is True.
+        :param poll: Poll command output. Uses `self.timeout` and
+            POLL_INTERVAL constant.
+        :return: Command output
+        :rtype: GuestExecOutput
+        """
+        self.raise_for_commands(['guest-exec', 'guest-exec-status'])
+        command = {
+            'execute': 'guest-exec',
+            'arguments': {
+                'path': path,
+                **({'arg': args} if args else {}),
+                **({'env': env} if env else {}),
+                **(
+                    {
+                        'input-data': standard_b64encode(
+                            stdin.encode('utf-8')
+                        ).decode('utf-8')
+                    }
+                    if stdin
+                    else {}
+                ),
+                'capture-output': capture_output,
+            },
+        }
+        output = self.execute(command)
+        self.last_pid = pid = output['return']['pid']
+        command_status = self.guest_exec_status(pid, poll=poll)['return']
+        exited = command_status['exited']
+        exitcode = command_status['exitcode']
+        stdout = command_status.get('out-data', None)
+        stderr = command_status.get('err-data', None)
+        if decode_output:
+            stdout = b64decode(stdout or '').decode('utf-8')
+            stderr = b64decode(stderr or '').decode('utf-8')
+        return GuestExecOutput(exited, exitcode, stdout, stderr)
+
+    def guest_exec_status(self, pid: int, *, poll: bool = False) -> dict:
+        """
+        Execute guest-exec-status and return output.
+
+        :param pid: PID in guest
+        :param poll: If True poll command status with POLL_INTERVAL
+        :return: Command output
+        :rtype: dict
+        """
+        self.raise_for_commands(['guest-exec-status'])
+        command = {
+            'execute': 'guest-exec-status',
+            'arguments': {'pid': pid},
+        }
+        if not poll:
+            return self.execute(command)
+        start_time = time()
+        while True:
+            command_status = self.execute(command)
+            if command_status['return']['exited']:
+                break
+            sleep(POLL_INTERVAL)
+            now = time()
+            if now - start_time > self.timeout:
+                raise GuestAgentTimeoutExceededError(self.timeout)
+        log.debug(
+            'Polling command pid=%s finished, time taken: %s seconds',
+            pid,
+            int(time() - start_time),
+        )
+        return command_status

compute/instance/instance.py

@@ -0,0 +1,551 @@
+"""Manage compute instances."""
+
+__all__ = ['Instance', 'InstanceConfig']
+
+import logging
+from dataclasses import dataclass
+
+import libvirt
+from lxml import etree
+from lxml.builder import E
+
+from compute.exceptions import (
+    GuestAgentCommandNotSupportedError,
+    InstanceError,
+)
+from compute.utils import units
+
+from .guest_agent import GuestAgent
+from .schemas import CPUSchema, InstanceSchema, NetworkInterfaceSchema
+
+
+log = logging.getLogger(__name__)
+
+
+class InstanceConfig:
+    """Compute instance description for libvirt."""
+
+    def __init__(self, schema: InstanceSchema):
+        """
+        Initialise InstanceConfig.
+
+        :param schema: InstanceSchema object
+        """
+        self.name = schema.name
+        self.title = schema.title
+        self.description = schema.description
+        self.memory = schema.memory
+        self.max_memory = schema.max_memory
+        self.vcpus = schema.vcpus
+        self.max_vcpus = schema.max_vcpus
+        self.cpu = schema.cpu
+        self.machine = schema.machine
+        self.emulator = schema.emulator
+        self.arch = schema.arch
+        self.boot = schema.boot
+        self.network_interfaces = schema.network_interfaces
+
+    def _gen_cpu_xml(self, cpu: CPUSchema) -> etree.Element:
+        xml = E.cpu(match='exact', mode=cpu.emulation_mode)
+        xml.append(E.model(cpu.model, fallback='forbid'))
+        xml.append(E.vendor(cpu.vendor))
+        xml.append(
+            E.topology(
+                sockets=str(cpu.topology.sockets),
+                dies=str(cpu.topology.dies),
+                cores=str(cpu.topology.cores),
+                threads=str(cpu.topology.threads),
+            )
+        )
+        for feature in cpu.features.require:
+            xml.append(E.feature(policy='require', name=feature))
+        for feature in cpu.features.disable:
+            xml.append(E.feature(policy='disable', name=feature))
+        return xml
+
+    def _gen_vcpus_xml(self, vcpus: int, max_vcpus: int) -> etree.Element:
+        xml = E.vcpus()
+        xml.append(E.vcpu(id='0', enabled='yes', hotpluggable='no', order='1'))
+        for i in range(max_vcpus - 1):
+            enabled = 'yes' if (i + 2) <= vcpus else 'no'
+            xml.append(
+                E.vcpu(
+                    id=str(i + 1),
+                    enabled=enabled,
+                    hotpluggable='yes',
+                    order=str(i + 2),
+                )
+            )
+        return xml
+
+    def _gen_network_interface_xml(
+        self, interface: NetworkInterfaceSchema
+    ) -> etree.Element:
+        return E.interface(
+            E.source(network=interface.source),
+            E.mac(address=interface.mac),
+            type='network',
+        )
+
+    def to_xml(self) -> str:
+        """Return XML config for libvirt."""
+        xml = E.domain(
+            E.name(self.name),
+            E.title(self.title),
+            E.description(self.description),
+            E.metadata(),
+            E.memory(str(self.memory * 1024), unit='KiB'),
+            E.currentMemory(str(self.memory * 1024), unit='KiB'),
+            type='kvm',
+        )
+        xml.append(
+            E.vcpu(
+                str(self.max_vcpus),
+                placement='static',
+                current=str(self.vcpus),
+            )
+        )
+        xml.append(self._gen_cpu_xml(self.cpu))
+        os = E.os(E.type('hvm', machine=self.machine, arch=self.arch))
+        for dev in self.boot.order:
+            os.append(E.boot(dev=dev))
+        xml.append(os)
+        xml.append(E.features(E.acpi(), E.apic()))
+        xml.append(E.on_poweroff('destroy'))
+        xml.append(E.on_reboot('restart'))
+        xml.append(E.on_crash('restart'))
+        xml.append(
+            E.pm(
+                E('suspend-to-mem', enabled='no'),
+                E('suspend-to-disk', enabled='no'),
+            )
+        )
+        devices = E.devices()
+        devices.append(E.emulator(str(self.emulator)))
+        for interface in self.network_interfaces:
+            devices.append(self._gen_network_interface_xml(interface))
+        devices.append(E.graphics(type='vnc', port='-1', autoport='yes'))
+        devices.append(E.input(type='tablet', bus='usb'))
+        devices.append(
+            E.channel(
+                E.source(mode='bind'),
+                E.target(type='virtio', name='org.qemu.guest_agent.0'),
+                E.address(
+                    type='virtio-serial', controller='0', bus='0', port='1'
+                ),
+                type='unix',
+            )
+        )
+        devices.append(
+            E.console(E.target(type='serial', port='0'), type='pty')
+        )
+        devices.append(
+            E.video(
+                E.model(type='vga', vram='16384', heads='1', primary='yes')
+            )
+        )
+        xml.append(devices)
+        return etree.tostring(xml, encoding='unicode', pretty_print=True)
+
+
+@dataclass
+class InstanceInfo:
+    state: str
+    max_memory: int
+    memory: int
+    nproc: int
+    cputime: int
+
+
+class DeviceConfig:
+    """Abstract device description class."""
+
+
+class Instance:
+    """Class for manipulating compute instance."""
+
+    def __init__(self, domain: libvirt.virDomain):
+        """
+        Initialise Instance.
+
+        :prop domain libvirt.virDomain:
+        :prop connection libvirt.virConnect:
+        :prop name str:
+        :prop guest_agent GuestAgent:
+
+        :param domain: libvirt domain object
+        """
+        self.domain = domain
+        self.connection = domain.connect()
+        self.name = domain.name()
+        self.guest_agent = GuestAgent(domain)
+
+    def _expand_instance_state(self, state: int) -> str:
+        states = {
+            libvirt.VIR_DOMAIN_NOSTATE: 'nostate',
+            libvirt.VIR_DOMAIN_RUNNING: 'running',
+            libvirt.VIR_DOMAIN_BLOCKED: 'blocked',
+            libvirt.VIR_DOMAIN_PAUSED: 'paused',
+            libvirt.VIR_DOMAIN_SHUTDOWN: 'shutdown',
+            libvirt.VIR_DOMAIN_SHUTOFF: 'shutoff',
+            libvirt.VIR_DOMAIN_CRASHED: 'crashed',
+            libvirt.VIR_DOMAIN_PMSUSPENDED: 'pmsuspended',
+        }
+        return states[state]
+
+    @property
+    def info(self) -> InstanceInfo:
+        """
+        Return instance info.
+
+        https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainInfo
+        """
+        _info = self.domain.info()
+        return InstanceInfo(
+            state=self._expand_instance_state(_info[0]),
+            max_memory=_info[1],
+            memory=_info[2],
+            nproc=_info[3],
+            cputime=_info[4],
+        )
+
+    @property
+    def status(self) -> str:
+        """
+        Return instance state: 'running', 'shutoff', etc.
+
+        Reference:
+        https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainState
+        """
+        try:
+            state, _ = self.domain.state()
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                'Cannot fetch status of ' f'instance={self.name}: {e}'
+            ) from e
+        return self._expand_instance_state(state)
+
+    @property
+    def is_running(self) -> bool:
+        """Return True if instance is running, else return False."""
+        if self.domain.isActive() != 1:
+            # 0 - is inactive, -1 - is error
+            return False
+        return True
+
+    @property
+    def is_autostart(self) -> bool:
+        """Return True if instance autostart is enabled, else return False."""
+        try:
+            return bool(self.domain.autostart())
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                f'Cannot get autostart status for '
+                f'instance={self.name}: {e}'
+            ) from e
+
+    def start(self) -> None:
+        """Start defined instance."""
+        log.info('Starting instnce=%s', self.name)
+        if self.is_running:
+            log.warning(
+                'Already started, nothing to do instance=%s', self.name
+            )
+            return
+        try:
+            self.domain.create()
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                f'Cannot start instance={self.name}: {e}'
+            ) from e
+
+    def shutdown(self, method: str | None = None) -> None:
+        """
+        Shutdown instance.
+
+        Shutdown methods:
+
+        SOFT
+            Use guest agent to shutdown. If guest agent is unavailable
+            NORMAL method will be used.
+
+        NORMAL
+            Use method choosen by hypervisor to shutdown. Usually send ACPI
+            signal to guest OS. OS may ignore ACPI e.g. if guest is hanged.
+
+        HARD
+            Shutdown instance without any guest OS shutdown. This is simular
+            to unplugging machine from power. Internally send SIGTERM to
+            instance process and destroy it gracefully.
+
+        UNSAFE
+            Force shutdown. Internally send SIGKILL to instance process.
+            There is high data corruption risk!
+
+        If method is None NORMAL method will used.
+
+        :param method: Method used to shutdown instance
+        """
+        methods = {
+            'SOFT': libvirt.VIR_DOMAIN_SHUTDOWN_GUEST_AGENT,
+            'NORMAL': libvirt.VIR_DOMAIN_SHUTDOWN_DEFAULT,
+            'HARD': libvirt.VIR_DOMAIN_DESTROY_GRACEFUL,
+            'UNSAFE': libvirt.VIR_DOMAIN_DESTROY_DEFAULT,
+        }
+        if method is None:
+            method = 'NORMAL'
+        if not isinstance(method, str):
+            raise TypeError(
+                f"Shutdown method must be a 'str', not {type(method)}"
+            )
+        method = method.upper()
+        if method not in methods:
+            raise ValueError(f"Unsupported shutdown method: '{method}'")
+        try:
+            if method in ['SOFT', 'NORMAL']:
+                self.domain.shutdownFlags(flags=methods[method])
+            elif method in ['HARD', 'UNSAFE']:
+                self.domain.destroyFlags(flags=methods[method])
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                f'Cannot shutdown instance={self.name} ' f'{method=}: {e}'
+            ) from e
+
+    def reset(self) -> None:
+        """
+        Reset instance.
+
+        Copypaste from libvirt doc:
+
+        Reset a domain immediately without any guest OS shutdown.
+        Reset emulates the power reset button on a machine, where all
+        hardware sees the RST line set and reinitializes internal state.
+
+        Note that there is a risk of data loss caused by reset without any
+        guest OS shutdown.
+        """
+        try:
+            self.domain.reset()
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                f'Cannot reset instance={self.name}: {e}'
+            ) from e
+
+    def reboot(self) -> None:
+        """Send ACPI signal to guest OS to reboot. OS may ignore this."""
+        try:
+            self.domain.reboot()
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                f'Cannot reboot instance={self.name}: {e}'
+            ) from e
+
+    def set_autostart(self, *, enabled: bool) -> None:
+        """
+        Set autostart flag for instance.
+
+        :param enabled: Bool argument to set or unset autostart flag.
+        """
+        autostart = 1 if enabled else 0
+        try:
+            self.domain.setAutostart(autostart)
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                f'Cannot set autostart flag for instance={self.name} '
+                f'{autostart=}: {e}'
+            ) from e
+
+    def set_vcpus(self, nvcpus: int, *, live: bool = False) -> None:
+        """
+        Set vCPU number.
+
+        If `live` is True and instance is not currently running vCPUs
+        will set in config and will applied when instance boot.
+
+        NB: Note that if this call is executed before the guest has
+        finished booting, the guest may fail to process the change.
+
+        :param nvcpus: Number of vCPUs
+        :param live: Affect a running instance
+        """
+        if nvcpus == 0:
+            raise InstanceError(
+                f'Cannot set zero vCPUs for instance={self.name}'
+            )
+        if nvcpus == self.info.nproc:
+            log.warning(
+                'Instance instance=%s already have %s vCPUs, nothing to do',
+                self.name,
+                nvcpus,
+            )
+            return
+        try:
+            flags = libvirt.VIR_DOMAIN_AFFECT_CONFIG
+            self.domain.setVcpusFlags(nvcpus, flags=flags)
+            if live is True:
+                if not self.is_running:
+                    log.warning(
+                        'Instance is not running, changes applied in '
+                        'instance config.'
+                    )
+                    return
+                flags = libvirt.VIR_DOMAIN_AFFECT_LIVE
+                self.domain.setVcpusFlags(nvcpus, flags=flags)
+                if self.guest_agent.is_available():
+                    try:
+                        self.guest_agent.raise_for_commands(
+                            ['guest-set-vcpus']
+                        )
+                        flags = libvirt.VIR_DOMAIN_VCPU_GUEST
+                        self.domain.setVcpusFlags(nvcpus, flags=flags)
+                    except GuestAgentCommandNotSupportedError:
+                        log.warning(
+                            'Cannot set vCPUs in guest via agent, you may '
+                            'need to apply changes in guest manually.'
+                        )
+                else:
+                    log.warning(
+                        'Cannot set vCPUs in guest OS on instance=%s. '
+                        'You may need to apply CPUs in guest manually.',
+                        self.name,
+                    )
+        except libvirt.libvirtError as e:
+            raise InstanceError(
+                f'Cannot set vCPUs for instance={self.name}: {e}'
+            ) from e
+
+    def set_memory(self, memory: int, *, live: bool = False) -> None:
+        """
+        Set memory.
+
+        If `live` is True and instance is not currently running set memory
+        in config and will applied when instance boot.
+
+        :param memory: Memory value in mebibytes
+        :param live: Affect a running instance
+        """
+        if memory == 0:
+            raise InstanceError(
+                f'Cannot set zero memory for instance={self.name}'
+            )
+        if live and self.info()['state'] == libvirt.VIR_DOMAIN_RUNNING:
+            flags = (
+                libvirt.VIR_DOMAIN_AFFECT_LIVE
+                | libvirt.VIR_DOMAIN_AFFECT_CONFIG
+            )
+        else:
+            flags = libvirt.VIR_DOMAIN_AFFECT_CONFIG
+        try:
+            self.domain.setMemoryFlags(
+                memory * 1024, flags=libvirt.VIR_DOMAIN_MEM_MAXIMUM
+            )
+            self.domain.setMemoryFlags(memory * 1024, flags=flags)
+        except libvirt.libvirtError as e:
+            msg = f'Cannot set memory for instance={self.name} {memory=}: {e}'
+            raise InstanceError(msg) from e
+
+    def attach_device(
+        self, device: 'DeviceConfig', *, live: bool = False
+    ) -> None:
+        """
+        Attach device to compute instance.
+
+        :param device: Object with device description e.g. DiskConfig
+        :param live: Affect a running instance
+        """
+        if live and self.is_running:
+            flags = (
+                libvirt.VIR_DOMAIN_AFFECT_LIVE
+                | libvirt.VIR_DOMAIN_AFFECT_CONFIG
+            )
+        else:
+            flags = libvirt.VIR_DOMAIN_AFFECT_CONFIG
+        self.domain.attachDeviceFlags(device.to_xml(), flags=flags)
+
+    def detach_device(
+        self, device: 'DeviceConfig', *, live: bool = False
+    ) -> None:
+        """
+        Dettach device from compute instance.
+
+        :param device: Object with device description e.g. DiskConfig
+        :param live: Affect a running instance
+        """
+        if live and self.is_running:
+            flags = (
+                libvirt.VIR_DOMAIN_AFFECT_LIVE
+                | libvirt.VIR_DOMAIN_AFFECT_CONFIG
+            )
+        else:
+            flags = libvirt.VIR_DOMAIN_AFFECT_CONFIG
+        self.domain.detachDeviceFlags(device.to_xml(), flags=flags)
+
+    def resize_volume(
+        self, name: str, capacity: int, unit: units.DataUnit
+    ) -> None:
+        """
+        Resize block device.
+
+        :param name: Disk device name e.g. `vda`, `sda`, etc.
+        :param capacity: Volume capacity in bytes.
+        """
+        self.domain.blockResize(
+            name,
+            units.to_bytes(capacity, unit=unit),
+            flags=libvirt.VIR_DOMAIN_BLOCK_RESIZE_BYTES,
+        )
+
+    def pause(self) -> None:
+        """Pause instance."""
+        raise NotImplementedError
+
+    def resume(self) -> None:
+        """Resume paused instance."""
+        raise NotImplementedError
+
+    def list_ssh_keys(self, user: str) -> list[str]:
+        """
+        Get list of SSH keys on guest for specific user.
+
+        :param user: Username.
+        """
+        raise NotImplementedError
+
+    def set_ssh_keys(self, user: str, ssh_keys: list[str]) -> None:
+        """
+        Add SSH keys to guest for specific user.
+
+        :param user: Username.
+        :param ssh_keys: List of public SSH keys.
+        """
+        raise NotImplementedError
+
+    def remove_ssh_keys(self, user: str, ssh_keys: list[str]) -> None:
+        """
+        Remove SSH keys from guest for specific user.
+
+        :param user: Username.
+        :param ssh_keys: List of public SSH keys.
+        """
+        raise NotImplementedError
+
+    def set_user_password(self, user: str, password: str) -> None:
+        """
+        Set new user password in guest OS.
+
+        This action performs by guest agent inside guest.
+
+        :param user: Username.
+        :param password: Password.
+        """
+        self.domain.setUserPassword(user, password)
+
+    def dump_xml(self, *, inactive: bool = False) -> str:
+        """Return instance XML description."""
+        flags = libvirt.VIR_DOMAIN_XML_INACTIVE if inactive else 0
+        return self.domain.XMLDesc(flags)
+
+    def delete(self) -> None:
+        """Undefine instance and delete local volumes."""
+        self.shutdown(method='HARD')
+        self.domain.undefine()

compute/instance/schemas.py

@@ -0,0 +1,126 @@
+"""Compute instance related objects schemas."""
+
+import re
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import BaseModel, validator
+
+from compute.utils.units import DataUnit
+
+
+class CPUEmulationMode(StrEnum):
+    """CPU emulation mode enumerated."""
+
+    HOST_PASSTHROUGH = 'host-passthrough'
+    HOST_MODEL = 'host-model'
+    CUSTOM = 'custom'
+    MAXIMUM = 'maximum'
+
+
+class CPUTopologySchema(BaseModel):
+    """CPU topology model."""
+
+    sockets: int
+    cores: int
+    threads: int
+    dies: int = 1
+
+
+class CPUFeaturesSchema(BaseModel):
+    """CPU features model."""
+
+    require: list[str]
+    disable: list[str]
+
+
+class CPUSchema(BaseModel):
+    """CPU model."""
+
+    emulation_mode: CPUEmulationMode
+    model: str
+    vendor: str
+    topology: CPUTopologySchema
+    features: CPUFeaturesSchema
+
+
+class StorageVolumeType(StrEnum):
+    """Storage volume types enumeration."""
+
+    FILE = 'file'
+    NETWORK = 'network'
+
+
+class StorageVolumeCapacitySchema(BaseModel):
+    """Storage volume capacity field model."""
+
+    value: int
+    unit: DataUnit
+
+
+class StorageVolumeSchema(BaseModel):
+    """Storage volume model."""
+
+    type: StorageVolumeType  # noqa: A003
+    source: Path
+    target: str
+    capacity: StorageVolumeCapacitySchema
+    readonly: bool = False
+    is_system: bool = False
+
+
+class NetworkInterfaceSchema(BaseModel):
+    """Network inerface model."""
+
+    source: str
+    mac: str
+
+
+class BootOptionsSchema(BaseModel):
+    """Instance boot settings."""
+
+    order: tuple
+
+
+class InstanceSchema(BaseModel):
+    """Compute instance model."""
+
+    name: str
+    title: str
+    description: str
+    memory: int
+    max_memory: int
+    vcpus: int
+    max_vcpus: int
+    cpu: CPUSchema
+    machine: str
+    emulator: Path
+    arch: str
+    image: str
+    boot: BootOptionsSchema
+    volumes: list[StorageVolumeSchema]
+    network_interfaces: list[NetworkInterfaceSchema]
+
+    @validator('name')
+    def _check_name(cls, value: str) -> str:  # noqa: N805
+        if not re.match(r'^[a-z0-9_]+$', value):
+            msg = (
+                'Name can contain only lowercase letters, numbers '
+                'and underscore.'
+            )
+            raise ValueError(msg)
+        return value
+
+    @validator('volumes')
+    def _check_volumes(cls, value: list) -> list:  # noqa: N805
+        if len([v for v in value if v.is_system is True]) != 1:
+            msg = 'Volumes list must contain one system volume'
+            raise ValueError(msg)
+        return value
+
+    @validator('network_interfaces')
+    def _check_network_interfaces(cls, value: list) -> list:  # noqa: N805
+        if not value:
+            msg = 'Network interfaces list must contain at least one element'
+            raise ValueError(msg)
+        return value

compute/session.py

@@ -0,0 +1,156 @@
+"""Hypervisor session manager."""
+
+import logging
+import os
+from contextlib import AbstractContextManager
+from types import TracebackType
+from typing import Any, NamedTuple
+from uuid import uuid4
+
+import libvirt
+from lxml import etree
+
+from .exceptions import InstanceNotFoundError, SessionError
+from .instance import Instance, InstanceConfig, InstanceSchema
+from .storage import DiskConfig, StoragePool, VolumeConfig
+from .utils import units
+
+
+log = logging.getLogger(__name__)
+
+
+class Capabilities(NamedTuple):
+    """Store domain capabilities info."""
+
+    arch: str
+    virt: str
+    emulator: str
+    machine: str
+
+
+class Session(AbstractContextManager):
+    """Hypervisor session manager."""
+
+    def __init__(self, uri: str | None = None):
+        """
+        Initialise session with hypervisor.
+
+        :param uri: libvirt connection URI.
+        """
+        self.IMAGES_POOL = os.getenv('CMP_IMAGES_POOL')
+        self.VOLUMES_POOL = os.getenv('CMP_VOLUMES_POOL')
+        self.uri = uri or 'qemu:///system'
+        self.connection = libvirt.open(self.uri)
+
+    def __enter__(self):
+        """Return Session object."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        exc_traceback: TracebackType | None,
+    ):
+        """Close the connection when leaving the context."""
+        self.close()
+
+    def close(self) -> None:
+        """Close connection to libvirt daemon."""
+        self.connection.close()
+
+    def capabilities(self) -> Capabilities:
+        """Return capabilities e.g. arch, virt, emulator, etc."""
+        prefix = '/domainCapabilities'
+        caps = etree.fromstring(self.connection.getDomainCapabilities())  # noqa: S320
+        return Capabilities(
+            arch=caps.xpath(f'{prefix}/arch/text()')[0],
+            virt=caps.xpath(f'{prefix}/domain/text()')[0],
+            emulator=caps.xpath(f'{prefix}/path/text()')[0],
+            machine=caps.xpath(f'{prefix}/machine/text()')[0],
+        )
+
+    def create_instance(self, **kwargs: Any) -> Instance:
+        """
+        Create and return new compute instance.
+
+        :param name str: Instance name.
+        :param title str: Instance title for humans.
+        :param description str: Some information about instance
+        :param memory int: Memory in MiB.
+        :param max_memory int: Maximum memory in MiB.
+        """
+        # TODO @ge: create instances in transaction
+        data = InstanceSchema(**kwargs)
+        config = InstanceConfig(data)
+        log.info('Define XML...')
+        log.info(config.to_xml())
+        self.connection.defineXML(config.to_xml())
+        log.info('Getting instance...')
+        instance = self.get_instance(config.name)
+        log.info('Creating volumes...')
+        for volume in data.volumes:
+            log.info('Creating volume=%s', volume)
+            capacity = units.to_bytes(
+                volume.capacity.value, volume.capacity.unit
+            )
+            log.info('Connecting to images pool...')
+            images_pool = self.get_storage_pool(self.IMAGES_POOL)
+            log.info('Connecting to volumes pool...')
+            volumes_pool = self.get_storage_pool(self.VOLUMES_POOL)
+            log.info('Building volume configuration...')
+            # if not volume.source:
+            # В случае если пользователь передаёт source для волюма, следует
+            # в либвирте делать поиск волюма по пути, а не по имени
+            #    gen_vol_name
+            # TODO @ge: come up with something else
+            vol_name = f'{config.name}-{volume.target}-{uuid4()}.qcow2'
+            vol_conf = VolumeConfig(
+                name=vol_name,
+                path=str(volumes_pool.path.joinpath(vol_name)),
+                capacity=capacity,
+            )
+            log.info('Volume configuration is:\n %s', vol_conf.to_xml())
+            if volume.is_system is True:
+                log.info(
+                    "Volume is marked as 'system', start cloning image..."
+                )
+                log.info('Get image %s', data.image)
+                image = images_pool.get_volume(data.image)
+                log.info('Cloning image into volumes pool...')
+                vol = volumes_pool.clone_volume(image, vol_conf)
+                log.info(
+                    'Resize cloned volume to specified size: %s',
+                    capacity,
+                )
+                vol.resize(capacity, unit=units.DataUnit.BYTES)
+            else:
+                log.info('Create volume...')
+                volumes_pool.create_volume(vol_conf)
+            log.info('Attaching volume to instance...')
+            instance.attach_device(
+                DiskConfig(path=vol_conf.path, target=volume.target)
+            )
+        return instance
+
+    def get_instance(self, name: str) -> Instance:
+        """Get compute instance by name."""
+        try:
+            return Instance(self.connection.lookupByName(name))
+        except libvirt.libvirtError as err:
+            if err.get_error_code() == libvirt.VIR_ERR_NO_DOMAIN:
+                raise InstanceNotFoundError(name) from err
+            raise SessionError(err) from err
+
+    def list_instances(self) -> list[Instance]:
+        """List all instances."""
+        return [Instance(dom) for dom in self.connection.listAllDomains()]
+
+    def get_storage_pool(self, name: str) -> StoragePool:
+        """Get storage pool by name."""
+        # TODO @ge: handle Storage pool not found error
+        return StoragePool(self.connection.storagePoolLookupByName(name))
+
+    def list_storage_pools(self) -> list[StoragePool]:
+        """List all strage pools."""
+        return [StoragePool(p) for p in self.connection.listStoragePools()]

compute/storage/__init__.py

@@ -0,0 +1,2 @@
+from .pool import StoragePool
+from .volume import DiskConfig, Volume, VolumeConfig

compute/storage/pool.py

@@ -0,0 +1,114 @@
+"""Manage storage pools."""
+
+import logging
+from pathlib import Path
+from typing import NamedTuple
+
+import libvirt
+from lxml import etree
+
+from compute.exceptions import StoragePoolError
+
+from .volume import Volume, VolumeConfig
+
+
+log = logging.getLogger(__name__)
+
+
+class StoragePoolUsage(NamedTuple):
+    """Storage pool usage info schema."""
+
+    capacity: int
+    allocation: int
+    available: int
+
+
+class StoragePool:
+    """Storage pool manipulating class."""
+
+    def __init__(self, pool: libvirt.virStoragePool):
+        """Initislise StoragePool."""
+        self.pool = pool
+        self.name = pool.name()
+
+    @property
+    def path(self) -> Path:
+        """Return storage pool path."""
+        xml = etree.fromstring(self.pool.XMLDesc())  # noqa: S320
+        return Path(xml.xpath('/pool/target/path/text()')[0])
+
+    def usage(self) -> StoragePoolUsage:
+        """Return info about storage pool usage."""
+        xml = etree.fromstring(self.pool.XMLDesc())  # noqa: S320
+        return StoragePoolUsage(
+            capacity=int(xml.xpath('/pool/capacity/text()')[0]),
+            allocation=int(xml.xpath('/pool/allocation/text()')[0]),
+            available=int(xml.xpath('/pool/available/text()')[0]),
+        )
+
+    def dump_xml(self) -> str:
+        """Return storage pool XML description as string."""
+        return self.pool.XMLDesc()
+
+    def refresh(self) -> None:
+        """Refresh storage pool."""
+        # TODO @ge: handle libvirt asynchronous job related exceptions
+        self.pool.refresh()
+
+    def create_volume(self, vol_conf: VolumeConfig) -> Volume:
+        """Create storage volume and return Volume instance."""
+        log.info(
+            'Create storage volume vol=%s in pool=%s', vol_conf.name, self.pool
+        )
+        vol = self.pool.createXML(
+            vol_conf.to_xml(),
+            flags=libvirt.VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA,
+        )
+        return Volume(self.pool, vol)
+
+    def clone_volume(self, src: Volume, dst: VolumeConfig) -> Volume:
+        """
+        Make storage volume copy.
+
+        :param src: Input volume
+        :param dst: Output volume config
+        """
+        log.info(
+            'Start volume cloning '
+            'src_pool=%s src_vol=%s dst_pool=%s dst_vol=%s',
+            src.pool_name,
+            src.name,
+            self.pool.name,
+            dst.name,
+        )
+        vol = self.pool.createXMLFrom(
+            dst.to_xml(),  # new volume XML description
+            src.vol,  # source volume virStorageVol object
+            flags=libvirt.VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA,
+        )
+        if vol is None:
+            raise StoragePoolError
+        return Volume(self.pool, vol)
+
+    def get_volume(self, name: str) -> Volume | None:
+        """Lookup and return Volume instance or None."""
+        log.info(
+            'Lookup for storage volume vol=%s in pool=%s', name, self.pool.name
+        )
+        try:
+            vol = self.pool.storageVolLookupByName(name)
+            return Volume(self.pool, vol)
+        except libvirt.libvirtError as e:
+            # TODO @ge: Raise VolumeNotFoundError instead
+            if (
+                e.get_error_domain() == libvirt.VIR_FROM_STORAGE
+                or e.get_error_code() == libvirt.VIR_ERR_NO_STORAGE_VOL
+            ):
+                log.exception(e.get_error_message())
+                return None
+            log.exception('unexpected error from libvirt')
+            raise StoragePoolError(e) from e
+
+    def list_volumes(self) -> list[Volume]:
+        """Return list of volumes in storage pool."""
+        return [Volume(self.pool, vol) for vol in self.pool.listAllVolumes()]

compute/storage/volume.py

@@ -0,0 +1,124 @@
+"""Manage storage volumes."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from time import time
+
+import libvirt
+from lxml import etree
+from lxml.builder import E
+
+from compute.utils import units
+
+
+@dataclass
+class VolumeConfig:
+    """
+    Storage volume config builder.
+
+    Generate XML config for creating a volume in a libvirt
+    storage pool.
+    """
+
+    name: str
+    path: str
+    capacity: int
+
+    def to_xml(self) -> str:
+        """Return XML config for libvirt."""
+        unixtime = str(int(time()))
+        xml = E.volume(type='file')
+        xml.append(E.name(self.name))
+        xml.append(E.key(self.path))
+        xml.append(E.source())
+        xml.append(E.capacity(str(self.capacity), unit='bytes'))
+        xml.append(E.allocation('0'))
+        xml.append(
+            E.target(
+                E.path(self.path),
+                E.format(type='qcow2'),
+                E.timestamps(
+                    E.atime(unixtime), E.mtime(unixtime), E.ctime(unixtime)
+                ),
+                E.compat('1.1'),
+                E.features(E.lazy_refcounts()),
+            )
+        )
+        return etree.tostring(xml, encoding='unicode', pretty_print=True)
+
+
+@dataclass
+class DiskConfig:
+    """
+    Disk config builder.
+
+    Generate XML config for attaching or detaching storage volumes
+    to compute instances.
+    """
+
+    target: str
+    path: str
+    readonly: bool = False
+
+    def to_xml(self) -> str:
+        """Return XML config for libvirt."""
+        xml = E.disk(type='file', device='disk')
+        xml.append(E.driver(name='qemu', type='qcow2', cache='writethrough'))
+        xml.append(E.source(file=self.path))
+        xml.append(E.target(dev=self.target, bus='virtio'))
+        if self.readonly:
+            xml.append(E.readonly())
+        return etree.tostring(xml, encoding='unicode', pretty_print=True)
+
+
+class Volume:
+    """Storage volume manipulating class."""
+
+    def __init__(
+        self, pool: libvirt.virStoragePool, vol: libvirt.virStorageVol
+    ):
+        """
+        Initialise Volume.
+
+        :param pool: libvirt virStoragePool object
+        :param vol: libvirt virStorageVol object
+        """
+        self.pool = pool
+        self.pool_name = pool.name()
+        self.vol = vol
+        self.name = vol.name()
+
+    @property
+    def path(self) -> Path:
+        """Return path to volume."""
+        return Path(self.vol.path())
+
+    def dump_xml(self) -> str:
+        """Return volume XML description as string."""
+        return self.vol.XMLDesc()
+
+    def clone(self, vol_conf: VolumeConfig) -> None:
+        """
+        Make a copy of volume to the same storage pool.
+
+        :param vol_info VolumeInfo: New storage volume dataclass object
+        """
+        self.pool.createXMLFrom(
+            vol_conf.to_xml(),
+            self.vol,
+            flags=libvirt.VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA,
+        )
+
+    def resize(self, capacity: int, unit: units.DataUnit) -> None:
+        """
+        Resize volume.
+
+        :param capacity int: Volume new capacity.
+        :param unit DataUnit: Data unit. Internally converts into bytes.
+        """
+        # TODO @ge: Check actual volume size before resize
+        self.vol.resize(units.to_bytes(capacity, unit=unit))
+
+    def delete(self) -> None:
+        """Delete volume from storage pool."""
+        self.vol.delete()

compute/utils/config_loader.py

@@ -0,0 +1,41 @@
+"""Configuration loader."""
+
+import tomllib
+from collections import UserDict
+from pathlib import Path
+
+from compute.exceptions import ConfigLoaderError
+
+
+DEFAULT_CONFIGURATION = {}
+DEFAULT_CONFIG_FILE = '/etc/computed/computed.toml'
+
+
+class ConfigLoader(UserDict):
+    """UserDict for storing configuration."""
+
+    def __init__(self, file: Path | None = None):
+        """
+        Initialise ConfigLoader.
+
+        :param file: Path to configuration file. If `file` is None
+            use default path from DEFAULT_CONFIG_FILE constant.
+        """
+        # TODO @ge: load deafult configuration
+        self.file = Path(file) if file else Path(DEFAULT_CONFIG_FILE)
+        super().__init__(self.load())
+
+    def load(self) -> dict:
+        """Load confguration object from TOML file."""
+        try:
+            with Path(self.file).open('rb') as configfile:
+                return tomllib.load(configfile)
+                # TODO @ge: add config schema validation
+        except tomllib.TOMLDecodeError as tomlerr:
+            raise ConfigLoaderError(
+                f'Bad TOML syntax in config file: {self.file}: {tomlerr}'
+            ) from tomlerr
+        except (OSError, ValueError) as readerr:
+            raise ConfigLoaderError(
+                f'Cannot read config file: {self.file}: {readerr}'
+            ) from readerr

compute/utils/identifiers.py

@@ -0,0 +1,18 @@
+"""Random identificators."""
+
+# ruff: noqa: S311, C417
+
+import random
+
+
+def random_mac() -> str:
+    """Retrun random MAC address."""
+    mac = [
+        0x00,
+        0x16,
+        0x3E,
+        random.randint(0x00, 0x7F),
+        random.randint(0x00, 0xFF),
+        random.randint(0x00, 0xFF),
+    ]
+    return ':'.join(map(lambda x: '%02x' % x, mac))

compute/utils/units.py

@@ -0,0 +1,39 @@
+"""Tools for data units convertion."""
+
+from enum import StrEnum
+
+
+class DataUnit(StrEnum):
+    """Data units enumerated."""
+
+    BYTES = 'bytes'
+    KIB = 'KiB'
+    MIB = 'MiB'
+    GIB = 'GiB'
+    TIB = 'TiB'
+
+
+class InvalidDataUnitError(ValueError):
+    """Data unit is not valid."""
+
+    def __init__(self, msg: str):
+        """Initialise InvalidDataUnitError."""
+        super().__init__(
+            f'{msg}, valid units are: {", ".join(list(DataUnit))}'
+        )
+
+
+def to_bytes(value: int, unit: DataUnit = DataUnit.BYTES) -> int:
+    """Convert value to bytes. See `DataUnit`."""
+    try:
+        _ = DataUnit(unit)
+    except ValueError as e:
+        raise InvalidDataUnitError(e) from e
+    powers = {
+        DataUnit.BYTES: 0,
+        DataUnit.KIB: 1,
+        DataUnit.MIB: 2,
+        DataUnit.GIB: 3,
+        DataUnit.TIB: 4,
+    }
+    return value * pow(1024, powers[unit])