308 lines
9.5 KiB
Markdown
308 lines
9.5 KiB
Markdown
# ucloud User Guide
|
||
|
||
## Introduction
|
||
After years of using OpenNebula, we've seen its beauty, and also its limitations. We couldn’t do everything we wanted with OpenNebula because of its limits, and we were often questioned if we should go for Openstack. As a team of curious and open geeks, we had a look at Openstack - and it looked HUGE, or in other words: very complex. We are UNIX company and we adhere to KISS, so it looked like not really compatible with our philosophy of how we do things.
|
||
|
||
In general what we want is something easy, portable, light, and simple.
|
||
|
||
For more details, See [Lets challenge OpenStack and OpenNebula](https://ungleich.ch/en-us/cms/blog/2019/06/24/lets-challenge-openstack-and-opennebula/)
|
||
|
||
## Pre-requisite
|
||
|
||
1. You need to have an Account at [accounts.ungleich.ch](https://account.ungleich.ch). If you don't have it create one [here](https://account.ungleich.ch).
|
||
|
||
2. Login and click on **SHOW SEEDS** button. On the next page it will show you your seed mentioned next to your user realm.
|
||
|
||
## Installation
|
||
|
||
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-setup` git repository.
|
||
```bash
|
||
git clone https://code.ungleich.ch/ucloud/ucloud-setup.git
|
||
```
|
||
|
||
2. Change your directory to recently cloned repository.
|
||
```bash
|
||
cd ucloud-setup
|
||
```
|
||
3. Install dependencies of `ucloud-setup`
|
||
```bash
|
||
pipenv install
|
||
```
|
||
4. Execute the following command to install ucloud
|
||
```bash
|
||
pipenv run python ucloud-setup.py cli setup --path ../ --api_server $api_server_url --name $username --realm $realm --seed $seed
|
||
```
|
||
It will setup ucloud in the parent directory of `ucloud-setup`
|
||
5. Go to `ucloud-cli`
|
||
```bash
|
||
cd ../ucloud-cli
|
||
pipenv install
|
||
pipenv shell
|
||
```
|
||
6. Run the following command to ensure that you have successfully installed `ucloud-cli`
|
||
```bash
|
||
python ucloud.py
|
||
```
|
||
|
||
If the output looks somewhat similar to this then you have successfully installed `ucloud-cli`
|
||
|
||
```bash
|
||
Usage: ucloud.py [OPTIONS] COMMAND [ARGS]...
|
||
|
||
Options:
|
||
--help Show this message and exit.
|
||
|
||
Commands:
|
||
host
|
||
image
|
||
user
|
||
vm
|
||
```
|
||
|
||
## 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
|
||
|
||
1. Create a file name *specs.json* and put your required VM's specification in it. Save it in `ucloud-cli` directory. A sample is given below.
|
||
```json
|
||
{
|
||
"cpu": 2,
|
||
"ram": "2GB",
|
||
"hdd": "10GB"
|
||
}
|
||
```
|
||
2. Find out which image you want to use by running the following command. Image means the Operating System which you want to use in your VM.
|
||
```bash
|
||
python ucloud.py image list --public
|
||
```
|
||
It will show list of available images. Sample output
|
||
|
||
```json
|
||
{
|
||
"253286ee-5a74-4747-808d-e47d7c3ce4ed": {
|
||
"filename": "alpine.qcow2",
|
||
"name": "alpine",
|
||
"owner": "ahmedbilal-admin",
|
||
"status": "CREATED",
|
||
"store_name": "images",
|
||
"visibility": "public"
|
||
},
|
||
"1245856ee-2345-4747-56798-ejdf72394d": {
|
||
"filename": "devuan.qcow2",
|
||
"name": "devuan",
|
||
"owner": "ahmedbilal-admin",
|
||
"status": "CREATED",
|
||
"store_name": "images",
|
||
"visibility": "public"
|
||
}
|
||
}
|
||
```
|
||
3. Suppose, we want to create our VM with alpine Image. So, we would use uuid of alpine linux i.e **253286ee-5a74-4747-808d-e47d7c3ce4ed**.
|
||
|
||
4. Run the following command to create your VM.
|
||
```bash
|
||
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
|
||
|
||
```json
|
||
{
|
||
"message": "VM Creation Queued"
|
||
}
|
||
```
|
||
|
||
### 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"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|