Server representation.
A list of servers, with the most relevant information, is typically fetched from Servers API. A more detailed information about a specific server can be fetched from Server details API.
When creating a server, one would typically use Builder API to define an instance of a server, and then pass it to Resource creation API to actually create the server.
To create a server, the only required properties are hostname, storageDevices, title, and zone.
import static fi.linuxbox.upcloud.resource.Builder.*
def web1 = server {
hostname = 'web1.example.com'
storageDevices = [
// contents of this list depends... see below.
]
title = 'frontend server 1'
zone = 'fi-hel1'
}
The contents of the storageDevices list depends on whether the operating system (OS) disk of the server is going to be created
Regardless, there are a lot of optional properties that can be set.
import static fi.linuxbox.upcloud.resource.Builder.*
def web1 = server {
// skipping mandatory properties and showing only
// optional properties with their default values:
avoidHost = null
bootOrder = 'disk'
coreNumber = 1
memoryAmount = 256
plan = 'custom'
firewall = 'on'
ipAddresses = [
ipAddress {
access = 'public'
family = 'IPv4'
},
ipAddress {
access = 'public'
family = 'IPv6'
}
]
nicModel = 'e1000'
passwordDelivery = 'email'
timezone = 'UTC'
videoModel = 'vga'
vnc = 'off'
vncPassword = 'password' // actual default is a random string
}
There are a few properties that can not be set when creating a server: host, license, state, tags, uuid, vncHost, and vncPort. Most of these can not be manipulated from client side at all.
While storages and IP addresses can be created with the server, they can not be modified with the server. See Storage and IpAddress class documentation for information on how to add and remove those resources from an existing server.
Tags can not be created with the server. See Tag class documentation for information on how to create and manage tags.
UpCloud provides templates for various operating systems. To clone the operating system disk from such a
template, the template UUID would be fetched from
Storages API by specifying a keyword argument
type: "template"
. Below, a storage UUID of a Debian template is chosen.
import static fi.linuxbox.upcloud.resource.Builder.*
def web1 = server {
// skipping all the other properties and showing only
// storageDevices for cloning a template:
storageDevices = [
storageDevice {
action = "clone"
storage = "01000000-0000-4000-8000-000020030100"
title = "Debian from a template"
size = 50
tier = "maxiops"
}
// optionally 1-3 additional storageDevices can be
// specified here, each with action create or attach
]
}
Templates allows UpCloud to preconfigure the operating system at the time of server initialization. For example, UpCloud can apply the given hostname to the OS configuration, and set the administrative account password (which would then be delivered according to passwordDelivery property).
Furthermore, if the template is a Linux template, UpCloud can create an additional user account on the server if our representation provides the optional loginUser property.
import static fi.linuxbox.upcloud.resource.Builder.*
def web1 = server {
// skipping all the other properties and only showing
// the optional loginUser property
loginUser = loginUser {
username = 'webmaster'
createPassword = 'no'
sshKeys = [
"ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
"ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
]
}
}
Another Linux template addition is the ability to execute an arbitrary provisioning script by means of the optional userData property.
import static fi.linuxbox.upcloud.resource.Builder.*
def web1 = server {
// skipping all the other properties and only showing
// the optional userData property
userData = """
grep webmaster /etc/* > $HOME/install.log
"""
}
See the property descriptions for more details.
This use case provides a simple way to create identical servers. Below, storage UUID of another storage that belongs to the same account and resides on the same zone is used as the source of the cloning.
import static fi.linuxbox.upcloud.resource.Builder.*
def web1 = server {
// skipping all the other properties and showing only
// storageDevices for cloning another servers' storages:
storageDevices = [
storageDevice {
action = "clone"
storage = "0169b4f8-051c-4a86-9484-f5b798249949"
}
// optionally 1-3 additional storageDevices can be
// specified here, each with action create or attach
]
}
This is different from cloning a template, since UpCloud has no way of knowing what's inside the storages, and no safe way to do any configuration.
UpCloud provides installation CD-ROMs for various operating systems. To install the operating system from
such a CD-ROM, the CD-ROM UUID would be fetched from
Storages API by specifying a keyword argument
type: "cdrom"
. Below, a storage UUID of a Debian CD-ROM is chosen.
import static fi.linuxbox.upcloud.resource.Builder.*
def web1 = server {
// skipping all the other properties and showing only
// storageDevices for installing from a CD-ROM:
storageDevices = [
storageDevice {
action = "create"
title = "Debian from scratch"
size = 20
tier = "maxiops"
},
storageDevice {
action = "attach"
storage = "01000000-0000-4000-8000-000020010301"
type = "cdrom"
}
// optionally 1-2 additional storageDevices can be
// specified here, each with action create or attach
]
}
One would typically use VNC to connect to the server for stepping through the installation.
Fields inherited from class | Fields |
---|---|
class Resource |
__$stMC |
Type | Name and description |
---|---|
String |
avoidHost Host to avoid. |
String |
bootOrder The storage device boot order: disk , cdrom , disk,cdrom , or cdrom,disk . |
String |
coreNumber Number of CPU cores on this server. |
String |
firewall Whether the firewall is enabled for this server: on or off . |
Long |
host Host ID that hosts this virtual machine. |
String |
hostname Hostname of this server. |
List<IpAddress> |
ipAddresses IP addresses of this server. |
Integer |
license Amount of credits per hour per CPU required by this server license. |
LoginUser |
loginUser Administrative account to create. |
String |
memoryAmount Amount of main memory in megabytes on this server. |
String |
nicModel Type of network interface card on this server: e1000 , virtio , or rtl8139 . |
String |
passwordDelivery Delivery method for administrative accounts' password: none , email , or sms . |
String |
plan Name of the preconfigured server plan, or custom , for this server. |
String |
planIpv4Bytes Number of bytes of IPv4 traffic included in the plan. |
String |
planIpv6Bytes Number of bytes of IPv6 traffic included in the plan. |
String |
state Server state. |
List<StorageDevice> |
storageDevices Storage devices attached to this server. |
List<String> |
tags Tags assigned to this server. |
String |
timezone The hardware clock timezone for this server. |
String |
title Title of this server. |
String |
userData A valid URL or the contents of a Bash script. |
String |
uuid Unique identifier of this server. |
String |
videoModel Type of video card attached to this server: vga or cirrus . |
String |
vnc Whether VNC is enabled on this server: on or off . |
String |
vncHost Hostname where VNC is available for this server. |
String |
vncPassword VNC password. |
String |
vncPort TCP port number on vncHost where the VNC server is listening for this server. |
String |
zone Zone ID where this server is located. |
Methods inherited from class | Name |
---|---|
class Resource |
setProperty, getProperty, toString, asType, getMetaClass, setMetaClass, wrapper, propertyMissing, propertyMissing, methodMissing, proj, invokeMethod, this$dist$invoke$1, this$dist$set$1, this$dist$get$1, super$1$toString, getHTTP, getSESSION, getMETA, wait, wait, wait, equals, hashCode, getClass, notify, notifyAll |
class Object |
wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll |
Host to avoid.
When creating a new server, this can be set to a host property of another server in order to create High Availability -environment.
This is not available in the server detail or list response, and can not be modified after server creation.
The storage device boot order: disk
, cdrom
, disk,cdrom
, or cdrom,disk
.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to disk
. This can also be modified without stopping the server.
Number of CPU cores on this server.
This is available in the server details response, and can optionally be set when creating a server where this defaults to a smallest possible value. If modified, the server must be stopped.
If set when creating or modifying a server, this has to be a valid combination with memoryAmount (see UpCloud.serverSizes). If plan is also set, then this must match with the selected plan.
Whether the firewall is enabled for this server: on
or off
.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to on
. This can also be modified without stopping the server.
Host ID that hosts this virtual machine.
This is available in the server details response, and can not be set when creating or modifying a server.
Hostname of this server.
This is available in the server details and list responses.
This must be set when creating a server. When creating the server OS disk by cloning from a template, this hostname will be reflected in the configuration files on the OS disk. When creating the server in any other way, this hostname will not automatically be set in the OS configuration.
This hostname can also be modified without stopping the server, but the modification will not automatically be changed to the configuration files on the OS disk.
This has to look like a DNS hostname or label, but this is not automatically added to any DNS server.
IP addresses of this server.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to one IPv4
and one IPv6
address (both public
).
See IpAddress class documentation for information about managing these after server creation.
Amount of credits per hour per CPU required by this server license.
This property is the sum of all the attached storages' license properties.
This is available in the server details response, and can not be set when creating or modifying a server.
Administrative account to create.
This can be set when creating a server from template. This is not available in server detail or list responses, and can not be modified after server creation.
Amount of main memory in megabytes on this server.
This is available in the server details response, and can optionally be set when creating a server where this defaults to a smallest possible value. If modified, the server must be stopped.
If set when creating or modifying a server, this has to be a valid combination with coreNumber (see UpCloud.serverSizes). If plan is also set, then this must match with the selected plan.
Type of network interface card on this server: e1000
, virtio
, or rtl8139
.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to e1000
. This can also be modified without stopping the server.
Delivery method for administrative accounts' password: none
, email
, or sms
.
This can optionally be set when creating a server, and defaults to email
.
This is not available in server detail or list responses, and can not be modified after server creation.
Name of the preconfigured server plan, or custom
, for this server.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to custom
. This can also be modified without stopping the server.
If this is set to something else than custom
, this must match a valid plan name from
UpCloud.plans. If coreNumber and/or memoryAmount
are also set, they must match the selected plan.
Number of bytes of IPv4 traffic included in the plan.
This is available in the server listing and server details responses. This can not be modified.
Number of bytes of IPv6 traffic included in the plan.
This is available in the server listing and server details responses. This can not be modified.
Server state.
This is available in the server details response, and can not be set when creating or modifying a server.
Storage devices attached to this server.
This is available in the server details response, and must be set to 1-4 storage devices when creating a server. Modifying these after server creation needs to go through Resource creation and Storage management APIs.
Tags assigned to this server.
This is available in the server details response, and can not be set when creating or modifying a server.
The hardware clock timezone for this server.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to UTC
. This can also be modified without stopping the server.
If set, must be a valid timezone identifier (see UpCloud.timezones).
Title of this server.
This is available in the server details response, and must be set when creating a server. This can also be modified without stopping the server.
A valid URL or the contents of a Bash script.
When creating a server from a Linux template, this can be set and it will be executed with root privileges upon server initialization. Pay special attention to verifying it. This has no meaning after server creation.
Unique identifier of this server.
This is available in the server details response, and can not be set when creating or modifying a server.
Type of video card attached to this server: vga
or cirrus
.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to vga
. This can also be modified without stopping the server.
Whether VNC is enabled on this server: on
or off
.
This is available in the server details response, and can optionally be set when creating a server where
this defaults to off
. This can also be modified without stopping the server.
Hostname where VNC is available for this server.
This is available in the server details response, and can not be set when creating or modifying a server.
VNC password.
This is available in the server details response, and can optionally be set when creating a server where this defaults to a randomly generated string. This can also be modified without stopping the server.
If set, must be 8-32 alphanumeric characters (a-zA-Z0-9
).
TCP port number on vncHost where the VNC server is listening for this server.
This is available in the server details response, and can not be set when creating or modifying a server.
Zone ID where this server is located.
This is available in the server details response, and must be set when creating a server. See UpCloud.zones. This can not be modified.