various updates v.dev3

docs/source/_static/custom.css

@@ -1 +1,2 @@
 div.code-block-caption {background: #d0d0d0;}
+a:visited {color: #004B6B;}

docs/source/cli/cloud_init.rst

@@ -0,0 +1,127 @@
+Using Cloud-init
+================
+
+Cloud-init for new instances
+----------------------------
+
+Cloud-init configs may be set inplace into :file:`instance.yaml`.
+
+.. code-block:: yaml
+   :caption: Example with Debian generic QCOW2 image
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 5
+         unit: GiB
+   cloud_init:
+     meta_data:
+       hostname: genericdebian
+       root_pass: secure_pass
+     user_data: |
+       ## template: jinja
+       #cloud-config
+       merge_how:
+         - name: list
+           settings: [append]
+       hostname: {{ ds.meta_data.hostname }}
+       fqdn: {{ ds.meta_data.hostname }}.instances.generic.cloud
+       manage_etc_hosts: true
+       chpasswd:
+         users:
+           - name: root
+             password: {{ ds.meta_data.root_pass }}
+             type: text
+         expire: False
+       ssh_pwauth: True
+       package_update: true
+       package_upgrade: true
+       packages:
+         - qemu-guest-agent
+         - vim
+         - psmisc
+         - htop
+       runcmd:
+         - [ systemctl, daemon-reload ]
+         - [ systemctl, enable, qemu-guest-agent.service ]
+         - [ systemctl, start, --no-block, qemu-guest-agent.service ]
+
+You can use separate file in this way:
+
+.. code-block:: yaml
+   :caption: user-data in separate file
+   :emphasize-lines: 11-
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 25
+         unit: GiB
+   cloud_init:
+     user_data: user-data.yaml
+
+Base64 encoded string with data must be ``base64:`` prefixed:
+
+.. code-block:: yaml
+   :caption: user-data as base64 encoded string
+   :emphasize-lines: 11-
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 25
+         unit: GiB
+   cloud_init:
+     user_data: base64:I2Nsb3VkLWNvbmZpZwpob3N0bmFtZTogY2xvdWRlYmlhbgpmcWRuOiBjbG91ZGViaWFuLmV4YW1wbGUuY29tCm1hbmFnZV9ldGNfaG9zdHM6IHRydWUK
+
+Also you can write config in YAML. Please note that in this case you will not be able to use the ``#cloud-config`` shebang.
+
+.. code-block:: yaml
+   :caption: meta-data as nested YAML
+   :emphasize-lines: 12-14
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 25
+         unit: GiB
+   cloud_init:
+     meta_data:
+       myvar: example
+       another_one: example_2
+     user_data: |
+       #cloud-config
+       #something here
+
+Edit Cloud-init config files on existing instance
+-------------------------------------------------
+
+Use ``setcloudinit`` subcommand::
+
+    compute setcloudinit myinstance --user-data user_data.yaml
+
+See `setcloudinit <../cli/reference.html#setcloudinit>`_ for details.

docs/source/cli/getting_started.rst

@@ -1,12 +1,21 @@
-Usage
-=====
+Getting started
+===============
 
 Creating compute instances
 --------------------------
 
-First place your image into images pool path.
+Compute instances are created through a description in yaml format. The description may be partial, the configuration will be supplemented with default parameters.
 
-Create :file:`inatance.yaml` config file with following content. Replace `debian_12.qcow2` with your actual image filename.
+This page describes how to start up a basic instance, you'll probably want to use cloud-init to get the guest up and running, see the instructions at `Using cloud-init <cloud_init.html>`_.
+
+The following examples contains minimal instance configuration. See also full example `here <instance_file.html>`_
+
+Using prebuilt QCOW2 disk image
+```````````````````````````````
+
+First place your image into ``images`` pool path.
+
+Create :file:`instance.yaml` config file with following content. Replace `debian_12.qcow2` with your actual image filename.
 
 .. code-block:: yaml
    :caption: Using prebuilt QCOW2 disk image
@@ -20,14 +29,13 @@ Create :file:`inatance.yaml` config file with following content. Replace `debian
    volumes:
      - type: file
        is_system: true
-       target: vda
        capacity:
          value: 10
          unit: GiB
 
 Check out what configuration will be applied when ``init``::
 
-   compute init -t
+   compute init --test
 
 Initialise instance with command::
 
@@ -50,7 +58,7 @@ Note that the ``image`` parameter is not used here.
 
 .. code-block:: yaml
    :caption: Using ISO image
-   :emphasize-lines: 11-13
+   :emphasize-lines: 10-12
    :linenos:
 
    name: myinstance
@@ -59,7 +67,6 @@ Note that the ``image`` parameter is not used here.
    volumes:
      - type: file
        is_system: true
-       target: vda
        capacity:
          value: 10
          unit: GiB
@@ -80,9 +87,8 @@ Add ``address`` attribute to start listen on all host network interfaces.
 .. code-block:: xml
    :caption: libvirt XML config fragment
    :emphasize-lines: 2
-   :linenos:
 
-   <graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0'>
+   <graphics type='vnc' port='-1' autoport='yes'>
      <listen type='address' address='0.0.0.0'/>
    </graphics>
 
@@ -96,7 +102,31 @@ Start instance and connect to VNC via any VNC client such as `Remmina <https://r
 
 Finish the OS installation over VNC and then do::
 
-   compute setcdrom myinstance /images/debian-12.2.0-amd64-netinst.iso --detach
+   compute setcdrom myinstance --detach /images/debian-12.2.0-amd64-netinst.iso
    compute powrst myinstance
 
 CDROM will be detached. ``powrst`` command will perform instance shutdown and start. Instance will booted from `vda` disk.
+
+Using existing disk
+```````````````````
+
+Place your disk image in ``volumes`` storage pool.
+
+Replace `/volume/myvolume.qcow2` with actual path to disk.
+
+.. code-block:: yaml
+   :caption: Using existing disk
+   :emphasize-lines: 7
+   :linenos:
+
+   name: myinstance
+   memory: 2048
+   vcpus: 2
+   volumes:
+     - type: file
+       is_system: true
+       source: /volumes/myvolume.qcow2
+
+Initialise and start instance::
+
+    compute init --start

docs/source/cli/index.rst

@@ -2,7 +2,9 @@ CLI
 ===
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 3
 
-    usage
+    getting_started
+    cloud_init
+    instance_file
     reference

docs/source/cli/instance_file.rst

@@ -0,0 +1,8 @@
+Instance file reference
+=======================
+
+There is full example of :file:`instance.yaml` with comments.
+
+.. literalinclude:: instance.yaml
+   :caption: instance.yaml
+   :language: yaml

docs/source/cli/reference.rst

@@ -2,6 +2,6 @@ CLI Reference
 =============
 
 .. argparse::
-   :module: compute.cli.control
+   :module: compute.cli.parser
    :func: get_parser
    :prog: compute

docs/source/conf.py

@@ -6,7 +6,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 project = 'Compute'
 copyright = '2023, Compute Authors'
 author = 'Compute Authors'
-release = '0.1.0-dev2'
+release = '0.1.0-dev3'
 
 # Sphinx general settings
 extensions = [
@@ -17,7 +17,6 @@ extensions = [
 templates_path = ['_templates']
 exclude_patterns = []
 language = 'en'
-#pygments_style = 'monokai'
 
 # HTML output settings
 html_theme = 'alabaster'

docs/source/configuration.rst

@@ -0,0 +1,37 @@
+Configuration
+=============
+
+Configuration can be stored in configration file or in environment variables prefixed with ``CMP_``.
+
+Configuration file must have TOML format. Example configuration:
+
+.. literalinclude:: ../../computed.toml
+   :caption: /etc/compute/computed.toml
+   :language: toml
+
+There are:
+
+``libvirt.uri``
+    Libvirt connection URI.
+
+    | Env: ``CMP_LIBVIRT_URI``
+    | Default: ``qemu:///system``
+
+``storage.images``
+    Name of libvirt storage pool to store compute instance etalon images.
+    `compute` takes images from here and creates disks for compute instances
+    based on them.
+
+    | Env: ``CMP_IMAGES_POOL``
+    | Default: ``images``
+
+``storage.volumes``
+    Name of libvirt storage pool to store compute instance disks.
+
+    | Env: ``CMP_VOLUMES_POOL``
+    | Default: ``volumes``
+
+.. NOTE::
+
+   ``storage.images`` and ``storage.volumes`` must be exist. Make sure that these
+   pools are defined, running, and have the autostart flag.

docs/source/index.rst

@@ -7,9 +7,10 @@ Contents
 --------
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
     installation
+    configuration
     cli/index
     pyapi/index
 

docs/source/installation.rst

@@ -6,7 +6,8 @@ Install Debian 12 on your host system. If you want use virtual machine as host m
 1. Download or build ``compute`` DEB packages.
 2. Install packages::
 
-      apt-get install ./compute*
+      apt-get install -y --no-install-recommends ./compute*
+      apt-get install -y --no-install-recommends dnsmasq
 
 3. Make sure that ``libvirtd`` and ``dnsmasq`` are enabled and running::
 
@@ -24,21 +25,24 @@ Install Debian 12 on your host system. If you want use virtual machine as host m
           virsh pool-autostart $pool
       done
 
-5. Prepare env. Set environment variables in your `~/.profile`, `~/.bashrc` or global in `/etc/profile.d/compute` or `/etc/bash.bashrc`:
+5. Setup configration if you want create another storage pools. See
+   `Configuration <configuration.html>`_
+   You can use configuration file :file:`/etc/compute/computed.toml` or environment
+   variables.
+
+   You can set environment variables in your :file:`~/.profile`, :file:`~/.bashrc`
+   or globally in :file:`/etc/profile.d/compute` or :file:`/etc/bash.bashrc`. For example:
 
    .. code-block:: sh
 
+      export CMP_LIBVIRT_URI=qemu:///system
       export CMP_IMAGES_POOL=images
       export CMP_VOLUMES_POOL=volumes
 
-   Configuration file is yet not supported.
-
    Make sure the variables are exported to the environment::
 
       printenv | grep CMP_
 
-   If the command didn't show anything source your rc files or relogin.
-
 6. Prepare network::
 
       virsh net-start default

docs/source/pyapi/exceptions.rst

@@ -1,5 +1,5 @@
-``exceptions``
-==============
+``exceptions`` — Exceptions
+===========================
 
 .. automodule:: compute.exceptions
    :members:

docs/source/pyapi/instance/cloud_init.rst

@@ -0,0 +1,5 @@
+``cloud_init``
+==============
+
+.. automodule:: compute.instance.cloud_init
+   :members:

docs/source/pyapi/instance/guest_agent.rst

@@ -3,4 +3,3 @@
 
 .. automodule:: compute.instance.guest_agent
    :members:
-   :special-members: __init__

docs/source/pyapi/instance/index.rst

@@ -1,11 +1,12 @@
-``instance``
-============
+``instance`` — Manage compute instances
+=======================================
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 3
     :caption: Contents:
 
     instance
     guest_agent
     devices
+    cloud_init
     schemas

docs/source/pyapi/instance/instance.rst

@@ -3,4 +3,3 @@
 
 .. automodule:: compute.instance.instance
    :members:
-   :special-members: __init__

docs/source/pyapi/session.rst

@@ -1,6 +1,5 @@
-``session``
-===========
+``session`` — Hypervisor session manager
+========================================
 
 .. automodule:: compute.session
    :members:
-   :special-members: __init__

docs/source/pyapi/storage/index.rst

@@ -1,8 +1,8 @@
-``storage``
-============
+``storage`` — Manage storage pools and volumes
+==============================================
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 3
     :caption: Contents:
 
     pool

docs/source/pyapi/storage/pool.rst

@@ -3,4 +3,3 @@
 
 .. automodule:: compute.storage.pool
    :members:
-   :special-members: __init__

docs/source/pyapi/storage/volume.rst

@@ -3,4 +3,3 @@
 
 .. automodule:: compute.storage.volume
    :members:
-   :special-members: __init__

docs/source/pyapi/utils.rst

@@ -1,5 +1,5 @@
-``utils``
-=========
+``utils`` — Common utils
+========================
 
 ``utils.units``
 ---------------
@@ -19,3 +19,10 @@
 
 .. automodule:: compute.utils.dictutil
    :members:
+
+
+``utils.diskutils``
+-------------------
+
+.. automodule:: compute.utils.diskutils
+   :members: