Backups are storage devices containing a point-in-time snapshot of a normal storage disk. Taking backups is a good way to preserve data when making system critical changes or just as assurance. A previous state of a normal storage can be restored from any of its backups. Backups can also be cloned to create a new normal storage device. Backups are created either manually on-demand or automatically using backup rules.

This article explains how the backup functions can be used by employing the UpCloud API authenticated with your Base64 encoded credentials. If you are not yet entirely familiar with the usage of the API, take a look at the article for Getting Started with UpCloud API.

Creating on-demand backup

Taking an on-demand backup is fast and simple. The following POST request allows you to create a new backup disk of a specific storage device identified by the storage UUID. Include a title in the body of the request, as shown in the example below, to give a name or description to the backup device.

POST /1.2/storage/<Storage_UUID>/backup
{
    "storage": {
        "title": "Manually created backup"
    }
}

In response to a successful operation, you will get the details of the new backup storage.

Setting up automated backups

Configuring an automated backup schedule works by modifying a storage device to add a backup_rules segment with a PUT request. These rules define how often a backup is taken, at what time of the day should the backup be stored, and how long each backup is kept before automated deletion. The following parameters are accepted in the backup rules.

"interval": "daily / mon / tue / wed / thu / fri / sat / sun"
"time": "0000-2359"
"retention": "1-1095"

The example backup rule below will set up a weekly backup taken every Saturday morning at 4:30 and retained for 8 days.

PUT /1.2/storage/<Storage_UUID>
{
    "storage": {
        "backup_rule": {
            "interval": "sat",
            "time": "0430",
            "retention": "8"
        }
    }
}

The currently active backup rules will show up in the storage details.

GET /1.2/storage/<Storage_UUID>

Restoring a backup

The main method of restoring backups is, in essence, reverting the storage disk back to the same state it was when the backup was taken.

You can get a list of all of your backup storages with the GET request below.

GET /1.2/storage/backup

When restoring a backup, the server that the origin storage is attached to must first be shut down and in the stopped state. To find out the correct server UUID, use the following GET request with the storage UUID, as indicated by the origin in the backup, to fetch the full details of the disk you wish to restore.

GET /1.2/storage/<Storage_UUID>
{
    "storage": {
        ...
        "servers": {
            "server": [
                "00e46b2e-0909-4e77-8acb-4b21e75cb5b9"
            ]
        },
        ...
    }
}

Then stop the server in preparation for the restore.

POST /1.2/server/<Server_UUID>/stop

Once the server has been powered down, use the following POST request while replacing the <Backup_UUID> with the UUID of the backup wish to restore.

POST /1.2/storage/<Backup_UUID>/restore

Restoring a backup will only take a moment depending on the size of the storage device. Once completed, you can restart the server again with the storage disk reverted to the backup state. Although the initial restore is fast, the new storage state must finish a background synchronisation before further actions, for example taking a new backup, can be made.

Cloning a new disk from a backup

Sometimes you might not want or be able to shut down the server the origin storage is attached to, yet you would need to get access to the files stored in a backup. This can be done by cloning the backup disk to create an entirely new storage device.

Backup disks are treated much the same as any other storage device. You can clone any backup storage using the following POST request.

Take care when choosing the target zone for cloning a storage disk. While cloning within one zone is quick, operations between different zones can be time-consuming.

POST /1.2/storage/<Backup_UUID>/clone
{
    "storage" : {
        "zone" : "fi-hel1",
        "tier" : "maxiops",
        "title" : "Clone of a backup disk"
    }
}

The response will return you the details of the newly clone storage device, such as its UUID. Then to access the backup files, attach the new disk to an existing server or deploy a new host using the storage disk instead of a public template.

Summary

Managing your backups using the UpCloud API is really quite simple and easy to implement in any programming language with support for HTTP libraries. Check out the full API Documentation to learn more about the features the UpCloud API offers.