302 lines
8.8 KiB
Markdown
302 lines
8.8 KiB
Markdown
# ucloud User Guide
|
|
|
|
## 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.
|
|
|
|
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"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|