uncloud/ucloud-docs
2
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
ucloud-docs/Userguide.md

309 lines
9.5 KiB
Markdown
Raw Normal View History

Add Userguide.md
2019-09-11 14:53:16 +00:00
# ucloud User Guide
a
2019-09-17 09:00:43 +00:00
## 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/)
Add Userguide.md
2019-09-11 14:53:16 +00:00
## Pre-requisite
a
2019-09-17 09:00:43 +00:00
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).
Add Userguide.md
2019-09-11 14:53:16 +00:00
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.
a
2019-09-16 17:20:03 +00:00
1. Clone `ucloud-setup` git repository.
Add Userguide.md
2019-09-11 14:53:16 +00:00
```bash
a
2019-09-16 17:20:03 +00:00
git clone https://code.ungleich.ch/ucloud/ucloud-setup.git
Add Userguide.md
2019-09-11 14:53:16 +00:00
```
2. Change your directory to recently cloned repository.
```bash
a
2019-09-16 17:20:03 +00:00
cd ucloud-setup
Add Userguide.md
2019-09-11 14:53:16 +00:00
```
a
2019-09-16 17:20:03 +00:00
3. Install dependencies of `ucloud-setup`
Add Userguide.md
2019-09-11 14:53:16 +00:00
```bash
pipenv install
```
a
2019-09-16 17:20:03 +00:00
4. Execute the following command to install ucloud
Add Userguide.md
2019-09-11 14:53:16 +00:00
```bash
a
2019-09-16 17:20:03 +00:00
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
Add Userguide.md
2019-09-11 14:53:16 +00:00
pipenv shell
```
a
2019-09-16 17:20:03 +00:00
6. Run the following command to ensure that you have successfully installed `ucloud-cli`
Add Userguide.md
2019-09-11 14:53:16 +00:00
```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
```
more stuff added
2019-09-16 11:41:18 +00:00
## 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"
}
}
```
Add Userguide.md
2019-09-11 14:53:16 +00:00
### 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
more stuff added
2019-09-16 11:41:18 +00:00
python ucloud.py vm create --name $username --realm $realm --seed $seed --specs specs.json --image_uuid 253286ee-5a74-4747-808d-e47d7c3ce4ed
Add Userguide.md
2019-09-11 14:53:16 +00:00
```
It will show something like the following
```json
{
"message": "VM Creation Queued"
}
more stuff added
2019-09-16 11:41:18 +00:00
```
### 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"
}
]
}
```
Reference in a new issue Copy permalink