Deploying Cloud Servers using the UpCloud API

This article describes some of the features of the UpCloud API and how you can go about deploying a server with API requests rather than using the UpCloud Control Panel. 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 POST /1.3/server requests, authenticated with an API token. 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 suggest taking a quick look at our guide to getting started with UpCloud API to create an API token.

Creating a server from a template

Deploying a 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.3/storage/template

The body of a POST request to create a new server should contain the necessary details of the cloud server and at least one storage device for the operating system. The example request below uses the Ubuntu Server 26.04 LTS public template to deploy a server with 1 CPU core, 1 GB RAM, and 25 GB storage, which matches the PREMIUM-1xCPU-1GB plan. Replace ssh-ed25519 AAAA... with your public SSH key.

Public templates that use cloud-init, such as Ubuntu Server 26.04 LTS, require metadata to be enabled for server creation, and you log in to them with an SSH key. If you do not wish to use the metadata feature, it can be disabled after server creation.

POST /1.3/server
{
    "server": {
        "zone": "fi-hel1",
        "title": "API Deploy Test",
        "hostname": "example.upcloud.com",
        "metadata" : "yes",
        "plan": "PREMIUM-1xCPU-1GB",
        "login_user": {
            "username": "root",
            "ssh_keys": {
                "ssh_key": [
                    "ssh-ed25519 AAAA..."
                ]
            }
        },
        "storage_devices": {
            "storage_device": [
                {
                    "action": "clone",
                    "storage": "01000000-0000-4000-8000-000030260200",
                    "title": "example.upcloud.com-disk0",
                    "size": 25,
                    "tier": "maxiops"
                }
            ]
        }
    }
}

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

GET /1.3/plan

Cloud servers deployed with a matching plan configuration are priced according to the monthly 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 from an existing storage device

Cloning an existing storage device is very similar to deploying a server from a template. Compared 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.3/storage/private

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

POST /1.3/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.3/server
{
    "server": {
        "zone": "fi-hel1",
        "title": "API Cloning Test",
        "hostname": "clone.example.upcloud.com",
        "plan": "PREMIUM-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.3/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, and 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, Debian, FreeBSD, and Rocky Linux are available as CDROMs that can be used to install the OS manually at first boot.

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

GET /1.3/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 the second with the CDROM UUID and type. The example uses the Debian 13.1.0 installation CD.

To have the server boot from the CDROM, set the boot order as shown below.

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

Once the server has been created, you will get a reply with the server details as a confirmation. You can go through the installation in the web console in the UpCloud Control Panel, or turn on VNC access to use your own VNC client with the following request.

PUT /1.3/server/server_UUID
{
    "server": {
        "remote_access_enabled": "yes"
    }
}

The reply includes the VNC address and port in remote_access_host and remote_access_port, and the password in remote_access_password. Connect to the new host using the method you prefer and install the operating system.

When you have finished with the installation, stop the server. IDE devices such as the CDROM can only be detached from a stopped server. If the server doesn't stop, for example because the installer is still running, use a hard stop.

POST /1.3/server/server_UUID/stop
{
    "stop_server": {
        "stop_type": "hard"
    }
}

Then detach the CDROM using the POST request below.

POST /1.3/server/server_UUID/storage/detach
{
    "storage_device": {
        "address": "ide:0:0"
    }
}

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

The VNC port is only kept while the server is running. To use VNC after the server has been stopped or restarted, set remote_access_enabled to no and then back to yes with the PUT request above, and connect to the new port in the reply.

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.