uncloud/docs/source/theory/summary.rst

Summary
=======

.. image:: /images/ucloud.svg

.. code-block::

                              <cli>
                                |
                                |
                                |
    +-------------------------<api>
    |                           |
    |           |```````````````|```````````````|
    |           |               |               |
    |     <file_scanner>    <scheduler>   <image_scanner>
    |                           |
    |                           |
    +-------------------------<host>
                                |
                                |
                                |
                         Virtual Machine------<init>------<metadata>



**ucloud-cli** interact with **ucloud-api** to do the following operations:

- Create/Delete/Start/Stop/Migrate/Probe (Status of) Virtual Machines
- Create/Delete Networks
- Add/Get/Delete SSH Keys
- Create OS Image out of a file (tracked by file_scanner)
- List User's files/networks/vms
- Add Host

ucloud can currently stores OS-Images on

* File System
* `CEPH <https://ceph.io/>`_


**ucloud-api** in turns creates appropriate Requests which are taken
by suitable components of ucloud. For Example, if user uses ucloud-cli
to create a VM, **ucloud-api** would create a **ScheduleVMRequest** containing
things like pointer to VM's entry which have specs, networking
configuration of VMs.

**ucloud-scheduler** accepts requests for VM's scheduling and
migration. It finds a host from a list of available host on which
the incoming VM can run and schedules it on that host.

**ucloud-host** runs on host servers i.e servers that
actually runs virtual machines, accepts requests
intended only for them. It creates/delete/start/stop/migrate
virtual machines. It also arrange network resources needed for the
incoming VM.

**ucloud-filescanner** keep tracks of user's files which would be needed
later for creating OS Images.

**ucloud-imagescanner** converts images files from qcow2 format to raw
format which would then be imported into image store.

* In case of **File System**, the converted image would be copied to
  :file:`/var/image/` or the path referred by :envvar:`IMAGE_PATH` environement variable
  mentioned in :file:`/etc/ucloud/ucloud.conf`.

* In case of **CEPH**, the converted image would be imported into
  specific pool (it depends on the image store in which the image
  belongs) of CEPH Block Storage.

**ucloud-metadata** provides metadata which is used to contextualize
VMs. When, the VM is created, it is just clone (duplicate) of OS
image from which it is created. So, to differentiate between my
VM and your VM, the VM need to be contextualized. This works
like the following

.. note::
    Actually, ucloud-init makes the GET request. You can also try it
    yourself using curl but ucloud-init does that for yourself.

* VM make a GET requests http://metadata which resolves to actual
  address of metadata server. The metadata server looks at the IPv6
  Address of the requester and extracts the MAC Address which is possible
  because the IPv6 address is
  `IPv6 EUI-64 <https://community.cisco.com/t5/networking-documents/understanding-ipv6-eui-64-bit-address/ta-p/3116953>`_.
  Metadata use this MAC address to find the actual VM to which it belongs
  and its owner, ssh-keys and much more. Then, metadata return these
  details back to the calling VM in JSON format. These details are
  then used be the **ucloud-init** which is explained next.

**ucloud-init** gets the metadata from **ucloud-metadata** to contextualize
the VM. Specifically, it gets owner's ssh keys (or any other keys the
owner of VM added to authorized keys for this VM) and put them to ssh
server's (installed on VM) authorized keys so that owner can access
the VM using ssh. It also install softwares that are needed for correct
behavior of VM e.g rdnssd (needed for `SLAAC <https://en.wikipedia.org/wiki/IPv6#Stateless_address_autoconfiguration_(SLAAC)>`_).