Class: UpcloudApi

Inherits:
Object
  • Object
show all
Defined in:
lib/upcloud_api.rb,
lib/upcloud_api/version.rb

Constant Summary collapse

VERSION = 
"1.3.0"

Instance Method Summary collapse

Constructor Details

#initialize(user, password) ⇒ UpcloudApi

Returns a new instance of UpcloudApi.

Parameters:

  • user (String) —

    Upcloud API account

  • password (String) —

    Upcloud API password



10
11
12
13
14
 
# File 'lib/upcloud_api.rb', line 10

def initialize user, password
    @user = user
    @password = password
    @auth = { username: @user, password: @password }
end

Instance Method Details

#account_information ⇒ Object

Returns available credits.

Calls GET /1.2/acccount



32
33
34
35
36
 
# File 'lib/upcloud_api.rb', line 32

def 
    response = get "account"
    data = JSON.parse response.body
    data["acccount"]["credits"]
end

#attach_storage(type: "disk", address: nil, server_uuid:, storage_uuid:) ⇒ Object

Attaches a storage to a server. Server must be stopped before the storage can be attached.

Calls POST /1.2/server/#server_uuid/storage/attach

Valid values for address are: ide:[01] / scsi:0: / virtio:

Parameters:

  • type (defaults to: "disk") —

    Type of the disk. Valid values are “disk” and “cdrom”.

  • address (defaults to: nil) —

    Address where the disk will be attached to. Defaults to next available address.

  • server_uuid —

    UUID of the server where the disk will be attached to.

  • storage_uuid —

    UUID of the storage that will be attached.



343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/upcloud_api.rb', line 343

def attach_storage type: "disk", address: nil, server_uuid:, storage_uuid:
    data = {
        "storage_device" => {
            "type" => type,
            "address" => address,
            "storage" => storage_uuid
        }
    }

    json = JSON.generate data

    response = post "server/#{server_uuid}/storage/attach", json

    response
end

#clone_storage(storage_uuid, zone: "fi-hel1", title:, tier: "maxiops") ⇒ Object

Clones existing storage.

This operation is asynchronous.

Calls POST /1.2/storage/#uuid/clone

backup_rule should be hash with following attributes:

  • interval # allowed values: daily / mon / tue / wed / thu / fri / sat / sun

  • time # allowed values: 0000-2359

  • retention # How many days backup will be kept. Allowed values: 1-1095

Parameters:

  • storage_uuid —

    UUID of the storage that will be modified

  • tier (defaults to: "maxiops") —

    Type of the disk. maxiops is SSD powered disk, other allowed value is “hdd”

  • title —

    Name of the disk

  • zone (defaults to: "fi-hel1") —

    Where the disk will reside. Needs to be within same zone with the server



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/upcloud_api.rb', line 317

def clone_storage storage_uuid, zone: "fi-hel1", title:, tier: "maxiops"
    data = {
        "storage" => {
            "zone" => zone,
            "title" => title,
            "tier" => tier
        }
    }

    json = JSON.generate data

    response = post "storage/#{storage_uuid}/clone", json

    response
end

#create_backup(storage_uuid) ⇒ Object

Restores a backup.

If the storage is attached to server, the server must first be stopped.

Calls /1.2/storage/#uuid/restore.

Parameters:

  • storage_uuid —

    TODO: is this supposed to be UUID of the storage or the backup?



386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/upcloud_api.rb', line 386

def create_backup storage_uuid, title:
    data = {
        "storage" => {
            "title" => title
        }
    }

    json = JSON.generate data

    response = post "storage/#{storage_uuid}/backup", json

    response
end

#create_server(zone: "fi-hel1", title:, hostname:, core_number: 1, memory_amount: 1024, storage_devices:) ⇒ Object

Creates new server from template.

Calls POST /1.2/server

Storage devices should be array of hashes containing following data:

{
"action" => "clone" # Can be "create", "clone" or "attach"
"storage" => template_uuid, # Should be passed only for "clone" or "attach"
"title" => disk_name # Name of the storage,
"tier" => "maxiops" # No sense using HDD any more
}

Returns HTTParty response



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/upcloud_api.rb', line 90

def create_server zone: "fi-hel1", title:, hostname:, core_number: 1, memory_amount: 1024, storage_devices:
    data = {
        "server" => {
            "zone" => zone,
            "title" => title,
            "hostname" => hostname,
            "core_number" => core_number,
            "memory_amount" => memory_amount,
            "storage_devices" => { "storage_device" => storage_devices }
        }
    }

    json = JSON.generate data
    response = post "server", json

    response
end

#create_storage(size:, tier: "maxiops", title:, zone: "fi-hel1", backup_rule: nil) ⇒ Object

Creates new storage.

Calls POST /1.2/storage

backup_rule should be hash with following attributes:

  • interval # allowed values: daily / mon / tue / wed / thu / fri / sat / sun

  • time # allowed values: 0000-2359

  • retention # How many days backup will be kept. Allowed values: 1-1095

Parameters:

  • size —

    Size of the storage in gigabytes

  • tier (defaults to: "maxiops") —

    Type of the disk. maxiops is SSD powered disk, other allowed value is “hdd”

  • title —

    Name of the disk

  • zone (defaults to: "fi-hel1") —

    Where the disk will reside. Needs to be within same zone with the server

  • backup_rule (defaults to: nil) —

    Hash of backup information. If not given, no backups will be automatically created.



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/upcloud_api.rb', line 255

def create_storage size:, tier: "maxiops", title:, zone: "fi-hel1", backup_rule: nil
    data = {
        "storage" => {
            "size" => size,
            "tier" => tier,
            "title" => title,
            "zone" => zone,
            "backup_rule" => backup_rule
        }
    }

    json = JSON.generate data

    response = post "storage", json

    response
end

#delete_server(server_uuid) ⇒ Object

Deletes a server.

In order to delete a server, the server must be stopped first.

Calls DELETE /1.2/server/#uuid



129
130
131
132
133
 
# File 'lib/upcloud_api.rb', line 129

def delete_server server_uuid
    response = delete "server/#{server_uuid}"

    response
end

#delete_storage(storage_uuid) ⇒ Object

Deletes a storage.

The storage must be in “online” state and it must not be attached to any server. Backups will not be deleted.

Parameters:

  • storage_uuid —

    UUID of the storage that will be deleted.



419
420
421
422
423
 
# File 'lib/upcloud_api.rb', line 419

def delete_storage storage_uuid
    response = delete "storage/#{storage_uuid}"

    response
end

#detach_storage(address) ⇒ Object

Detaches storage from a server. Server must be stopped before the storage can be detached.

Calls POST /1.2/server/#server_uuid/storage/detach

Parameters:

  • address —

    Address where the storage that will be detached resides.



364
365
366
367
368
369
370
371
372
373
374
375
376
 
# File 'lib/upcloud_api.rb', line 364

def detach_storage address
    data = {
        "storage_device" => {
            "address" => address
        }
    }

    json = JSON.generate data

    response = post "server/#{server_uuid}/storage/detach", json

    response
end

#login ⇒ Object

Tests that authentication to Upcloud works.

This is not required to use, as authentication is used with HTTP basic auth with each request.

Calls GET /1.2/server

Returns true in success, false if not



24
25
26
27
 
# File 'lib/upcloud_api.rb', line 24

def 
    response = get "server"
    response.code == 200
end

#modify_server(server_uuid, params) ⇒ Object

Modifies existing server.

In order to modify a server, the server must be stopped first.

Calls PUT /1.2/server/#uuid

Parameters:

  • server_uuid (String) —

    UUID of the server that will be modified.

  • params (Hash) —

    Hash of params that will be passed to be changed.



116
117
118
119
120
121
122
 
# File 'lib/upcloud_api.rb', line 116

def modify_server server_uuid, params
    data = { "server" => params }
    json = JSON.generate data
    response = put "server/#{server_uuid}", json

    response
end

#modify_storage(storage_uuid, size:, title:, backup_rule: nil) ⇒ Object

Modifies existing storage.

Calls PUT /1.2/storage/#uuid

backup_rule should be hash with following attributes:

  • interval # allowed values: daily / mon / tue / wed / thu / fri / sat / sun

  • time # allowed values: 0000-2359

  • retention # How many days backup will be kept. Allowed values: 1-1095

Parameters:

  • storage_uuid —

    UUID of the storage that will be modified

  • size —

    Size of the storage in gigabytes

  • title —

    Name of the disk

  • backup_rule (defaults to: nil) —

    Hash of backup information. If not given, no backups will be automatically created.



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/upcloud_api.rb', line 286

def modify_storage storage_uuid, size:, title:, backup_rule: nil
    data = {
        "storage" => {
            "size" => size,
            "title" => title,
            "backup_rule" => backup_rule
        }
    }

    json = JSON.generate data

    response = put "storage/#{storage_uuid}", json

    response
end

#restart_server(server_uuid, type: :soft, timeout: nil, timeout_action: :ignore) ⇒ Object

Restarts down a server that is currently running

Calls POST /1.2/server/#uuid/restart

Hard shutdown means practically same as taking the power cable off from the computer. Soft shutdown sends ACPI signal to the server, which should then automatically handle shutdown routines by itself. If timeout is given, server will be forcibly shut down after the timeout has expired.

server if timeout happens. Default is :ignore.

Parameters:

  • server_uuid —

    UUID of the server

  • type (defaults to: :soft) —

    Type of the shutdown. Available types are :hard and :soft. Defaults to :soft.

  • timeout (defaults to: nil) —

    Time after server will be hard stopped if it didn’t close cleanly. Only affects :soft type.

  • timeout_action (defaults to: :ignore) —

    What will happen when timeout happens. :destroy hard stops the server and :ignore makes



195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/upcloud_api.rb', line 195

def restart_server server_uuid, type: :soft, timeout: nil, timeout_action: :ignore
    data = {
        "stop_server" => {
            "stop_type" => type.to_s
        }
    }
    data["stop_server"]["timeout"] = timeout unless timeout.nil?

    json = JSON.generate data

    response = post "server/#{server_uuid}/restart", json

    response
end

#server_details(uuid) ⇒ Object

Shows details of a server.

Calls GET /1.2/server/#uuid

Parameters:

  • uuid —

    from UpcloudApi#servers



61
62
63
64
65
 
# File 'lib/upcloud_api.rb', line 61

def server_details uuid
    response = get "server/#{uuid}"
    data = JSON.parse response.body
    data
end

#servers ⇒ Object

Lists servers associated with the account

Calls GET /1.2/server

Returns array of servers with values

  • zone

  • core_number

  • title

  • hostname

  • memory_amount

  • uuid

  • state



50
51
52
53
54
 
# File 'lib/upcloud_api.rb', line 50

def servers
    response = get "server"
    data = JSON.parse response.body
    data["servers"]["server"]
end

#start_server(server_uuid) ⇒ Object

Starts server that is shut down.

Calls POST /1.2/server/#uuid/start

Parameters:

  • server_uuid —

    UUID of the server



140
141
142
143
144
 
# File 'lib/upcloud_api.rb', line 140

def start_server server_uuid
    response = post "server/#{server_uuid}/start"

    response
end

#stop_server(server_uuid, type: :soft, timeout: nil, asynchronous: false) ⇒ Object

Shuts down a server that is currently running

Calls POST /1.2/server/#uuid/stop

Hard shutdown means practically same as taking the power cable off from the computer. Soft shutdown sends ACPI signal to the server, which should then automatically handle shutdown routines by itself. If timeout is given, server will be forcibly shut down after the timeout has expired.

Raises Timeout::Error in case server does not shut down in 300 seconds in non-asynchronous mode.

Parameters:

  • server_uuid —

    UUID of the server

  • type (defaults to: :soft) —

    Type of the shutdown. Available types are :hard and :soft. Defaults to :soft.

  • timeout (defaults to: nil) —

    Time after server will be hard stopped if it didn’t close cleanly. Only affects :soft type.

  • asynchronous (defaults to: false) —

    If false, this call will wait until the server has really stopped.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/upcloud_api.rb', line 160

def stop_server server_uuid, type: :soft, timeout: nil, asynchronous: false
    data = {
        "stop_server" => {
            "stop_type" => type.to_s
        }
    }
    data["stop_server"]["timeout"] = timeout unless timeout.nil?

    json = JSON.generate data

    response = post "server/#{server_uuid}/stop", json

    return response if asynchronous

    Timeout::timeout 300 do
        loop do
            details = server_details server_uuid
            return response if details["server"]["state"] == "stopped"
        end
    end
end

#storage_details(storage_uuid) ⇒ Object

Shows detailed information of single storage.

Calls GET /1.2/storage/#uuid

Parameters:

  • storage_uuid —

    UUID of the storage



235
236
237
238
239
 
# File 'lib/upcloud_api.rb', line 235

def storage_details storage_uuid
    response = get "storage/#{storage_uuid}"
    data = JSON.parse response.body
    data
end

#storages(type: nil) ⇒ Object

Lists all storages or storages matching to given type.

Calls GET /1.2/storage or /1.2/storage/#type

Available types:

  • public

  • private

  • normal

  • backup

  • cdrom

  • template

  • favorite

Parameters:

  • type (defaults to: nil) —

    Type of the storages to be returned on nil



224
225
226
227
228
 
# File 'lib/upcloud_api.rb', line 224

def storages type: nil
    response = get(type && "storage/#{type}" || "storage")
    data = JSON.parse response.body
    data
end

#templates ⇒ Object

Lists templates available from Upcloud

Calls GET /1.2/storage/template



70
71
72
73
74
 
# File 'lib/upcloud_api.rb', line 70

def templates
    response = get "storage/template"
    data = JSON.parse response.body
    data
end