This article describes some of the features of the UpCloud API and how you can go about creating servers with API requests rather than using the UpCloud Control Panel. For more details about the requests used in this article can be found in the API documentation.

There are three ways to create a cloud server using the API:

  • from a public template
  • by cloning an existing storage device
  • by installing an OS manually using installation media

All of the methods use a POST /1.2/server requests with the Base64 authentication. To define the finer details, you will need to enter a few required parameters in the request body.

If you are not yet familiar with the UpCloud API, we would suggest taking a quick look at Getting Started with UpCloud API to set up your API user account and access rights.

Creating a server from a template

Deploying a new server using a public template is basically an operation to clone a templated operating system image on a new storage device of the desired size and type. You can get a list of the public templates with their UUIDs using the following request.

GET /1.2/storage/template

The body of a POST request to create a new server should contain the necessary details of the virtual machine and at least one storage devices for the operating system. The example request below uses the Debian 8 Jessie public template to deploy a server with 1CPU core, 1GB RAM, and 30GB storage which corresponds to the smallest preconfigured plan.

POST /1.2/server
{
    "server": {
        "zone": "fi-hel1",
        "title": "API Deploy Test",
        "hostname": "example.upcloud.com",
        "plan": "1xCPU-1GB",
        "storage_devices": {
            "storage_device": [
                {
                    "action": "clone",
                    "storage": "01000000-0000-4000-8000-000020030100",
                    "title": "example.upcloud.com-disk0",
                    "size": 30,
                    "tier": "maxiops"
                }
            ]
        }
    }
}

The other available plans can be seen with the following GET request.

GET /1.2/plan

Cloud servers deployed with a matching plan configuration are priced according to the preconfigured plans. In addition to the listed plans servers can also be freely configured with a custom plan which allows greater flexibility with the CPU, memory, and storage resources.

Cloning an existing storage device

Cloning an existing storage is very similar to deploying a server from a template. In comparison to the previous method, you just need to change the storage UUID from a public template to another storage device on your UpCloud account. You can clone any storage that you have access rights to as long as the storage is not currently in use.

You can get a list of your storage devices with the next GET request.

GET /1.2/storage/private

As mentioned above, a storage device you wish to use as a source for a cloning operation cannot be running during the process. Shut down the source server with the following request.

POST /1.2/server/<Server_UUID>/stop

Once the source server has been powered down, you can deploy a new host by cloning the storage disk. Enter the example request body to your query and replace the <Storage_UUID> with the desired source device.

POST /1.2/server
{
    "server": {
        "zone": "fi-hel1",
        "title": "API Cloning Test",
        "hostname": "clone.example.upcloud.com",
        "plan": "1xCPU-1GB",
        "storage_devices": {
            "storage_device": [
                {
                    "action": "clone",
                    "storage": "<Storage_UUID>",
                    "title": "example.upcloud.com-disk0-clone0"
                    "tier": "maxiops"
                }
            ]
        }
    }
}

Cloning will take a moment depending on the size of the source storage device. Until cloning is complete, both servers will be in the maintenance state.

Once the cloning process has finished, you can start the source server again with the following POST request.

POST /1.2/server/<Server_UUID>/start

Take care when cloning large storage devices. Cloning between zones can take some time and the source host must remain powered down during the process. A way to get around this is to first clone the disk within the current zone, which is much faster, then use the clone as a source when sending the data to a new zone.

Creating a server from installation media

In addition to the public templates, a server can also be deployed using the available installation media of various operating systems. For example, Arch, Fedora and Knoppix are available as CDROMs that can be used to install the OS manually.

You can get a list of CDROM UUIDs with the GET request underneath.

GET /1.2/storage/cdrom

When you have chosen the CDROM you wish to use to install a new server, run the following POST request with two storage devices; one blank disk with the size and tier you wish, and second with the CDROM UUID and type.

To have the server boot from the CDROM, set the boot order as shown below. You might also wish to enable VNC access to go through the installation later. Otherwise, the Web Console is always available at your UpCloud Control Panel.

POST /1.2/server
{
    "server": {
        "zone": "fi-hel1",
        "title": "API CDROM Deploy Test",
        "hostname": "example.upcloud.com",
        "plan": "1xCPU-1GB",
        "storage_devices": {
            "storage_device" : [
                {
                    "action" : "create",
                    "size" : "30",
                    "title" : "example.upcloud.com-disk0",
                    "tier": "maxiops"
                },
                {
                    "action" : "attach",
                    "storage" : "01000000-0000-4000-8000-000070010101",
                    "type" : "cdrom"
                }
            ]
        },
        "boot_order" : "cdrom,disk",
        "vnc" : "on"
    }
}

Once the server has been created, you will get a reply with the server details as a confirmation including the VNC settings and password. Connect to the new host using the method you prefer and install the operating system.

When you have finished with the installation, power off the server for a moment and detach the CDROM using the POST request below.

POST /1.2/server/<Server_UUID>/storage/detach
{
    "storage_device": {
        "address": "ide:0:0"
    }
}

All done! You can then start the custom installed server again.

What to do next

Now that you have a server up and running, you might wish to set up a backup solution suitable for your use case. Continue on with an article about Managing Backups with UpCloud API, or if you would like to learn more about the requests used in this article check out the Servers section in the API documentation.