Class: UpcloudApi

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

Overview

Class to serve as a Ruby API for the UpCloud HTTP API

Constant Summary collapse

VERSION = 
"1.5.0".freeze

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



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

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



39
40
41
42
43
 
# File 'lib/upcloud_api.rb', line 39

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

#attach_storage(server_uuid, storage_uuid:, type: "disk", address: nil) ⇒ 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:

to next available address.

Parameters:

  • server_uuid —

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

  • storage_uuid —

    UUID of the storage that will be attached.

  • 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



402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/upcloud_api.rb', line 402

def attach_storage(server_uuid, storage_uuid:, type: "disk", address: nil)
  data = {
    "storage_device" => {
      "type" => type,
      "storage" => storage_uuid
    }
  }
  data["storage_device"]["address"] = address unless address.nil?

  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

allowed value is “hdd” with the server

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

  • title —

    Name of the disk

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

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



352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
 
# File 'lib/upcloud_api.rb', line 352

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, title:) ⇒ Object

Creates backup from a storage.

This operation is asynchronous.

Calls /1.2/storage/#uuid/backup

Parameters:

  • storage_uuid —

    UUID of the storage to be backed-up

  • title —

    Name of the backup



447
448
449
450
451
452
453
454
455
456
457
458
459
 
# File 'lib/upcloud_api.rb', line 447

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:, ip_addresses: :all) ⇒ 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
}

ip_addresses should be an array containing :public, :private and/or :ipv6. It defaults to :all, which means the server will get public IPv4, private IPv4 and public IPv6 addresses.

Returns HTTParty response



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/upcloud_api.rb', line 100

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

  if ip_addresses != :all
    ips = []
    ips << { "access" => "public", "family" => "IPv4" } if ip_addresses.include? :public
    ips << { "access" => "private", "family" => "IPv4" } if ip_addresses.include? :private
    ips << { "access" => "public", "family" => "IPv6" } if ip_addresses.include? :ipv6

    data["server"]["ip_addresses"] = {}
    data["server"]["ip_addresses"]["ip_address"] = ips
  end

  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

allowed value is “hdd” with the server backups will be automatically created.

Parameters:

  • size —

    Size of the storage in gigabytes

  • tier (defaults to: "maxiops") —

    Type of the disk. maxiops is SSD powered disk, other

  • title —

    Name of the disk

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

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

  • backup_rule (defaults to: nil) —

    Hash of backup information. If not given, no



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/upcloud_api.rb', line 292

def create_storage(size:, tier: "maxiops", title:, zone: "fi-hel1",
                   backup_rule: nil)
  data = {
    "storage" => {
      "size" => size,
      "tier" => tier,
      "title" => title,
      "zone" => zone
    }
  }
  data["storage"]["backup_rule"] = backup_rule unless backup_rule.nil?

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

  response
end

#defavorite_storage(storage_uuid) ⇒ Object

Removes storage to favorites

Calls POST /1.2/storage/#storage_uuid/favorite.

Parameters:

  • storage_uuid —

    UUID of the storage to be removed from favorites



490
491
492
493
494
 
# File 'lib/upcloud_api.rb', line 490

def defavorite_storage(storage_uuid)
  response = delete "storage/#{storage_uuid}/favorite"

  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



149
150
151
152
153
 
# File 'lib/upcloud_api.rb', line 149

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.



503
504
505
506
507
 
# File 'lib/upcloud_api.rb', line 503

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

  response
end

#detach_storage(server_uuid, 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:

  • server_uuid —

    UUID of the server from which to detach the storage.

  • address —

    Address where the storage that will be detached resides.



425
426
427
428
429
430
431
432
433
434
435
436
437
 
# File 'lib/upcloud_api.rb', line 425

def detach_storage(server_uuid, address:)
  data = {
    "storage_device" => {
      "address" => address
    }
  }

  json = JSON.generate data

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

  response
end

#favorite_storage(storage_uuid) ⇒ Object

Adds storage to favorites

Calls POST /1.2/storage/#storage_uuid/favorite.

Parameters:

  • storage_uuid —

    UUID of the storage to be included in favorites



479
480
481
482
483
 
# File 'lib/upcloud_api.rb', line 479

def favorite_storage(storage_uuid)
  response = post "storage/#{storage_uuid}/favorite"

  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



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

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.



136
137
138
139
140
141
142
 
# File 'lib/upcloud_api.rb', line 136

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

backups will be automatically created.

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



324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/upcloud_api.rb', line 324

def modify_storage(storage_uuid, size:, title:, backup_rule: nil)
  data = {
    "storage" => {
      "size" => size,
      "title" => title
    }
  }
  data["storage"]["backup_rule"] = backup_rule unless backup_rule.nil?

  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 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.

Defaults to :soft. close cleanly. Only affects :soft type. :destroy hard stops the server and :ignore stops the operation 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.

  • timeout (defaults to: nil) —

    Time after server will be hard stopped if it did not

  • timeout_action (defaults to: :ignore) —

    What will happen when timeout happens.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/upcloud_api.rb', line 227

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

  json = JSON.generate data

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

  response
end

#restore_backup(backup_uuid) ⇒ Object

Restores a backup.

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

Calls /1.2/storage/#backup_uuid/restore.

Parameters:

  • backup_uuid —

    UUID of the backup



468
469
470
471
472
 
# File 'lib/upcloud_api.rb', line 468

def restore_backup(backup_uuid)
  response = post "storage/#{backup_uuid}/restore"

  response
end

#server_configurations ⇒ Object

Returns available server configurations.

Calls GET /1.2/server_size



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

def server_configurations
  response = get "server_size"
  response["server_sizes"]["server_size"]
end

#server_details(uuid) ⇒ Object

Shows details of a server.

Calls GET /1.2/server/#uuid

Parameters:

  • uuid —

    from UpcloudApi#servers



68
69
70
71
72
 
# File 'lib/upcloud_api.rb', line 68

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



57
58
59
60
61
 
# File 'lib/upcloud_api.rb', line 57

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



160
161
162
163
164
 
# File 'lib/upcloud_api.rb', line 160

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.

Defaults to :soft. close cleanly. Only affects :soft type. has really stopped.

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.

  • timeout (defaults to: nil) —

    Time after server will be hard stopped if it did not

  • asynchronous (defaults to: false) —

    If false, this call will wait until the server



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/upcloud_api.rb', line 186

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"].nil?
      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



269
270
271
272
273
 
# File 'lib/upcloud_api.rb', line 269

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



258
259
260
261
262
 
# File 'lib/upcloud_api.rb', line 258

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



77
78
79
80
81
 
# File 'lib/upcloud_api.rb', line 77

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

#templatize_storage(storage_uuid, title:) ⇒ Object

Templatizes existing storage.

This operation is asynchronous.

Calls POST /1.2/storage/#uuid/templatize

Parameters:

  • storage_uuid —

    UUID of the storage that will be templatized

  • title —

    Name of the template storage



376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/upcloud_api.rb', line 376

def templatize_storage(storage_uuid, title:)
  data = {
    "storage" => {
      "title" => title
    }
  }

  json = JSON.generate data

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

  response
end