From 69affb3fbd8e0ed6621bbe326357ed76d1e4d29a Mon Sep 17 00:00:00 2001 From: Ahmed Bilal Khalid Date: Mon, 16 Sep 2019 16:41:18 +0500 Subject: [PATCH] more stuff added --- Userguide.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 197 insertions(+), 4 deletions(-) diff --git a/Userguide.md b/Userguide.md index 8664278..d868ce3 100644 --- a/Userguide.md +++ b/Userguide.md @@ -10,7 +10,7 @@ To install `ucloud-cli` you need to execute the following commands. Make sure you have [Python 3.7](https://www.python.org/) and [pipenv](https://pypi.org/project/pipenv/) installed. -1. Clone `ucloud-cli` git repository. `ucloud-cli` is needed to talk with ucloud backend i.e create/delete/start/stop VM, attach network to VM etc. +1. Clone `ucloud-cli` git repository. `ucloud-cli` is needed to talk with ucloud backend i.e create/deleteTO_BE_/start/stop VM, attach network to VM etc. ```bash git clone https://code.ungleich.ch/ungleich-public/ucloud-cli.git ``` @@ -47,7 +47,84 @@ To install `ucloud-cli` you need to execute the following commands. Make sure yo vm ``` -## Examples +## Usage Examples +*If you are reading this it means that you are testing ucloud before its general public release. So, this document assume that you are both maintainer (person who install/manage ucloud installation) and enduser of ucloud.* + +### Create Image From File + + +The first step after installation of ucloud is to create a base image on which VMs would base themself. To do this, perform the following steps + +1. Upload a **.qcow2** OS image under /var/www/$username where $username would be your username. +2. Wait for few seconds so that your image/file get tracked by ucloud-file-scanner +3. Now, list all of your files. You can do this by executing `python ucloud.py user files --name $username --realm $realm --seed $seed`. A sample output is given below + ```json + { + "message": [ + { + "filename": "alpine.qcow2", + "uuid": "aa323e6a-2479-4554-b2b2-7a2eb1b9952f" + }, + ] + } + ``` +4. As, you can see we uploaded alpine.qcow2 image. You can upload any image as far as it is in qcow2 format. +5. Now, execute the following command to ask ucloud to create base image and make it publicly available for other as well. + ```shell + python ucloud.py image create-from-file --name alpineLinux --uuid aa323e6a-2479-4554-b2b2-7a2eb1b9952f ----image_store_name images + ``` +6. If you list public images at this point by executing the command `python ucloud.py image list --public` you would get something like this +```json +{ + "aa323e6a-2479-4554-b2b2-7a2eb1b9952f": { + "filename": "alpine.qcow2", + "name": "alpine", + "owner": "ahmedbilal-admin", + "status": "TO_BE_CREATED", + "store_name": "images", + "visibility": "public" + } +} +``` +Note the **TO_BE_CREATED** status. It means that it is not yet to be available to use. + +7. If you wait for few seconds and run the command again you would see something like this if everything goes correctly. +```json +{ + "aa323e6a-2479-4554-b2b2-7a2eb1b9952f": { + "filename": "alpine.qcow2", + "name": "alpine", + "owner": "ahmedbilal-admin", + "status": "CREATED", + "store_name": "images", + "visibility": "public" + } +} +``` +It means that the image is available for consumption now. + + +### List Public Base Images (OS Images) +Execute the following command to get list of all publicly available base images. Then, you can use these images to create a VM for yourself. + +```bash +python ucloud.py image list --public +``` + +Sample output is as follows + +```json +{ + "aa323e6a-2479-4554-b2b2-7a2eb1b9952f": { + "filename": "alpine.qcow2", + "name": "alpine", + "owner": "ahmedbilal-admin", + "status": "CREATED", + "store_name": "images", + "visibility": "public" + } +} +``` ### Create VM @@ -89,7 +166,7 @@ To install `ucloud-cli` you need to execute the following commands. Make sure yo 4. Run the following command to create your VM. ```bash - python ucloud vm create --name {YOUR_USERNAME} --realm {YOUR_REALM} --seed {YOUR_SEED} --specs specs.json --image_uuid 253286ee-5a74-4747-808d-e47d7c3ce4ed + python ucloud.py vm create --name $username --realm $realm --seed $seed --specs specs.json --image_uuid 253286ee-5a74-4747-808d-e47d7c3ce4ed ``` It will show something like the following @@ -98,4 +175,120 @@ To install `ucloud-cli` you need to execute the following commands. Make sure yo { "message": "VM Creation Queued" } - ``` \ No newline at end of file + ``` + +### Start/Stop/Delete a VM + +1. First you need to know the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) of a vm to start/stop/delete it +2. For that, you would need to list your vms. You can do this by executing the following command + ```bash + python ucloud.py user vms --name $username --realm $realm --seed $seed + ``` + It will show list of your VMs and their details. Sample output is as follow + ```json + { + "message": [ + { + "hostname": "/v1/host/cc7f5d199c2a419eb103c2bf10d9ca79", + "specs": { + "cpu": 2, + "hdd": 10000000000, + "ram": 2000000000 + }, + "status": "STOPPED", + "vm_uuid": "dbe8810e7a224aaea93929c4cee0ccea" + } + ] + } + ``` +3. Now, we got VM's UUID. So, we can start/stop/delete it. Execute, the following command to start/stop/delete the vm. + + **Note:** Replace the $action with either **start**, **stop** or **delete**. + + ```bash + python ucloud.py vm $action --uuid dbe8810e7a224aaea93929c4cee0ccea --name $username --realm $realm --seed $seed + ``` + + It would show something like the following + ```json + { + "message": "VM $action Queued" + } + ``` + +### Get Status of a VM +Run the following command to get detailed status of a VM +```bash +python ucloud.py vm status --uuid dbe8810e7a224aaea93929c4cee0ccea +``` +Sample output is as follow. + +```json +{ + "owner": "ahmedbilal-admin", + "specs": { + "cpu": 2, + "ram": 2000000000, + "hdd": 10000000000 + }, + "hostname": "/v1/host/cc7f5d199c2a419eb103c2bf10d9ca79", + "status": "RUNNING", + "image_uuid": "aa323e6a-2479-4554-b2b2-7a2eb1b9952f", + "log": [ + "2019-09-10T12:23:06.371173 - Started successfully" + ], + "in_migration": False, + "key": "/v1/vm/dbe8810e7a224aaea93929c4cee0ccea", + "storage_attachment": [] +} +``` + + +### List VMs + +Run the following command +```bash +python ucloud.py user vms --name $username --realm $realm --seed $seed +``` + +It would show your VMs. Sample output is as follow. +```json + { + "message": [ + { + "hostname": "/v1/host/cc7f5d199c2a419eb103c2bf10d9ca79", + "specs": { + "cpu": 2, + "hdd": 10000000000, + "ram": 2000000000 + }, + "status": "STOPPED", + "vm_uuid": "dbe8810e7a224aaea93929c4cee0ccea" + } + ] + } +``` + +### List Files + +Run the following command +```bash +python ucloud.py user files --name $username --realm $realm --seed $seed +``` + +It would show all of your files. Sample output is as follow. +```json + { + "message": [ + { + "filename": "alpine.qcow2", + "uuid": "aa323e6a-2479-4554-b2b2-7a2eb1b9952f" + }, + { + "filename": "meow.py", + "uuid": "acc4fead-9536-4bdd-bf5d-23856ef94434" + } + ] + } +``` +