uncloud/docs/source/introduction/usage.rst

Usage
=====

Start API
----------

.. code-block:: sh

    ucloud api

Host Creation
-------------

Currently, we don't have any host (that runs virtual machines). 
So, we need to create it by executing the following command

.. code-block:: sh
    
    ucloud-cli host create --hostname ungleich.ch --cpu 32 --ram '32GB' --os-ssd '32GB'

You should see something like the following

.. code-block:: json

    {
        "message": "Host Created"
    }

Start Scheduler
---------------
Scheduler is responsible for scheduling VMs on appropriate host.

.. code-block:: sh

    ucloud scheduler

Start Host
----------
Host is responsible for handling the following actions

* Start VM.
* Stop VM.
* Create VM.
* Delete VM.
* Migrate VM.
* Manage Network Resources needed by VMs.

It uses a hypervisor such as QEMU to perform these actions.

To start host we created earlier, execute the following command

.. code-block:: sh

    ucloud host ungleich.ch

Create OS Image
---------------
First, we need to upload the file.

.. code-block:: sh

    mkdir /var/www/admin
    (cd /var/www/admin && wget http://[2a0a:e5c0:2:12:0:f0ff:fea9:c3d9]/alpine-untouched.qcow2)

Run File Scanner and Image Scanner
------------------------------------
Currently, our uploaded file *alpine-untouched.qcow2* is not tracked by ucloud. We can only make
images from tracked files. So, we need to track the file by running File Scanner

.. code-block:: sh

    ucloud filescanner

File Scanner would run, scan your uploaded image and track it. You can check whether your image
is successfully tracked by executing the :code:`ucloud-cli user files`, It will return something like the following

.. _list-user-files:

.. code-block:: json

    {
        "message": [
            {
                "filename": "alpine-untouched.qcow2",
                "uuid": "3f75bd20-45d6-4013-89c4-7fceaedc8dda"
            }
        ]
    }

Our file is now being tracked by ucloud. Lets create an OS image using the uploaded file.

An image belongs to an image store. There are two types of store

* Public Image Store
* Private Image Store (Not Implemented Yet)

.. note::
    **Quick Quiz** Have we create an image store yet?

The answer is **No, we haven't**. Creating an example image store is very easy.
Just execute the following command

.. code-block:: sh

    pipenv run python ~/ucloud/api/create_image_store.py

An image store (with name = "images") would be created. Now, we are fully ready for creating our
very own image. Executing the following command to create image using the file uploaded earlier

.. code-block:: sh

    ucloud-cli image create-from-file --name alpine --uuid 3f75bd20-45d6-4013-89c4-7fceaedc8dda --image-store-name images

Please note that your **uuid** would be different. See :ref:`List of user files <list-user-files>`.

Now, ucloud have received our request to create an image from file. We have to run Image Scanner to make the image.

.. code-block:: sh

    ucloud imagescanner

To make sure, that our image is create run :code:`ucloud-cli image list --public`. You would get 
output something like the following

.. code-block:: json
    
    {
        "images": [
            {
                "name": "images:alpine",
                "status": "CREATED"
            }
        ]
    }

Create VM
---------

The following command would create a Virtual Machine (name: meow) with following specs

* CPU: 1
* RAM: 1GB
* OS-SSD: 4GB
* OS: Alpine Linux

.. code-block:: sh

    ucloud-cli vm create --vm-name meow --cpu 1 --ram '1gb' --os-ssd '4gb' --image images:alpine

Check VM Status
---------------

.. code-block:: sh

    ucloud-cli vm status --vm-name meow


.. code-block:: json

    {
        "hostname": "/v1/host/74c21c332f664972bf5078e8de080eea",
        "image_uuid": "3f75bd20-45d6-4013-89c4-7fceaedc8dda",
        "in_migration": null,
        "log": [
            "2019-11-12T09:11:09.800798 - Started successfully"
        ],
        "metadata": {
            "ssh-keys": []
        },
        "name": "meow",
        "network": [],
        "owner": "admin",
        "owner_realm": "ungleich-admin",
        "specs": {
            "cpu": 1,
            "hdd": [],
            "os-ssd": "4.0 GB",
            "ram": "1.0 GB"
        },
        "status": "RUNNING",
        "vnc_socket": "/tmp/tmpj1k6sdo_"
    }

Create Network
--------------

.. code-block:: sh

    ucloud-cli network create --network-name mynet --network-type vxlan


.. code-block:: json

    {
        "message": "Network successfully added."
    }

Create VM using this network

.. code-block:: sh

    ucloud-cli vm create --vm-name meow2 --cpu 1 --ram '1gb' --os-ssd '4gb' --image images:alpine --network mynet