UpCloud

Storages

A storage device is a block device similar to a physical hard disk. It can be used to install an operating system or hold other filesystems for a server. Storages can be freely attached to any server within the same zone and under the same account.

A maximum of 16 storage devices can be attached to a server at the same time; however, the combined limit for network interfaces and storage devices is 24.

Storage types

  • Name
    disk
    Description

    Normal storage for operating system and application data. This is the only user-writable storage type.

  • Name
    cdrom
    Description

    Read-only media, typically for server installations or crash recovery.

  • Name
    template
    Description

    Special storage resources used to create new servers with a preconfigured operating system.

  • Name
    backup
    Description

    Point-in-time backup of a normal storage. Can be restored or cloned to create new storage.

Storage tiers

  • Name
    maxiops
    Description

    High performance storage with maximum IOPS.

  • Name
    standard
    Description

    General purpose storage with balanced performance.

  • Name
    hdd
    Description

    High capacity archive storage (called "hdd" in API for backwards compatibility).

Storage access types

  • Name
    public
    Description

    Storages available to all users, such as operating system templates and CD-ROM images.

  • Name
    private
    Description

    Storages owned by the account and only visible to the account owner.

Storage states

  • Name
    online
    Description

    The storage is ready for use. Can be attached or detached.

  • Name
    maintenance
    Description

    Maintenance work is being performed on the storage.

  • Name
    cloning
    Description

    The storage is currently the clone source for another storage.

  • Name
    backuping
    Description

    The storage is currently being backed up.

  • Name
    syncing
    Description

    The storage is synchronizing its data.

  • Name
    error
    Description

    The storage has encountered an error and is inaccessible.

Favorite storages

Storage resources can be tagged as favorites to make them easier to find. Both public and private storages can be added to favorites. Favorite storages can be listed using the /1.3/storage/favorite endpoint.

GET/1.3/storage

List storages

Returns a list of all accessible storages. The list can be filtered by access type, storage type, or favorite status.

Available endpoints

  • Name
    /1.3/storage
    Type
    GET
    Description

    List all storages.

  • Name
    /1.3/storage/public
    Type
    GET
    Description

    List public storages (templates, CD-ROMs).

  • Name
    /1.3/storage/private
    Type
    GET
    Description

    List private storages.

  • Name
    /1.3/storage/normal
    Type
    GET
    Description

    List normal disk storages.

  • Name
    /1.3/storage/backup
    Type
    GET
    Description

    List backup storages.

  • Name
    /1.3/storage/template
    Type
    GET
    Description

    List templates.

  • Name
    /1.3/storage/cdrom
    Type
    GET
    Description

    List CD-ROM images.

  • Name
    /1.3/storage/favorite
    Type
    GET
    Description

    List favorite storages.

Request

GET
/1.3/storage
curl -X GET https://api.upcloud.com/1.3/storage \
  -u your_username:your_password
GET/1.3/storage/{uuid}

Get storage details

Returns detailed information about a specific storage resource, including attached servers and backup information.

Response fields

  • Name
    uuid
    Type
    string
    Description

    Storage unique identifier.

  • Name
    title
    Type
    string
    Description

    Storage title.

  • Name
    size
    Type
    integer
    Description

    Storage size in GiB.

  • Name
    tier
    Type
    string
    Description

    Storage tier (maxiops, standard, hdd).

  • Name
    encrypted
    Type
    string
    Description

    Whether storage is encrypted ("yes" or "no").

  • Name
    servers
    Type
    object
    Description

    List of servers this storage is attached to.

  • Name
    backups
    Type
    object
    Description

    List of backups for this storage.

Request

GET
/1.3/storage/{uuid}
curl -X GET https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e \
  -u your_username:your_password
POST/1.3/storage

Create storage

Creates a new storage resource. Storages are always created in a specific zone.

Required attributes

  • Name
    size
    Type
    integer
    Description

    Storage size in GiB (1-4096).

  • Name
    zone
    Type
    string
    Description

    Zone identifier (e.g., "fi-hel1").

  • Name
    title
    Type
    string
    Description

    Storage title (0-255 characters).

Optional attributes

  • Name
    tier
    Type
    string
    Description

    Storage tier: "maxiops", "standard", or "hdd". Default: "maxiops".

  • Name
    encrypted
    Type
    string
    Description

    Enable encryption: "yes" or "no". Default: "no".

  • Name
    backup_rule
    Type
    object
    Description

    Automatic backup configuration.

  • Name
    labels
    Type
    array
    Description

    Labels for classification.

Request

POST
/1.3/storage
curl -X POST https://api.upcloud.com/1.3/storage \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage": {
      "size": 50,
      "tier": "maxiops",
      "title": "My new storage",
      "zone": "fi-hel1",
      "encrypted": "yes",
      "labels": [
        {"key": "env", "value": "prod"}
      ]
    }
  }'
PUT/1.3/storage/{uuid}

Modify storage

Modifies an existing storage resource. Size can only be increased, not decreased.

Modifiable attributes

  • Name
    title
    Type
    string
    Description

    Storage title.

  • Name
    size
    Type
    integer
    Description

    Storage size (can only be increased).

  • Name
    backup_rule
    Type
    object
    Description

    Automatic backup configuration.

  • Name
    labels
    Type
    array
    Description

    Labels for classification.

Request

PUT
/1.3/storage/{uuid}
curl -X PUT https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage": {
      "title": "Updated storage name",
      "size": 100
    }
  }'
POST/1.3/storage/{uuid}/resize

Resize partition

Resizes the last partition of a storage and the ext3/ext4/XFS/NTFS filesystem on that partition if the partition does not extend to the end of the storage yet.

Before the resize is attempted, a backup is taken from the storage. If the resize succeeds, backup details are returned. It is advisable to keep the backup until you have ensured that everything works after the resize.

If the resize fails, the backup is used to restore the storage to the state where it was before the resize. After that the backup is deleted automatically.

Request

POST
/1.3/storage/{uuid}/resize
curl -X POST https://api.upcloud.com/1.3/storage/017ca4cc-def2-458d-a797-7782959b30a7/resize \
  -u your_username:your_password
POST/1.3/storage/{uuid}/clone

Clone storage

Creates an exact copy of an existing storage resource. The clone can be created in the same zone or a different zone.

Attributes

  • Name
    title
    Type
    string
    Description

    Title for the cloned storage. Required.

  • Name
    zone
    Type
    string
    Description

    Target zone for the clone. Required.

  • Name
    tier
    Type
    string
    Description

    Storage tier for the clone.

  • Name
    encrypted
    Type
    string
    Description

    Enable encryption: "yes" or "no".

Request

POST
/1.3/storage/{uuid}/clone
curl -X POST https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/clone \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage": {
      "title": "Cloned storage",
      "zone": "de-fra1",
      "tier": "maxiops"
    }
  }'
POST/1.3/storage/{uuid}/cancel

Cancel storage operation

Cancels a running cloning operation and deletes the incomplete copy.

A running cloning operation can be cancelled if it is taking too long or was not intentional. Cancelling the cloning will stop the operation, remove the incomplete new storage and return the source storage back to online state.

Note that it might take several seconds for the source storage to reset back to online state after the cancellation request is completed.

Request

POST
/1.3/storage/{uuid}/cancel
curl -X POST https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/cancel \
  -u your_username:your_password
POST/1.3/server/{server_uuid}/storage/attach

Attach storage

Attaches a storage device to a server. The storage must be in the same zone as the server.

Attributes

  • Name
    storage
    Type
    string
    Description

    UUID of the storage to attach. Required.

  • Name
    type
    Type
    string
    Description

    Attachment type: "disk" or "cdrom". Default: "disk".

  • Name
    address
    Type
    string
    Description

    Device address (e.g., "virtio:0", "scsi:0:0").

  • Name
    boot_disk
    Type
    string
    Description

    Set as boot disk: "0" or "1".

Request

POST
/1.3/server/{server_uuid}/storage/attach
curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/storage/attach \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage_device": {
      "storage": "01d4fcd4-e446-433b-8a9c-551a1284952e",
      "type": "disk",
      "address": "virtio:1"
    }
  }'
POST/1.3/server/{server_uuid}/storage/detach

Detach storage

Detaches a storage device from a server.

Attributes

  • Name
    address
    Type
    string
    Description

    Device address to detach (e.g., "virtio:1"). Required.

Request

POST
/1.3/server/{server_uuid}/storage/detach
curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/storage/detach \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage_device": {
      "address": "virtio:1"
    }
  }'
POST/1.3/server/{uuid}/cdrom/load

Load CD-ROM

Loads a storage as a CD-ROM in the CD-ROM device of a server.

This operation requires that a CD-ROM device is attached to the server. A CD-ROM device can be attached using the Attach storage operation.

Any storage of type normal or cdrom can be loaded as a CD-ROM.

Attributes

  • Name
    storage
    Type
    string
    Description

    UUID of a storage of type "normal" or "cdrom" to load. Required.

Request

POST
/1.3/server/{uuid}/cdrom/load
curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/cdrom/load \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage_device": {
      "storage": "01000000-0000-4000-8000-000060010101"
    }
  }'
POST/1.3/server/{uuid}/cdrom/eject

Eject CD-ROM

Ejects the storage from the CD-ROM device of a server.

Request

POST
/1.3/server/{uuid}/cdrom/eject
curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/cdrom/eject \
  -u your_username:your_password
POST/1.3/storage/{uuid}/import

Create import

Creates an import task to import data into an existing storage. If the storage has been attached to a server, the server must be in stopped state.

The supported data type is raw (extension .raw, .img or .iso). The data can be compressed with GZip or XZ (Content-Types application/gzip and application/x-xz).

Note that the size of the data to be imported cannot exceed the size of the storage.

Import modes

  • Name
    http_import
    Description

    Import from a publicly reachable HTTP server. Requires source_location to be set to the URL.

  • Name
    direct_upload
    Description

    Data is pushed directly to a temporary URL returned in direct_upload_url.

Attributes

  • Name
    source
    Type
    string
    Description

    Import mode: "http_import" or "direct_upload". Required.

  • Name
    source_location
    Type
    string
    Description

    URL to import from (required for http_import mode).

Request

POST
/1.3/storage/{uuid}/import
curl -X POST https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/import \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage_import": {
      "source": "http_import",
      "source_location": "https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-12.0.0-amd64-netinst.iso"
    }
  }'
GET/1.3/storage/{uuid}/import

Get import details

Returns detailed information of an ongoing or finished import task. If the task is in progress, the counter values and state reflect the current state of the import.

Import states

  • Name
    prepared
    Description

    The task has been submitted. Initial state.

  • Name
    pending
    Description

    The task is waiting for data transfer to start.

  • Name
    importing
    Description

    The data is being written.

  • Name
    completed
    Description

    The import task was completed successfully.

  • Name
    failed
    Description

    The import task failed.

  • Name
    cancelling
    Description

    The import task cancellation was requested.

  • Name
    cancelled
    Description

    The import task was cancelled.

Request

GET
/1.3/storage/{uuid}/import
curl -X GET https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/import \
  -u your_username:your_password
POST/1.3/storage/{uuid}/import/cancel

Cancel import

Cancels an ongoing import task. The task will transition into cancelling state.

Once the import task has been fully cancelled, the storage will transition into syncing or online state depending on whether any data has been written. If data was written, the storage contents will be rolled back to the state before starting the import task.

Request

POST
/1.3/storage/{uuid}/import/cancel
curl -X POST https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/import/cancel \
  -u your_username:your_password
POST/1.3/storage/{uuid}/backup

Create backup

Creates a point-in-time backup of a storage resource.

Attributes

  • Name
    title
    Type
    string
    Description

    Title for the backup. Required.

Request

POST
/1.3/storage/{uuid}/backup
curl -X POST https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/backup \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage": {
      "title": "Manual backup 2024-01-15"
    }
  }'
POST/1.3/storage/{uuid}/restore

Restore backup

Restores the contents of a backup to the original storage. The target storage will be overwritten.

Request

POST
/1.3/storage/{uuid}/restore
curl -X POST https://api.upcloud.com/1.3/storage/01287ad1-496c-4b5f-bb67-0fc2e3494740/restore \
  -u your_username:your_password
POST/1.3/storage/{uuid}/templatize

Templatize storage

Creates a template from an existing storage. Templates can be used to create new servers.

The speed of the operation depends on the size of the storage. Templates can be created from any MaxIOPS, Standard or Archive block storage device. Deployments from custom templates are restricted to use the same storage tier.

Attributes

  • Name
    title
    Type
    string
    Description

    Title for the template. Required.

Request

POST
/1.3/storage/{uuid}/templatize
curl -X POST https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/templatize \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "storage": {
      "title": "My custom template"
    }
  }'
POST/1.3/storage/{uuid}/favorite

Add to favorites

Adds a storage to the list of favorite storages. To list favorite storages, use the /1.3/storage/favorite endpoint.

This operation succeeds even if the storage is already on the list of favorites.

Request

POST
/1.3/storage/{uuid}/favorite
curl -X POST https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/favorite \
  -u your_username:your_password
DELETE/1.3/storage/{uuid}/favorite

Remove from favorites

Removes a storage from the list of favorite storages.

This operation succeeds even if the storage is not on the list of favorites.

Request

DELETE
/1.3/storage/{uuid}/favorite
curl -X DELETE https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e/favorite \
  -u your_username:your_password
DELETE/1.3/storage/{uuid}

Delete storage

Deletes a storage resource. The storage must be detached from all servers before deletion.

The state of the storage must be online. The storage must not be attached to any server.

Query parameters

  • Name
    backups
    Type
    string
    Description

    Backup deletion policy: "keep" (default), "keep_latest", or "delete".

Request

DELETE
/1.3/storage/{uuid}
curl -X DELETE "https://api.upcloud.com/1.3/storage/01d4fcd4-e446-433b-8a9c-551a1284952e?backups=delete" \
  -u your_username:your_password