9.5 KiB

Raw Blame History

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

Pre-requisite

You need to have an Account at accounts.ungleich.ch. If you don't have it create one here.
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 and pipenv installed.

Clone ucloud-setup git repository.

git clone https://code.ungleich.ch/ucloud/ucloud-setup.git

Change your directory to recently cloned repository.
```
cd ucloud-setup
```
Install dependencies of ucloud-setup
```
pipenv install
```

Execute the following command to install ucloud

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

Go to ucloud-cli

cd ../ucloud-cli
pipenv install
pipenv shell

Run the following command to ensure that you have successfully installed ucloud-cli
```
python ucloud.py
```
If the output looks somewhat similar to this then you have successfully installed ucloud-cli
```
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

Upload a .qcow2 OS image under /var/www/$username where $username would be your username.
Wait for few seconds so that your image/file get tracked by ucloud-file-scanner

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

{
    "message": [
        {
            "filename": "alpine.qcow2",
            "uuid": "aa323e6a-2479-4554-b2b2-7a2eb1b9952f"
        },
    ]
}

As, you can see we uploaded alpine.qcow2 image. You can upload any image as far as it is in qcow2 format.

Now, execute the following command to ask ucloud to create base image and make it publicly available for other as well.

python ucloud.py image create-from-file --name alpineLinux --uuid aa323e6a-2479-4554-b2b2-7a2eb1b9952f ----image_store_name images

If you list public images at this point by executing the command python ucloud.py image list --public you would get something like this

{
    "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.

If you wait for few seconds and run the command again you would see something like this if everything goes correctly.

{
    "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.

python ucloud.py image list --public

Sample output is as follows

{
    "aa323e6a-2479-4554-b2b2-7a2eb1b9952f": {
        "filename": "alpine.qcow2",
        "name": "alpine",
        "owner": "ahmedbilal-admin",
        "status": "CREATED",
        "store_name": "images",
        "visibility": "public"
    }
}

Create VM

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.
```
{
    "cpu": 2,
    "ram": "2GB",
    "hdd": "10GB"
}
```

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.

python ucloud.py image list --public

It will show list of available images. Sample output

{
    "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"
    }
}

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.

Run the following command to create your VM.

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

{
    "message": "VM Creation Queued"
}

Start/Stop/Delete a VM

First you need to know the UUID of a vm to start/stop/delete it

For that, you would need to list your vms. You can do this by executing the following command

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

{
    "message": [
        {
            "hostname": "/v1/host/cc7f5d199c2a419eb103c2bf10d9ca79",
            "specs": {
                "cpu": 2,
                "hdd": 10000000000,
                "ram": 2000000000
            },
            "status": "STOPPED",
            "vm_uuid": "dbe8810e7a224aaea93929c4cee0ccea"
        }
    ]
}

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.
```
python ucloud.py vm $action --uuid dbe8810e7a224aaea93929c4cee0ccea --name $username --realm $realm --seed $seed
```
It would show something like the following
```
{
    "message": "VM $action Queued"
}
```

Get Status of a VM

Run the following command to get detailed status of a VM

python ucloud.py vm status --uuid dbe8810e7a224aaea93929c4cee0ccea

Sample output is as follow.

{
    "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

python ucloud.py user vms --name $username --realm $realm --seed $seed

It would show your VMs. Sample output is as follow.

    {
        "message": [
            {
                "hostname": "/v1/host/cc7f5d199c2a419eb103c2bf10d9ca79",
                "specs": {
                    "cpu": 2,
                    "hdd": 10000000000,
                    "ram": 2000000000
                },
                "status": "STOPPED",
                "vm_uuid": "dbe8810e7a224aaea93929c4cee0ccea"
            }
        ]
    }

List Files