From 8e7f185fc62b834cbd03de5b1f7d86483e1f9111 Mon Sep 17 00:00:00 2001 From: ge Date: Mon, 6 Nov 2023 18:38:24 +0300 Subject: [PATCH] various improvements --- README.md | 76 ++++++++++------------- compute/instance/instance.py | 5 +- docs/source/conf.py | 2 +- docs/source/index.rst | 10 +-- docs/source/python-api/index.rst | 34 +++++----- docs/source/python-api/instance/index.rst | 4 +- docs/source/python-api/storage.rst | 14 ----- docs/source/python-api/storage/index.rst | 9 +++ docs/source/python-api/storage/pool.rst | 5 ++ docs/source/python-api/storage/volume.rst | 5 ++ 10 files changed, 81 insertions(+), 83 deletions(-) delete mode 100644 docs/source/python-api/storage.rst create mode 100644 docs/source/python-api/storage/index.rst create mode 100644 docs/source/python-api/storage/pool.rst create mode 100644 docs/source/python-api/storage/volume.rst diff --git a/README.md b/README.md index e5ebab3..65d0605 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,41 @@ -# Compute Service +# Compute -В этом репозитории развивается базовая библиотека для взаимодействия с libvirt и выполнения операций с виртуальными машинами. Фокус на QEMU/KVM. +Compute-instance management library and tools. -## Зависимости (версии из репозитория Debian 12): +Currently supports only QEMU/KVM based virtual machines. -- `python3-lxml` 4.9.2 -- `python3-docopt` 0.6.2 -- `python3-libvirt` 9.0.0 +## Docs -Минимальная поддерживаемая версия Python — `3.11`, потому, что можем. +Run `make serve-docs`. -## API +## Roadmap -В структуре проекта сейчас бардак, многое будет переосмыслено и переделано позже. Основная цель на текущем этапе — получить минимально работающий код, с помощью которого возможно выполнить установку виртуальной машины и как-то управлять ею. - -Есть набор классов, предоставляющих собой интерфейсы для взаимодействия с виртуальными машинами, стораджами, дисками и т.п. Датаклассы описывают сущности и имеют метод `to_xml()` для получения XML конфига для `libvirt`. Смысл использования датаклассов в том, чтобы иметь один объект, содержащий в себе нормальные легкочитаемые аттрибуты и XML описание сущности одновременно. - -## ROADMAP - -- [ ] Установка инстансов - - [ ] Установка с использованием эталонного образа ОС - - [ ] Установка с пустым диском и загрузкой с ISO - - [ ] Установка с использованием готового волюма -- [x] Базовое управление питанием -- [ ] Остановка и возобновление инстансов -- [ ] Изменение числа vCPU на горячую -- [ ] Изменение топологии процессора -- [ ] Выбор типа эмуляции процессора, вендора, модели и инструкций -- [ ] Изменение памяти на горячую -- [ ] Ресайз дисков на горячую -- [ ] Выбор между BIOS и UEFI -- [ ] Редактирование параметров загрузки (boot menu, etc) -- [x] Горячее подключение устройств -- [ ] Горячее отключение устройств -- [ ] GPU -- [ ] Поддержка инстансов с разной гарантированной долей CPU -- [x] Базовое управление QEMU Guest Agent -- [ ] Проверка доступности и возможностей QEMU Guest Agent -- [ ] Статистика потребления ресурсов -- [ ] Управление SSH-ключами -- [ ] Изменение пароля root +- [x] Create instances +- [ ] CDROM +- [x] Instance power management +- [ ] Instance pause and resume +- [x] vCPU hotplug +- [ ] Memory hotplug +- [x] Hot disk resize [not tested] +- [ ] CPU topology customization +- [x] CPU customization (emulation mode, model, vendor, features) +- [ ] BIOS/UEFI settings +- [x] Device attaching +- [ ] Device detaching +- [ ] GPU passthrough +- [ ] CPU guarantied resource percent support +- [x] QEMU Guest Agent management +- [ ] Instance resources usage stats +- [ ] SSH-keys management +- [x] Setting user passwords in guest [not tested] - [ ] LXC -- [ ] Работа с дисками QCOW2,3 -- [ ] ZVOL -- [ ] Сетевые диски -- [ ] Создание Storage Pool на основе TOML/YAML описания -- [ ] Удаление Storage Pool -- [ ] Снапшоты +- [x] QCOW2 disks support +- [ ] ZVOL support +- [ ] Network disks support +- [ ] Images service integration (Images service is not implemented yet) +- [ ] Manage storage pools +- [ ] Instance snapshots +- [ ] Instance backups +- [ ] Instance migrations +- [ ] HTTP API +- [ ] Full functional CLI [in progress] diff --git a/compute/instance/instance.py b/compute/instance/instance.py index 21e8d22..b561b94 100644 --- a/compute/instance/instance.py +++ b/compute/instance/instance.py @@ -484,10 +484,11 @@ class Instance: self, name: str, capacity: int, unit: units.DataUnit ) -> None: """ - Resize block device. + Resize attached block device. :param name: Disk device name e.g. `vda`, `sda`, etc. - :param capacity: Volume capacity in bytes. + :param capacity: New volume capacity. + :param unit: Capacity unit. """ self.domain.blockResize( name, diff --git a/docs/source/conf.py b/docs/source/conf.py index 7e83ba6..3f78a8c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,7 +15,7 @@ extensions = [ ] templates_path = ['_templates'] exclude_patterns = [] -language = 'ru' +language = 'en' # HTML output settings html_theme = 'alabaster' diff --git a/docs/source/index.rst b/docs/source/index.rst index 634116c..569bdfe 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,15 +1,15 @@ -Compute Service -=============== +Compute +======= -Документация библиотеки для управления Compute-инстансами. +Compute-instance management library. .. toctree:: :maxdepth: 1 python-api/index -Индексы и таблицы ------------------ +Indices and tables +------------------ * :ref:`genindex` * :ref:`modindex` diff --git a/docs/source/python-api/index.rst b/docs/source/python-api/index.rst index be20c7f..1e32950 100644 --- a/docs/source/python-api/index.rst +++ b/docs/source/python-api/index.rst @@ -1,8 +1,8 @@ Python API ========== -API позволяет выполнять действия над инстансами программно. Ниже описано пример -изменения параметров и запуска инстанса `myinstance`. +The API allows you to perform actions on instances programmatically. Below is +an example of changing parameters and launching the `myinstance` instance. .. code-block:: python @@ -10,7 +10,6 @@ API позволяет выполнять действия над инстанс from compute import Session - logging.basicConfig(level=logging.DEBUG) with Session() as session: @@ -20,28 +19,29 @@ API позволяет выполнять действия над инстанс instance.set_autostart(enabled=True) -Контекстный менеджер :class:`Session` предоставляет абстракцию над :class:`libvirt.virConnect` -и возвращает объекты других классов настоящей билиотеки. +:class:`Session` context manager provides an abstraction over :class:`libvirt.virConnect` +and returns objects of other classes of the present library. -Представление сущностей ------------------------ +Entity representation +--------------------- -Такие сущности как Сompute-инстанс представлены в виде классов. Эти классы напрямую -вызывают методы libvirt для выполнения операций на гипервизоре. Пример класса — :data:`Volume`. +Entities such as a compute-instance are represented as classes. These classes directly +call libvirt methods to perform operations on the hypervisor. An example class is +:class:`Volume`. -Конфигурационные файлы различных объектов libvirt в compute описаны специальными -датаклассами. Датакласс хранит в своих свойствах параметры объекта и может вернуть XML -конфиг для libvirt с помощью метода ``to_xml()``. Пример — :py:class:`VolumeConfig`. +The configuration files of various libvirt objects in `compute` are described by special +dataclasses. The dataclass stores object parameters in its properties and can return an +XML config for libvirt using the ``to_xml()`` method. For example :class:`VolumeConfig`. -Для валидации входных данных используются модели `Pydantic `_. -Пример — :py:class:`VolumeSchema`. +`Pydantic `_ models are used to validate input data. +For example :class:`VolumeSchema`. -Документация модулей --------------------- +Modules documentation +--------------------- .. toctree:: :maxdepth: 4 session instance/index - storage + storage/index diff --git a/docs/source/python-api/instance/index.rst b/docs/source/python-api/instance/index.rst index d0ee0ba..659ffc2 100644 --- a/docs/source/python-api/instance/index.rst +++ b/docs/source/python-api/instance/index.rst @@ -3,8 +3,8 @@ .. toctree:: :maxdepth: 1 - :caption: Содержание: - + :caption: Contents: + instance guest_agent schemas diff --git a/docs/source/python-api/storage.rst b/docs/source/python-api/storage.rst deleted file mode 100644 index 5b24aeb..0000000 --- a/docs/source/python-api/storage.rst +++ /dev/null @@ -1,14 +0,0 @@ -``storage`` -=========== - -``compute.storage.pool`` ------------------------- - -.. automodule:: compute.storage.pool - :members: - -``compute.storage.volume`` --------------------------- - -.. automodule:: compute.storage.volume - :members: diff --git a/docs/source/python-api/storage/index.rst b/docs/source/python-api/storage/index.rst new file mode 100644 index 0000000..e9ea734 --- /dev/null +++ b/docs/source/python-api/storage/index.rst @@ -0,0 +1,9 @@ +``storage`` +============ + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + pool + volume diff --git a/docs/source/python-api/storage/pool.rst b/docs/source/python-api/storage/pool.rst new file mode 100644 index 0000000..d3b2a99 --- /dev/null +++ b/docs/source/python-api/storage/pool.rst @@ -0,0 +1,5 @@ +``pool`` +======== + +.. automodule:: compute.storage.pool + :members: diff --git a/docs/source/python-api/storage/volume.rst b/docs/source/python-api/storage/volume.rst new file mode 100644 index 0000000..0623324 --- /dev/null +++ b/docs/source/python-api/storage/volume.rst @@ -0,0 +1,5 @@ +``volume`` +========== + +.. automodule:: compute.storage.volume + :members: