8. Servers
This chapter describes operations for creating and managing servers on UpCloud. A server is a single virtual machine instance running on UpCloud.
The server configuration defines which storage devices the server is attached to, which IP addresses can be used and how the server can be reached for remote management. A server must have at least one storage device attached in order to be started. Servers may have from zero to five public IPv4 and IPv6 addresses. All servers have a utility IP address that cannot be removed.
Server states
The server state indicates the server's current status.
| State | Description |
|---|---|
| started | The server is running. |
| stopped | The server is stopped. |
| maintenance | The server is in maintenance mode. |
| error | The server has encountered an error. This means the server is inaccessible due to an error in the cloud service. |
The normal server states are started and stopped. The maintenance state is a
temporary state used when the cloud service updates the server. If the server
is in error state, it will return automatically in the started or stopped state
when the issue is resolved.
List server configurations
Returns a list of available server configurations. A server configuration consists of a combination of CPU core count and main memory amount. All servers are created using these configurations.
Request
Normal response
{
"server_sizes": {
"server_size": [
{
"core_number": "1",
"memory_amount": "1024"
},
{
"core_number": "1",
"memory_amount": "2048"
},
... many more combinations ...
{
"core_number": "20",
"memory_amount": "130048"
},
{
"core_number": "20",
"memory_amount": "131072"
}
]
}
}
List servers
Returns a list of all servers associated with the current account.
Only the servers' most relevant information is returned by this operation. Further details on individual servers can be requested with the Get server details operation.
It is also possible to filter shown servers with label URL parameters, e.g.
?label=env or ?label=env%3Dprod. URL parameter can be given multiple
times to add more filters (e.g. ?label=env%3Dprod&label=v2), where
only servers that match all labels are returned.
Label keys are matched case insensitively.
Request
Normal response
{
"servers": {
"server": [
{
"core_number": "1",
"hostname": "fi.example.com",
"labels": {
"label": [
{
"key": "env",
"value": "prod"
}
]
},
"license": 0,
"memory_amount": "2048",
"plan" : "1xCPU-2GB",
"plan_ivp4_bytes" : "34253332",
"plan_ipv6_bytes" : "0",
"state": "started",
"tags" : {
"tag" : [
"PROD",
"CentOS"
]
},
"title": "Helsinki server",
"uuid": "00798b85-efdc-41ca-8021-f6ef457b8531",
"zone": "fi-hel1"
},
{
"core_number": "1",
"hostname": "uk.example.com",
"labels": {
"label": []
},
"license": 0,
"memory_amount": "512",
"plan" : "custom",
"state": "stopped",
"tags" : {
"tag" : [
"DEV",
"Ubuntu"
]
},
"title": "London server",
"uuid": "009d64ef-31d1-4684-a26b-c86c955cbf46",
"zone": "uk-lon1"
}
]
}
}
Get server details
Returns detailed information about a specific server.
Request
Normal response
{
"server": {
"boot_order": "disk",
"core_number": "0",
"firewall": "on",
"host" : 7653311107,
"hostname": "server1.example.com",
"labels": {
"label": [
{
"key": "env",
"value": "dev"
}
]
},
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.00",
"family" : "IPv4"
},
{
"access": "public",
"address": "0.0.0.0",
"family" : "IPv4"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family" : "IPv6"
}
]
},
"license": 0,
"memory_amount": "2048",
"networking" : {
"interfaces" : {
"interface" : [
{
"index" : 1,
"ip_addresses" : {
"ip_address" : [
{
"address" : "94.237.0.207",
"dhcp_provided": "yes",
"family" : "IPv4",
"floating" : "no"
}
]
},
"mac" : "de:ff:ff:ff:66:89",
"network" : "037fcf2a-6745-45dd-867e-f9479ea8c044",
"type" : "public",
"bootable": "no"
},
{
"index" : 2,
"ip_addresses" : {
"ip_address" : [
{
"address" : "10.6.3.95",
"dhcp_provided": "yes",
"family" : "IPv4",
"floating" : "no"
}
]
},
"mac" : "de:ff:ff:ff:ed:85",
"network" : "03000000-0000-4000-8045-000000000000",
"type" : "utility",
"bootable": "no"
},
{
"index" : 3,
"ip_addresses" : {
"ip_address" : [
{
"address" : "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"dhcp_provided": "yes",
"family" : "IPv6",
"floating" : "no"
}
]
},
"mac" : "de:ff:ff:ff:cc:20",
"network" : "03c93fd8-cc60-4849-91b8-6e404b228e2a",
"type" : "public",
"bootable": "no"
}
]
}
},
"nic_model": "virtio",
"plan" : "1xCPU-2GB",
"plan_ipv4_bytes": "3565675343",
"plan_ipv6_bytes": "4534432",
"simple_backup": "0100,dailies",
"state": "started",
"server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
"storage_devices": {
"storage_device": [
{
"address": "virtio:0",
"part_of_plan" : "yes",
"labels": [
{
"key": "foo",
"value": "bar"
}
],
"storage": "012580a1-32a1-466e-a323-689ca16f2d43",
"storage_size": 20,
"storage_tier": "maxiops",
"storage_title": "Storage for server1.example.com",
"type": "disk",
"boot_disk": "0"
}
]
},
"tags" : {
"tag" : [
"DEV",
"Ubuntu"
]
},
"timezone": "UTC",
"title": "server1.example.com",
"uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
"video_model": "cirrus",
"remote_access_enabled": "yes",
"remote_access_type": "vnc",
"remote_access_host": "fi-hel1.vnc.upcloud.com",
"remote_access_password": "aabbccdd",
"remote_access_port": "3000",
"zone": "fi-hel1"
}
}
The license attribute indicates the amount of credits per hour per CPU core
required by the server license. The server's license attribute is the sum of
all the attached storages' license attributes.
Create server
Creates a new server instance.
There are three ways to create a server:
- from a template,
- by cloning another server, or,
- by installing the server from scratch using an operating system installation media.
New servers are automatically started. By default, the server is not accessible by a remote access software.
The remote access via VNC can be enabled by setting remote_access_enabled parameter's value to yes.
A remote access password is generated and returned in the output of the create server operation.
The server can be added to a server group. See Server Groups for more information.
Creating from a template
UpCloud provides templates for various operating systems. Servers created from templates are preconfigured. The configurations vary between templates and may include, for example, setting the hostname, resizing the filesystem to fill the storage size and setting a root or other administrative account password.
A list of available templates can be obtained with the following request:
See List storages for more information on storage resource listings.
When creating a Linux server from a template, we recommend the use of ssh_keys as the login method.
ssh_keys are also the only login method for cloud-init enabled templates - one cannot create a password for these templates.
It is possible to define one or more public SSH keys. Without ssh_keys, by default on non-cloud-init templates, we create a
one-time password for the administrative account which is returned in the output of the operation.
This password is not stored anywhere and cannot be retrieved later. Once the administrative user
logs in, they are forced to change this one-time password. To check the template type of a public storage, see
List storages for more information.
When creating a Windows server from a template, the administrative account's password is
returned in the output of the operation (unless create_password in login_user section
is set to "no"). This password is not stored anywhere and cannot be retrieved later.
For security reasons, the password should be changed immediately after logging in.
With user_data it is possible to enter any set of commands (usually in a form of a
bash script or URL to one) to perform automated initial configuration on server
(e.g. installing automatically additional software components from package repository).
Note that these commands will be executed with root privileges upon server initialization
so special care should be taken to provide only verified data.
Creating a server from a template is an asynchronous operation. While the
create operation is running, the server is in maintenance state as the server
is being configured. As soon as the server is ready, the state will change to
started.
Creation of private templates is possible from any maxiops storage. Private templates can be used in same way as public templates. See Templatize storage for more information.
Request
{
"server": {
"zone": "fi-hel1",
"title": "My Debian server",
"hostname": "debian.example.com",
"labels": {
"label": [
{
"key": "test",
"value": ""
}
]
},
"plan": "2xCPU-4GB",
"storage_devices": {
"storage_device": [
{
"action": "clone",
"labels": [
{
"key": "foo",
"value": "bar"
}
],
"storage": "01000000-0000-4000-8000-000020030100",
"title": "Debian from a template",
"size": 50,
"tier": "maxiops"
}
]
},
"networking": {
"interfaces": {
"interface": [
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv4"
}
]
},
"type": "public"
},
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv4"
}
]
},
"type": "utility"
},
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv6"
}
]
},
"type": "public"
},
{
"type": "private",
"network": "03b5b0a0-ad4c-4817-9632-dafdb3ace5d9",
"ip_addresses": {
"ip_address": [
{
"family": "IPv4",
"address": "10.0.0.50",
"dhcp_provided": "yes"
},
{
"family": "IPv4",
"address": "10.0.0.60"
}
]
}
}
]
}
},
"login_user": {
"username": "upclouduser",
"ssh_keys": {
"ssh_key": [
"ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
"ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
]
}
}
}
}
The storage size is initially that of the template. When the server creation is complete, the storage will be resized and the size attribute will be set accordingly.
Cloning another server
An exact copy of another server can be obtained by cloning the server's storage devices. Cloning is a convenient method of creating multiple identical server instances.
The state of the cloned storage must be online.
Request
{
"server": {
"zone": "fi-hel1",
"title": "Another Debian server",
"hostname": "debian2.example.com",
"core_number": "4",
"memory_amount": "8192",
"storage_devices": {
"storage_device": [
{
"action": "clone",
"storage": "0169b4f8-051c-4a86-9484-f5b798249949",
"title": "Storage for another Debian server"
}
]
},
"networking": {
"interfaces": {
"interface": [
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv4"
}
]
},
"type": "public"
},
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv4"
}
]
},
"type": "utility"
},
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv6"
}
]
},
"type": "public"
},
{
"type": "private",
"network": "03b5b0a0-ad4c-4817-9632-dafdb3ace5d9",
"ip_addresses": {
"ip_address": [
{
"family": "IPv4",
"address": "10.0.0.50"
}
]
}
}
]
}
}
}
}
Installing a server from scratch
The server's operating system can be installed from a CD-ROM by attaching an empty storage device and loading an operating system installation CD-ROM.
UpCloud provides a variety of installation CD-ROMs for different operating systems. A list of CD-ROMs can be retrieved using the following request:
See List storages for more information on storage resource listings. VNC is used to connect to the server during installation.
Request
{
"server": {
"zone": "fi-hel1",
"title": "My Debian server",
"hostname": "debian.example.com",
"avoid_host": 7653311107,
"core_number": "4",
"memory_amount": "8192",
"storage_devices": {
"storage_device": [
{
"action": "create",
"size": "20",
"tier": "maxiops",
"title": "Debian from scratch"
},
{
"action": "attach",
"storage": "01000000-0000-4000-8000-000020010301",
"type": "cdrom"
}
]
},
"simple_backup": "0430,monthlies",
"networking": {
"interfaces": {
"interface": [
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv4"
}
]
},
"type": "public"
},
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv4"
}
]
},
"type": "utility"
},
{
"ip_addresses": {
"ip_address": [
{
"family": "IPv6"
}
]
},
"type": "public"
},
{
"type": "private",
"network": "03b5b0a0-ad4c-4817-9632-dafdb3ace5d9",
"ip_addresses": {
"ip_address": [
{
"family": "IPv4",
"address": "10.0.0.50"
}
]
}
}
]
}
}
}
}
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| avoid_host | A valid host id | no | Use this to make sure VMs do not reside on specific host. Refers to value from host -attribute. Useful when building HA-environments. | |
| host | A valid host id | no | Use this to start a VM on a specific host. Refers to value from host -attribute. Only available for private cloud hosts. | |
| boot_order | disk / cdrom / network or comma separated combination | disk | no | The boot device order. |
| core_number | A valid combination with memory_amount | smallest possible | no | The number of CPU cores dedicated to the server. See List server configurations. |
| firewall | on / off | on | no | The state of the server firewall rules. |
| hostname | A valid hostname | yes | A valid domain name, e.g. host.example.com. The maximum length is 128 characters. | |
| interfaces | An array of 1-10 interface objects. | yes | All interfaces wanted for the server. Interface object is described below. | |
| labels | 0-255 label blocks |
no | Labels contain key-value pairs defined in label block to classify the server. |
|
| login_user | One valid login_user block |
no | Define login account and SSH keys | |
| memory_amount | A valid combination with core_number | smallest possible | no | The amount of main memory in megabytes. See List server configurations. |
| metadata | yes / no | no | no | HTTP-accessible metadata service for the server. See our tutorial for more information. |
| nic_model | e1000 / virtio / rtl8139 | virtio | no | The model of the server's network interfaces. It is recommended to use the default unless there are specific reasons to choose otherwise; others may be subject to bandwidth limitations. |
| password_delivery | none / email / sms | no | The delivery method for the server’s root password. | |
| plan | A valid plan name returned with plan listing, or custom |
custom |
no | The pricing plan used. If a plan is selected, the core_number and memory_amount must match the plan if they are present. |
| storage_devices | 1-16 storage_device blocks | yes | The storage_devices block contains storage_device blocks that define the attached storages. | |
| timezone | A valid timezone identifier UTC | no | A timezone identifier, e.g. Europe/Helsinki. See Timezones. | |
| title | 0-255 characters | yes | A short, informational description. | |
| user_data | A valid URL or shell script | no | Defines URL for a server setup script, or the script body itself | |
| video_model | vga / cirrus | vga | no | The model of the server's video interface. |
| remote_access_type | vnc | vnc | no | The remote access type. |
| remote_access_enabled | yes / no | no | no | Is the remote access enabled. |
| remote_access_password | 8 characters of a-z, A-Z and 0-9. | randomly generated | no | Remote access password. |
| simple_backup | HHMM,{daily|dailies|weeklies|monthlies} / no | account default | no | Simple backup time in UTC, followed by daily, dailies, weeklies, or monthlies option separated by comma, or no when disabled. |
| zone | A valid zone identifier | yes | The zone in which the server will be hosted, e.g. fi-hel1. See Zones. | |
| server_group | Server group UUID | no | Use this to add the VM to a server group |
The storage_devices block may contain 1-16 storage devices. Each block can have
the following attributes:
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| action | create / clone / attach | yes | The method used to create or attach the specified storage. | |
| address | ide[:[01]:[01]] / scsi[:0:[0-15]] / virtio[:[0-15]] | The next available | no | The device address the storage will be attached to. Specify only the bus name (ide/scsi/virtio) to auto-select next available address from that bus. |
| size | 10-1024 | if action is clone, same as original | yes | if action is create The size of the storage device in gigabytes. This attribute is applicable only if action is create or clone. |
| storage | A valid storage UUID | yes | if action is clone or attach The UUID of the storage device to be attached or cloned. Applicable only if action is attach or clone. | |
| tier | hdd / maxiops |
hdd | No | The storage tier to use. See [Storage tiers]. |
| title | 0-255 characters | no | A short, informational description for the storage. | |
| type | disk / cdrom | disk | no | The device type the storage will be attached as. See [Storage types]. |
| boot_disk | 0/1 | 0 | no | If the value is 1 the storage device will be used as a boot disk, unless overridden with the server boot_order attribute. |
| labels | List of wanted labels for the storage | no | Labels describing the storage, objects with both "key" and "value" defined. Available when the action is create or clone. |
The interfaces block may contain 1-10 network interfaces. Each block can have the following attributes:
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| network | A valid network unique ID | (varies) | Virtual network ID to join. Required for private interfaces. Setting it in public and utility interfaces requires special privileges. |
|
| type | public / utility / private | yes | Set the type of the network | |
| index | Positive integer | Position in array | no | Interface index |
| ip_addresses | IP address array, see below | yes | Array of IP addresses under ip_address | |
| source_ip_filtering | yes / no | yes | no | Whether source IP filtering is enabled on the interface. Disabling it is allowed only for SDN private interfaces. |
| bootable | yes / no | no | no | Whether to try booting through the interface. |
Disabling the source IP filtering allows sourcing traffic from other IP addresses than allocated to virtual servers within the network, for example when a virtual server is acting as a NAT gateway or a site-to-site VPN endpoint.
ip_addresses block expects an ip_address-named array with following possible arguments.
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| family | IPv4 / IPv6 | IPv4 | yes | Address family of the address. Currently IPv6 is only supported with public type interfaces. |
| address | IPv4 / IPv6 address | no | A valid IP address within the IP space of the network. If not given, the next free address is selected. Specifying an address in public and utility interfaces requires special privileges. |
|
| dhcp_provided | yes / no | no | In case of multiple IP addresses attached to the interface, the one marked with dhcp_provided flag is the one offered by the DHCP server. By default, the dhcp_provided is set to yes for the first IP address in the array. |
The login_user block may contain username, create_password attribute and 0-32 SSH keys:
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| create_password | yes / no | yes | no | If set to "yes", a one-time password will be created. If ssh_keys is set this defaults to "no". This option is disabled on cloud-init templates. |
| username | Valid, non-reserved username | root | no | If set to other than "root", normal user with sudo privileges is created |
| ssh_keys | 1-32 ssh_key attributes |
no | Each ssh_key child attribute defines one SSH-key in OpenSSH format. Requires create_password is set to "no" or not provided. This option is required for cloud-init templates. |
Note: login_user and user_data attributes are ignored with other than Linux templates.
The labels block may include key-value pairs for classifying the server.
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| key | 1-32 upper and lower case letters, numbers, - & _. Cannot start with _ |
yes | Key representing the label | |
| value | 0-255 characters | yes | Key representing the value |
Labels can include specific service labels that cannot be modified. These always start with _ and do not conflict with normal labels.
Normal response
{
"server": {
"boot_order": "disk",
"core_number": "2",
"firewall": "on",
"hostname": "debian.example.com",
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family" : "IPv4"
},
{
"access": "public",
"address": "x.x.x.x",
"family" : "IPv4"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family" : "IPv6"
}
]
},
"license": 0,
"memory_amount": "4096",
"nic_model": "virtio",
"password": "aabbccdd",
"plan" : "2xCPU-4GB",
"plan_ipv4_bytes" : "0",
"plan_ipv6_bytes" : "0",
"simple_backup": "0430,dailies",
"state": "maintenance",
"storage_devices": {
"storage_device": [
{
"address": "virtio:0",
"part_of_plan" : "yes",
"storage": "0169b4f8-051c-4a86-9484-f5b798249949",
"storage_size": 1,
"storage_tier": "maxiops",
"storage_title": "Debian from a template",
"type": "disk",
"boot_disk": "0"
}
]
},
"tags" : {
"tag" : []
},
"timezone": "UTC",
"title": "My Debian server",
"uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
"video_model": "cirrus",
"remote_access_enabled": "no",
"remote_access_password": "aabbccdd",
"zone": "fi-hel1"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | ACTION_INVALID | The attribute action has an invalid value. |
| 400 Bad Request | ACTION_MISSING | The required attribute action is missing from the request. |
| 400 Bad Request | BOOT_ORDER_INVALID | The attribute boot_order has an invalid value. |
| 400 Bad Request | CORE_MEMORY_UNSUPPORTED | The combination of core_number and memory_amount is not supported. See List server configurations. |
| 400 Bad Request | CORE_NUMBER_INVALID | The attribute core_number has an invalid value. |
| 400 Bad Request | CREATE_PASSWORD_INVALID | The attribute create_password cannot be yes when ssh keys is provided. |
| 400 Bad Request | FIREWALL_INVALID | The attribute firewall has an invalid value. |
| 400 Bad Request | HOSTNAME_INVALID | The attribute hostname has an invalid value. Value is case sensitive and must be in lower case. |
| 400 Bad Request | HOSTNAME_MISSING | The required attribute hostname is missing from the request. |
| 400 Bad Request | MEMORY_AMOUNT_INVALID | The attribute memory_amount has an invalid value. |
| 400 Bad Request | NIC_MODEL_INVALID | The attribute nic_model has an invalid value. |
| 400 Bad Request | PASSWORD_DELIVERY_INVALID | The attribute password_delivery has an invalid value. |
| 400 Bad Request | SERVER_TITLE_INVALID | The attribute title in the server block has an invalid value. |
| 400 Bad Request | SERVER_TITLE_MISSING | The required attribute title is missing from the server block. |
| 400 Bad Request | SIMPLE_BACKUP_INVALID | The attribute simple_backup has an invalid value. |
| 400 Bad Request | SIZE_INVALID | The attribute size has an invalid value. If action is clone, size must be greater than the size of the cloned storage. |
| 400 Bad Request | SIZE_MISSING | The required attribute size is missing from the request. |
| 400 Bad Request | STORAGE_DEVICE_INVALID | A malformed storage_device block. |
| 400 Bad Request | STORAGE_DEVICE_MISSING | The storage_device block is missing from the request. |
| 400 Bad Request | STORAGE_DEVICES_INVALID | A malformed storage_devices block. |
| 400 Bad Request | STORAGE_DEVICES_MISSING | The storage_devices block is missing from the request. |
| 400 Bad Request | STORAGE_INVALID | The attribute storage has an invalid value. |
| 400 Bad Request | STORAGE_MISSING | The required attribute storage is missing from a storage_device block. |
| 400 Bad Request | STORAGE_TITLE_INVALID | The attribute title in a storage_device block has an invalid value. |
| 400 Bad Request | STORAGE_TITLE_MISSING | The required attribute title is missing from the storage_device block. |
| 400 Bad Request | TIMEZONE_INVALID | The attribute timezone has an invalid value. |
| 400 Bad Request | TYPE_INVALID | The attribute type has an invalid value. |
| 400 Bad Request | TIER_INVALID | The attribute tier has an invalid value. |
| 400 Bad Request | USER_DATA_INVALID | The attribute user_data has an invalid value. |
| 400 Bad Request | VIDEO_MODEL_INVALID | The attribute video_model has an invalid value. |
| 400 Bad Request | VNC_INVALID | The attribute remote_access_type has an invalid value. |
| 400 Bad Request | VNC_PASSWORD_INVALID | The attribute remote_access_password has an invalid value. |
| 400 Bad Request | ZONE_INVALID | The attribute zone has an invalid value. |
| 400 Bad Request | ZONE_MISSING | The required attribute zone is missing from the request. |
| 400 Bad Request | INVALID_LABEL_KEY | The attribute key in a label block has an invalid value. |
| 400 Bad Request | INVALID_LABEL_VALUE | The attribute value in a label block has an invalid value. |
| 402 Payment Required | INSUFFICIENT_CREDITS | There are not enough credits to perform the requested action. See Credits. |
| 403 Forbidden | STORAGE_FORBIDDEN | The storage exists, but is owned by another account. |
| 403 Forbidden | HOST_FORBIDDEN | The specified host is not available for the current account. |
| 403 Forbidden | PLAN_CORE_NUMBER_ILLEGAL | The specified core_number does not match the selected plan. |
| 403 Forbidden | PLAN_MEMORY_AMOUNT_ILLEGAL | The specified memory_amount does not match the selected plan. |
| 403 Forbidden | TRIAL_PLAN | User is in trial mode, trial mode server cannot have a pricing plan. |
| 403 Forbidden | TRIAL_SERVER_LIMIT_REACHED | Trial mode server limit reached. |
| 403 Forbidden | TRIAL_CORE_LIMIT_REACHED | Trial mode core limit reached. |
| 403 Forbidden | TRIAL_NETWORK_LIMIT_REACHED | Trial mode network limit reached. |
| 403 Forbidden | TRIAL_DETACHED_FLOATING_IP_LIMIT_REACHED | Trial mode detached floating IP limit reached. |
| 403 Forbidden | TRIAL_MEMORY_LIMIT_REACHED | Trial mode memory limit reached. |
| 403 Forbidden | TRIAL_STORAGE_LIMIT_REACHED | Trial mode storage limit reached. |
| 403 Forbidden | TRIAL_STORAGE_SIZE_LIMIT_REACHED | Trial mode storage size limit reached. |
| 403 Forbidden | TRIAL_IP_LIMIT_REACHED | Trial mode IP limit reached. |
| 403 Forbidden | SERVER_CORE_LIMIT_REACHED | Server core account quota limit reached. |
| 403 Forbidden | SERVER_MEMORY_LIMIT_REACHED | Server memory account quota limit reached. |
| 403 Forbidden | HDD_STORAGE_LIMIT_REACHED | HDD storage account quota limit reached. |
| 403 Forbidden | SSD_STORAGE_LIMIT_REACHED | SSD storage account quota limit reached. |
| 403 Forbidden | MAXIOPS_STORAGE_LIMIT_REACHED | MaxIOPS storage account quota limit reached. |
| 403 Forbidden | SERVER_IP_LIMIT_REACHED | Server IP account quota limit reached. |
| 403 Forbidden | NETWORK_LIMIT_REACHED | Network account quota limit reached. |
| 403 Forbidden | DETACHED_FLOATING_IP_LIMIT_REACHED | Detached floating IP account quota limit reached. |
| 403 Forbidden | NETWORK_PEERING_LIMIT_REACHED | Network peering account quota limit reached. |
| 409 Conflict | LABEL_LIMIT_REACHED | Maximum number of labels per resource reached. |
| 404 Not Found | STORAGE_NOT_FOUND | The storage does not exist. |
| 404 Not Found | HOST_NOT_FOUND | The host does not exist. |
| 404 Not Found | ZONE_NOT_FOUND | The zone does not exist. |
| 409 Conflict | CDROM_DEVICE_IN_USE | The request has multiple storage_device blocks that attach storages as a CD-ROM. Only one CD-ROM device can be attached per server. |
| 409 Conflict | DEVICE_ADDRESS_IN_USE | The request has multiple storage_device blocks attached to the same device address. |
| 409 Conflict | IP_ADDRESS_RESOURCES_UNAVAILABLE | There were not enough IP addresses available in the specified zone to create the requested server. |
| 409 Conflict | MULTIPLE_TEMPLATES | The request has multiple storage_device blocks referring to templates. Only one storage template can be used to create a server. |
| 409 Conflict | PUBLIC_STORAGE_ATTACH | Attaching a storage of access type public is not allowed. See Storage access types. |
| 409 Conflict | SERVER_RESOURCES_UNAVAILABLE | There are not enough server resources available in the specified zone to create the requested server. |
| 409 Conflict | STORAGE_ATTACHED_AS_CDROM | A storage resource to be attached as a disk is already attached to some server as a CD-ROM. |
| 409 Conflict | STORAGE_ATTACHED_AS_DISK | A storage resource to be attached as a CD-ROM is already attached to some server as a disk. |
| 409 Conflict | STORAGE_DEVICE_LIMIT_REACHED | The request contained more than four storage_device blocks. |
| 409 Conflict | STORAGE_IN_USE | The request has multiple storage_device blocks referring to the same storage resource. |
| 409 Conflict | STORAGE_RESOURCES_UNAVAILABLE | There are not enough storage resources available in the specified zone to create the requested storages. |
| 409 Conflict | STORAGE_STATE_ILLEGAL | The storage is in a state in which it cannot be used. See Storage states. |
| 409 Conflict | STORAGE_TYPE_ILLEGAL | The type of the storage to be attached is illegal. Attaching a cdrom or a template as a disk is not possible. See Storage types. |
| 409 Conflict | ZONE_MISMATCH | The storage is located in a different zone than the one the server is created in. |
| 409 Conflict | INVALID_USERNAME | The specified username is a reserved username in operating system. |
| 409 Conflict | SERVER_CREATING_LIMIT_REACHED | There are too many servers simultaneously being created. |
| 409 Conflict | TOO_MANY_BOOT_DISKS | Too many boot disks: Only one storage can have boot_disk defined. |
| 409 Conflict | WINDOWS_NOT_AVAILABLE | Windows servers cannot be created while in trial mode. |
| 409 Conflict | MS_LMA_REQUIRED | Creation of Windows servers requires acceptance of the Microsoft License Mobility Agreement. |
| 409 Conflict | BACKUP_RULE_CONFLICT | The backup rule of a storage conflicts with the simple backup rule of the server. |
| 409 Conflict | CAN_NOT_CREATE_PASSWORD_FOR_THE_SELECTED_DISTRIBUTION | The attribute create_password cannot be yes for the selected distribution. Please, use SSH keys instead. |
| 409 Conflict | METADATA_DISABLED_ON_CLOUD-INIT | Metadata cannot be disabled when creating a server from a cloud-init template. |
| 409 Conflict | SERVER_RESOURCES_UNAVAILABLE_FOR_STRICT_AA | Conditions for strict anti-affinity policy cannot currently be met. Please try again later or remove the server from the server group. |
Start server
Starts a stopped server. The server state must be stopped.
Request
Attributes
| Attributes | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| avoid_host | A valid host id | no | Use this to make sure VMs do not reside on specific host. Refers to value from host -attribute. Useful when building HA-environments. | |
| host | A valid host id | no | Use this to start the VM on a specific host. Refers to value from host -attribute. Only available for private cloud hosts. | |
| start_type | async, sync | sync | no | Define server start type. With async, you need to poll separately when your server is in started state. |
Normal response
{
"server": {
"boot_order": "disk",
"core_number": "2",
"firewall": "on",
"hostname": "debian.example.com",
"host": 8055964291,
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family" : "IPv4"
},
{
"access": "public",
"address": "x.x.x.x",
"family" : "IPv4"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family" : "IPv6"
}
]
},
"labels": {
"label": []
},
"license": 0,
"memory_amount": "4096",
"nic_model": "virtio",
"plan" : "2xCPU-4GB",
"plan_ipv4_bytes" : "435376546",
"plan_ipv6_bytes" : "0",
"state": "started",
"storage_devices": {
"storage_device": [
{
"address": "virtio:0",
"plart_of_plan" : "yes",
"storage": "0169b4f8-051c-4a86-9484-f5b798249949",
"storage_size": "10",
"storage_tier": "maxiops",
"storage_title": "Debian from a template",
"type": "disk",
"boot_disk": "0"
}
]
},
"tags" : {
"tag" : []
},
"timezone": "UTC",
"title": "My Debian server",
"uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
"video_model": "cirrus",
"remote_access_enabled": "no",
"remote_access_password": "aabbccdd",
"zone": "fi-hel1"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 404 Not Found | HOST_NOT_FOUND | The host does not exist. |
| 402 Payment Required | INSUFFICIENT_CREDITS | There are not enough credits to perform the requested action. See Credits. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 403 Forbidden | HOST_FORBIDDEN | The specified host is not available for the current account. |
| 403 Forbidden | TRIAL_SERVER_LIMIT_REACHED | Trial mode server limit reached. |
| 403 Forbidden | TRIAL_CORE_LIMIT_REACHED | Trial mode core limit reached. |
| 403 Forbidden | TRIAL_NETWORK_LIMIT_REACHED | Trial mode network limit reached. |
| 403 Forbidden | TRIAL_DETACHED_FLOATING_IP_LIMIT_REACHED | Trial mode detached floating IP limit reached. |
| 403 Forbidden | TRIAL_MEMORY_LIMIT_REACHED | Trial mode memory limit reached. |
| 403 Forbidden | TRIAL_STORAGE_LIMIT_REACHED | Trial mode storage limit reached. |
| 403 Forbidden | TRIAL_STORAGE_SIZE_LIMIT_REACHED | Trial mode storage size limit reached. |
| 403 Forbidden | TRIAL_IP_LIMIT_REACHED | Trial mode IP limit reached. |
| 403 Forbidden | SERVER_CORE_LIMIT_REACHED | Server core account quota limit reached. |
| 403 Forbidden | SERVER_MEMORY_LIMIT_REACHED | Server memory account quota limit reached. |
| 403 Forbidden | HDD_STORAGE_LIMIT_REACHED | HDD storage account quota limit reached. |
| 403 Forbidden | SSD_STORAGE_LIMIT_REACHED | SSD storage account quota limit reached. |
| 403 Forbidden | MAXIOPS_STORAGE_LIMIT_REACHED | MaxIOPS storage account quota limit reached. |
| 403 Forbidden | SERVER_IP_LIMIT_REACHED | Server IP account quota limit reached. |
| 403 Forbidden | NETWORK_LIMIT_REACHED | Network account quota limit reached. |
| 403 Forbidden | DETACHED_FLOATING_IP_LIMIT_REACHED | Detached floating IP account quota limit reached. |
| 403 Forbidden | NETWORK_PEERING_LIMIT_REACHED | Network peering account quota limit reached. |
| 409 Conflict | LABEL_LIMIT_REACHED | Maximum number of labels per resource reached. |
| 409 Conflict | NO_STORAGES_ATTACHED | There are no storage devices currently attached to the server. A server cannot be started with no storage devices. |
| 409 Conflict | SERVER_RESOURCES_UNAVAILABLE | There are not enough server resources available in the specified zone to start the requested server. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
Stop server
Stops a started server.
The server state must be started.
Stopping a server can be done in three different ways:
- by hard stopping, or,
- soft stopping with a timeout, or,
- soft stopping without a timeout.
Hard stopping a server is the equivalent of physically unplugging the server.
Soft stopping a server sends an ACPI signal to the server. If a timeout is set, the timeout period has passed and the server is still running, a hard stop is performed. If no timeout is set, only the ACPI signal is sent.
Request
Attributes
| Attributes | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| stop_type | soft / hard | soft | no | Type of stop operation performed on the server. |
| timeout | 1-600 | no | The stop timeout in seconds. |
Normal response
{
"server" : {
"boot_order" : "disk",
"core_number" : "2",
"firewall" : "on",
"hostname" : "debian.example.com",
"host" : 8055964291,
"ip_addresses" : [
{
"access" : "utility",
"address" : "10.0.0.0",
"family" : "IPv4"
},
{
"access" : "public",
"address" : "x.x.x.x",
"family" : "IPv4"
},
{
"access" : "public",
"address" : "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family" : "IPv6"
}
],
"labels": {
"label": []
},
"license" : 0,
"memory_amount" : "4096",
"nic_model" : "virtio",
"plan" : "2xCPU-4GB",
"plan_ipv4_bytes" : "34543646754",
"plan_ipv6_bytes" : "242432",
"state" : "started",
"storage_devices" : {
"storage_device" : [
{
"address" : "virtio:0",
"part_of_plan" : "yes",
"storage" : "0169b4f8-051c-4a86-9484-f5b798249949",
"storage_size" : "10",
"storage_tier": "maxiops",
"storage_title" : "Debian from a template",
"type" : "disk"
}
]
},
"tags" : {
"tag" : []
},
"timezone" : "UTC",
"title" : "My Debian server",
"uuid" : "00c78863-db86-44ea-af70-d6edc4d162bf",
"video_model" : "cirrus",
"remote_access_enabled": "no",
"remote_access_password" : "aabbccdd",
"zone" : "fi-hel1"
}
}
Note: the server's state is still started after the operation. The state will
change to stopped once the server has shut down.
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | STOP_TYPE_INVALID | The attribute stop_type has an invalid value. |
| 400 Bad Request | TIMEOUT_INVALID | The attribute timeout has an invalid value. |
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
Restart server
Stops and starts a server. The server state must be started.
A restart can be done in two ways:
- by hard stopping, or,
- by soft stopping with a timeout.
Hard stopping the server in the equivalent of power cycling the server. The server is then started.
Soft stopping sends an ACPI signal to the server. The API then waits for the
server to shut down before starting it. If the server has not shut down within
the timeout period, the action indicated by timeout_action is performed. A value
of destroy hard stops the server which is then started. A value of ignore stops
the operation and the server will not be started.
Request
Attributes
| Attributes | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| stop_type | soft / hard | soft | no | Restart type |
| timeout | 1-600 | yes if type is soft | Stop timeout in seconds | |
| timeout_action | destroy / ignore | ignore | no | Action to take if timeout limit is exceeded. |
| host | A valid host id | no | Use this to restart the VM on a specific host. Refers to value from host -attribute. Only available for private cloud hosts. |
Normal response
{
"server": {
"boot_order": "disk",
"core_number": "2",
"firewall": "on",
"hostname": "debian.example.com",
"host": 8055964291,
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family" : "IPv4"
},
{
"access": "public",
"address": "x.x.x.x",
"family" : "IPv4"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family" : "IPv6"
}
]
},
"labels": {
"label": []
},
"license": 0,
"memory_amount": "4096",
"nic_model": "virtio",
"plan" : "2xCPU-4GB",
"plan_ipv4_bytes" : "34543646754",
"plan_ipv6_bytes" : "242432",
"state": "started",
"storage_devices": {
"storage_device": [
{
"address": "virtio:0",
"plart_of_plan" : "yes",
"storage": "0169b4f8-051c-4a86-9484-f5b798249949",
"storage_size": "10",
"storage_tier": "maxiops",
"storage_title": "Debian from a template",
"type": "disk"
}
]
},
"tags" : {
"tag" : []
},
"timezone": "UTC",
"title": "My Debian server",
"uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
"video_model": "cirrus",
"remote_access_enabled": "no",
"remote_access_password": "aabbccdd",
"zone": "fi-hel1"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | STOP_TYPE_INVALID | The attribute stop_type has an invalid value. |
| 400 Bad Request | TIMEOUT_MISSING | The required attribute timeout is missing from the request. |
| 400 Bad Request | TIMEOUT_INVALID | The attribute timeout has an invalid value. |
| 400 Bad Request | TIMEOUT_ACTION_INVALID | The attribute timeout_action has an invalid value. |
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 403 Forbidden | HOST_FORBIDDEN | The specified host is not available for the current account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 404 Not Found | HOST_NOT_FOUND | The host does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
Modify server
Modifies the configuration of an existing server.
Attaching and detaching storages as well as assigning and releasing IP addresses have their own separate operations. See Attach storage, Detach storage, Assign IP address and Release IP address.
In order to change the remote_access_type attribute, or decrease core_number and memory_amount, the server state must be stopped.
Request
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| boot_order | disk / cdrom / network or comma separated combination | disk | no | The boot device order. |
| core_number | A valid combination with memory_amount | no | The number of CPU cores dedicated to the server. See List server configurations. | |
| firewall | on / off | on | no | The state of the server firewall rules. |
| hostname | A valid hostname | no | A valid hostname, e.g. host.example.com. The maximum length is 128 characters. | |
| labels | 0-255 label blocks |
no | Labels contain key-value pairs defined in label block above to classify the server. |
|
| memory_amount | A valid combination with core_number | no | The amount of main memory in megabytes. See List server configurations. | |
| metadata | yes / no | no | no | HTTP-accessible metadata service for the server. See our tutorial for more information. |
| nic_model | "e1000 / virtio / rtl8139" | virtio | no | The model of the server's network interfaces. It is recommended to use the default unless there are specific reasons to choose otherwise; others may be subject to bandwidth limitations. |
| plan | A valid plan name returned with plan listing, or custom |
custom |
no | The pricing plan used. If a plan is selected, the core_number and memory_amount must match the plan if they are present. |
| simple_backup | HHMM,{daily|dailies|weeklies|monthlies} / no | account default | no | Simple backup time in UTC, followed by daily, dailies, weeklies, or monthlies option separated by comma, or no when disabled. |
| title | 0-255 characters | no | A short, informational description. | |
| timezone | A valid timezone identifier | no | A timezone identifier, e.g. Europe/Helsinki. See Timezones. | |
| video_model | vga / cirrus | vga | no | The model of the server's video interface. |
| remote_access_type | vnc | vnc | no | The remote access type. |
| remote_access_enabled | yes / no | no | no | Is the remote access enabled. |
| remote_access_password | 8 characters of a-z, A-Z and 0-9. | no | The remote access password. |
Normal response
{
"server": {
"boot_order": "disk",
"core_number": "8",
"firewall": "on",
"hostname": "debian.example.com",
"host": 8055964291,
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family" : "IPv4"
},
{
"access": "public",
"address": "x.x.x.x",
"family" : "IPv4"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family" : "IPv6"
}
]
},
"labels": {
"label": []
},
"license": 0,
"memory_amount": "16384",
"nic_model": "virtio",
"plan" : "custom",
"plan_ipv4_bytes" : "0",
"plan_ipv6_bytes" : "0",
"simple_backup": "no",
"state": "stopped",
"storage_devices": {
"storage_device": [
{
"address": "virtio:0",
"plart_of_plan" : "yes",
"storage": "0169b4f8-051c-4a86-9484-f5b798249949",
"storage_size": "10",
"storage_tier": "maxiops",
"storage_title": "Debian from a template",
"type": "disk",
"boot_disk": "0"
}
]
},
"tags" : {
"tag" : []
},
"timezone": "UTC",
"title": "My Debian server",
"uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
"video_model": "cirrus",
"remote_access_enabled": "no",
"remote_access_password" : "aabbccdd",
"zone": "fi-hel1"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | BOOT_ORDER_INVALID | The attribute boot_order has an invalid value. |
| 400 Bad Request | CORE_MEMORY_UNSUPPORTED | The combination of core_number and memory_amount is not supported. See List server configurations. |
| 400 Bad Request | CORE_NUMBER_INVALID | The attribute core_number has an invalid value. |
| 400 Bad Request | FIREWALL_INVALID | The attribute firewall has an invalid value. |
| 400 Bad Request | HOSTNAME_INVALID | The attribute hostname has an invalid value. |
| 400 Bad Request | MEMORY_AMOUNT_INVALID | The attribute memory_amount has an invalid value. |
| 400 Bad Request | NIC_MODEL_INVALID | The attribute nic_model has an invalid value. |
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 400 Bad Request | SIMPLE_BACKUP_INVALID | The attribute simple_backup has an invalid value. |
| 400 Bad Request | TITLE_INVALID | The attribute title has an invalid value. |
| 400 Bad Request | TIMEZONE_INVALID | The attribute timezone has an invalid value. |
| 400 Bad Request | VIDEO_MODEL_INVALID | The attribute video_model has an invalid value. |
| 400 Bad Request | VNC_INVALID | The attribute remote_access_type has an invalid value. |
| 400 Bad Request | VNC_PASSWORD_INVALID | The attribute remote_access_password has an invalid value. |
| 400 Bad Request | FAILED_TO_ADD_MEMORY | Failed to hot resize memory. |
| 400 Bad Request | INVALID_LABEL_KEY | The attribute key in a label block has an invalid value. |
| 400 Bad Request | INVALID_LABEL_VALUE | The attribute value in a label block has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 403 Forbidden | PLAN_CORE_NUMBER_ILLEGAL | The specified core_number does not match the selected plan. |
| 403 Forbidden | PLAN_MEMORY_AMOUNT_ILLEGAL | The specified memory_amount does not match the selected plan. |
| 403 Forbidden | TRIAL_SERVER_LIMIT_REACHED | Trial mode server limit reached. |
| 403 Forbidden | TRIAL_CORE_LIMIT_REACHED | Trial mode core limit reached. |
| 403 Forbidden | TRIAL_NETWORK_LIMIT_REACHED | Trial mode network limit reached. |
| 403 Forbidden | TRIAL_DETACHED_FLOATING_IP_LIMIT_REACHED | Trial mode detached floating IP limit reached. |
| 403 Forbidden | TRIAL_MEMORY_LIMIT_REACHED | Trial mode memory limit reached. |
| 403 Forbidden | TRIAL_STORAGE_LIMIT_REACHED | Trial mode storage limit reached. |
| 403 Forbidden | TRIAL_STORAGE_SIZE_LIMIT_REACHED | Trial mode storage size limit reached. |
| 403 Forbidden | TRIAL_IP_LIMIT_REACHED | Trial mode IP limit reached. |
| 403 Forbidden | SERVER_CORE_LIMIT_REACHED | Server core account quota limit reached. |
| 403 Forbidden | SERVER_MEMORY_LIMIT_REACHED | Server memory account quota limit reached. |
| 403 Forbidden | HDD_STORAGE_LIMIT_REACHED | HDD storage account quota limit reached. |
| 403 Forbidden | SSD_STORAGE_LIMIT_REACHED | SSD storage account quota limit reached. |
| 403 Forbidden | MAXIOPS_STORAGE_LIMIT_REACHED | MaxIOPS storage account quota limit reached. |
| 403 Forbidden | SERVER_IP_LIMIT_REACHED | Server IP account quota limit reached. |
| 403 Forbidden | NETWORK_LIMIT_REACHED | Network account quota limit reached. |
| 403 Forbidden | DETACHED_FLOATING_IP_LIMIT_REACHED | Detached floating IP account quota limit reached. |
| 403 Forbidden | NETWORK_PEERING_LIMIT_REACHED | Network peering account quota limit reached. |
| 409 Conflict | LABEL_LIMIT_REACHED | Maximum number of labels per resource reached. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
| 409 Conflict | BACKUP_RULE_CONFLICT | The backup rule of a storage conflicts with the simple backup rule of the server. |
| 409 Conflict | HOT_RESIZE_NOT_ENABLED | Hot resize of CPU or memory is not enabled on the server. Please, stop and restart the server to enable hot resize. |
| 409 Conflict | HOT_RESIZE_UNAVAILABLE | Hot resize is currently unavailable for this server, please shutdown the server to resize. |
| 409 Conflict | NO_AVAILABLE_MEMORY_SLOTS | No available memory slots. Free memory slots by shutting down the server and restarting it again |
Cancel server operation
Cancels a running server operation.
A running server operation can be cancelled if it is e.g. taking too much time or was not intentional. For example, to cancel cloning a server, invoke this method on the new server in progress of being created.
The server state must be 'maintenance'.
Request
Normal response
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which operations can not be cancelled. |
| 409 Conflict | UNABLE_TO_CANCEL | The cancellation was not successful. |
Delete server
Deletes a server.
The server state must be stopped. Storage devices attached to the server are
automatically deleted if storages is truthy and backups to those storages
will be handled by backups. Kept storages can be reattached to other
servers. IP addresses used by the server are released.
Request
Query parameters
| Parameter | Description | Accepted values | Default value |
|---|---|---|---|
| storages | Controls what to do with storages related to the deleted server. | 0, 1, true, false | 0 |
| backups | If storages are to be deleted, controls what to do with backups related to the storages. | keep, keep_latest, delete | keep |
Normal response
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 400 Bad Request | REQUEST_INVALID | Deleting backups without deleting storages is not allowed. |
| 400 Bad Request | STORAGE_DELETION_POLICY_INVALID | The deletion policy for storages is invalid. |
| 400 Bad Request | BACKUP_DELETION_POLICY_INVALID | The deletion policy for backups is invalid. Allowed values are 'keep', 'keep_latest' and 'delete'. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
| 409 Conflict | STORAGE_STATE_ILLEGAL | One of the attached storages is in a state in which it cannot be used. See Storage states. |
Metadata service
A server can use the UpCloud metadata service to query information about itself. See our tutorial for more information.
Metadata service can be used for deployment automation by allowing initialization scripts to utilise server-specific information for configuring software and applications.
Metadata is available per server basis when enabled at server creation or if enabled at a later time by modifying the server, and only from within the server itself. The server can query the metadata HTTP API available at the IP address 169.254.169.254 to list either the full information in JSON or per single metadata field available as a directory tree.
~# curl http://169.254.169.254/metadata/v1/
cloud_name
instance_id
hostname
platform
subplatform
public_keys
region
network/
storage/
tags
user_data
vendor_data
~# curl http://169.254.169.254/metadata/v1/storage
disks/
~# curl http://169.254.169.254/metadata/v1/storage/disks
1
~# curl http://169.254.169.254/metadata/v1/storage/disks/1
id
serial
size
type
tier
~# curl http://169.254.169.254/metadata/v1/storage/disks/1/id
0187b8c5-7220-4c90-9026-047dff8be0b3
~# curl http://169.254.169.254/metadata/v1.json
{
"cloud_name": "upcloud",
"instance_id": "00bf9504-a4cb-4839-88ff-124a2c95e169",
"hostname": "metadata.example.com",
"platform": "servers",
"subplatform": "metadata (http://169.254.169.254)",
"public_keys": [
"ssh-rsa AAAAB[...]ud1Cw== [email protected]"
],
"region": "de-fra1",
"network": {
"interfaces": [
{
"index": 1,
"ip_addresses": [
{
"address": "94.237.90.209",
"dhcp": true,
"dns": [
"94.237.127.9",
"94.237.40.9"
],
"family": "IPv4",
"floating": false,
"gateway": "94.237.90.1",
"network": "94.237.90.0/24"
}
],
"mac": "de:ad:be:ef:3f:c5",
"network_id": "03030473-8e9d-4f4f-bcfe-b2c300391a07",
"type": "public"
},
{
"index": 2,
"ip_addresses": [
{
"address": "10.199.12.11",
"dhcp": true,
"dns": null,
"family": "IPv4",
"floating": false,
"gateway": "10.199.12.1",
"network": "10.199.12.0/24"
}
],
"mac": "de:ad:be:ef:9f:ff",
"network_id": "03318153-4e70-4ba5-8e74-69538582188d",
"type": "utility"
},
{
"index": 3,
"ip_addresses": [
{
"address": "2a04:3540:1000:811:9809:21ff:fe8b:5962",
"dhcp": true,
"dns": [
"2a04:3540:53::1",
"2a04:3544:53::1"
],
"family": "IPv6",
"floating": false,
"gateway": "2a04:3540:1000:811::1",
"network": "2a04:3540:1000:811::/64"
}
],
"mac": "9a:09:21:8b:59:62",
"network_id": "03000000-0000-4000-8002-000000000000",
"type": "public"
}
],
"dns": [
"94.237.127.9",
"94.237.40.9"
]
},
"storage": {
"disks": [
{
"id": "0187b8c5-7220-4c90-9026-047dff8be0b3",
"serial": "0187b8c572204c909026",
"size": 25,
"type": "disk",
"tier": "maxiops"
}
]
},
"tags": [
"dev",
"metadata"
],
"user_data": "apt-get update && apt-get -y upgrade",
"vendor_data": ""
}
Server Groups
Servers can be bundled into a server group. These groups may have an anti-affinity policy in use. The policy can be strict, best-effort, or no policy.
- Strict policy doesn't allow servers in the same server group to be on the same host
- Best-effort policy tries to put servers on different hosts, but this is not guaranteed
- No policy doesn't affect server host affinity
A server can belong to only one group. It must be removed from the group if it is to be moved to another group.
The status of server's anti-affinity can be checked via group info or group list endpoints. If the status is met, the server is the only one on that server host.
If the status is unmet, the server is sharing the same server host with another server from the same anti-affinity group.
It is also possible to filter shown server groups with label URL parameters, e.g. ?label=env or ?label=env%3Dprod.
URL parameter can be given multiple times to add more filters (e.g. ?label=env%3Dprod&label=v2), where only server
groups that match all labels are returned.
Label keys are matched case insensitively.
List all server groups
Normal response
{
"server_groups": {
"server_group": [
{
"anti_affinity": "yes",
"anti_affinity_status": [
{
"uuid": "0016dadf-eba4-4331-bd34-a361841f7af1",
"status": "met"
},
{
"uuid": "00c77bbe-fc0e-436f-a753-37f5b5b76270",
"status": "met"
}
],
"labels": {
"label": [
{
"key": "foo",
"value": "bar"
}
]
},
"servers": {
"server": [
"0016dadf-eba4-4331-bd34-a361841f7af2",
"00c77bbe-fc0e-436f-a753-37f5b5b76271"
]
},
"title": "nameserver group",
"uuid": "0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0"
},
{
"anti_affinity": "no",
"anti_affinity_status": null,
"labels": {
"label": [
{
"key": "foo",
"value": "bar"
}
]
},
"servers": {
"server": [
"001789da-3aa4-4431-bd34-b4ad841f23e2"
]
},
"title": "my group",
"uuid": "0bebfe54-7532-4ca4-b8c0-0fa294ea9b7a"
}
]
}
}
Show server group details
Normal response
{
"server_group": {
"anti_affinity": "yes",
"anti_affinity_status": [
{
"uuid": "0016dadf-eba4-4331-bd34-a361841f7af1",
"status": "met"
},
{
"uuid": "00c77bbe-fc0e-436f-a753-37f5b5b76270",
"status": "met"
}
],
"labels": {
"label": [
{
"key": "foo",
"value": "bar"
}
]
},
"servers": {
"server": [
"0016dadf-eba4-4331-bd34-a361841f7af2",
"00c77bbe-fc0e-436f-a753-37f5b5b76271"
]
},
"title": "nameserver group",
"uuid": "0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | GROUP_INVALID | The server group UUID has an invalid value. |
| 403 Forbidden | GROUP_FORBIDDEN | The server group exists, but is owned by another account. |
| 404 Not Found | GROUP_NOT_FOUND | The server group does not exist. |
List servers in a group
Normal response
{
"servers": {
"server": [
"0016dadf-eba4-4331-bd34-a361841f7af2",
"00c77bbe-fc0e-436f-a753-37f5b5b76271"
]
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | GROUP_INVALID | The server group UUID has an invalid value. |
| 403 Forbidden | GROUP_FORBIDDEN | The server group exists, but is owned by another account. |
| 404 Not Found | GROUP_NOT_FOUND | The server group does not exist. |
Create a new server group
{
"server_group": {
"title": "My brand new server group",
"servers": {
"server": [
"00e2dc05-379d-6b90-a354-e5c3f9293918",
"00451e12-46ee-41a0-8a52-1aff9039298a",
"00651e23-44ff-41a0-9a82-2aff9039298b"
]
},
"labels": {
"label": [
{
"key": "foo",
"value": "bar"
}
]
},
"anti_affinity": "yes"
}
}
Normal response
Attributes
| Attributes | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| title | 0-255 characters | no | Server group title. | |
| server | Server UUID or empty | no | Server UUID | |
| anti_affinity | strict / yes / no | no | no | Anti-affinity policy. Strict, yes (best-effort), no |
| (label) key | Lowercased alphabet (a-z), any number (0-9), 1-32 characters | no | Label key | |
| (label) value | 0-255 characters | no | Label value |
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 400 Bad Request | DUPLICATE_LABEL_KEYS | Label keys must be unique. |
| 400 Bad Request | INVALID_LABEL_KEY | Invalid label key in query parameters. |
| 400 Bad Request | INVALID_LABEL_VALUE | Invalid label value in query parameters. |
| 409 Conflict | STRICT_ANTI_AFFINITY_NOT_MET | Can't create a group. Strict anti-affinity is not met |
Modify server group
{
"server_group": {
"title": "New fancy title for the group",
"servers": {
"server": [
"00e2dc05-379d-6b90-a354-e5c3f9293918",
"00451e12-46ee-41a0-8a52-1aff9039298a"
]
},
"anti_affinity": "no"
}
}
Normal response
Attributes
| Attributes | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| title | 0-255 characters | no | Server group title | |
| server | Server UUID or empty | no | Server UUID | |
| anti_affinity | strict / yes / no / | no | no | Anti-affinity policy. Strict, yes (best-effort), no |
| (label) key | 1-32 characters, lowercased alphabet (a-z), any number (0-9), - & _, cannot start with _ |
no | Label key | |
| (label) value | 0-255 characters | no | Label value |
Labels can include specific service labels that cannot be modified. These always start with _ and do not conflict with normal labels.
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 400 Bad Request | GROUP_INVALID | The server group UUID has an invalid value. |
| 403 Forbidden | GROUP_FORBIDDEN | The server group exists, but is owned by another account. |
| 404 Not Found | GROUP_NOT_FOUND | The server group does not exist. |
| 400 Bad Request | DUPLICATE_LABEL_KEYS | Label keys must be unique. |
| 400 Bad Request | INVALID_LABEL_KEY | Invalid label key in query parameters. |
| 400 Bad Request | INVALID_LABEL_VALUE | Invalid label value in query parameters. |
| 409 Conflict | ALREADY_IN_SERVER_GROUP | The server (server uuid) is already in a server group (group uuid) |
| 409 Conflict | STRICT_ANTI_AFFINITY_NOT_MET | Can't modify the group. Strict anti-affinity is not met |
Delete server group
Normal response
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | GROUP_INVALID | The server group UUID has an invalid value. |
| 403 Forbidden | GROUP_FORBIDDEN | The server group exists, but is owned by another account. |
| 404 Not Found | GROUP_NOT_FOUND | The server group does not exist. |
Add a new server to a server group
Normal response
Attributes
| Attributes | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| server | Server UUID or empty | yes | Server UUID |
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 400 Bad Request | GROUP_INVALID | The server group UUID has an invalid value. |
| 403 Forbidden | GROUP_FORBIDDEN | The server group exists, but is owned by another account. |
| 404 Not Found | GROUP_NOT_FOUND | The server group does not exist. |
| 409 Conflict | ALREADY_IN_SERVER_GROUP | The server (server uuid) is already in a server group (group uuid) |
| 409 Conflict | STRICT_ANTI_AFFINITY_NOT_MET | Can't add server to the group. Strict anti-affinity is not met |
Remove server from a server group
DELETE /1.3/server-group/0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0/servers/00235adf-add4-66f1-ef34-e331516bb6a1
Normal response
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 400 Bad Request | GROUP_INVALID | The server group UUID has an invalid value. |
| 403 Forbidden | GROUP_FORBIDDEN | The server group exists, but is owned by another account. |
| 404 Not Found | GROUP_NOT_FOUND | The server group does not exist. |