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 = 
"2.1.1".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

Returns:

  • available credits in the account as a string.



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

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

#add_tag_to_server(server_uuid, tags) ⇒ Object

Attaches one or more tags to a server.

Calls POST /1.2/server/uuid/tag/tags.

Parameters:

  • server_uuid (String) —

    UUID of the server

  • tags (Array, String) —

    Tags that will be attached to the server

Returns:

  • HTTParty response object.



877
878
879
880
881
 
# File 'lib/upcloud_api.rb', line 877

def add_tag_to_server server_uuid, tags
  tag = (tags.respond_to? :join && tags.join(",") || tags)

  post "server/#{server_uuid}/tag/#{tag}"
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:

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 to next available address.

Returns:

  • HTTParty response object.



531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'lib/upcloud_api.rb', line 531

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

#change_ip_address_ptr(ip_address, ptr_record) ⇒ Object

Note:

Can only be set to public IP addresses.

Changes given IP address’s PTR record.

Calls PUT /1.2/ip_address.

Returns:

  • HTTParty response object.



974
975
976
977
978
979
980
981
982
983
 
# File 'lib/upcloud_api.rb', line 974

def change_ip_address_ptr ip_address, ptr_record
  data = {
    "ip_address" => {
      "ptr_record" => ptr_record
    }
  }
  json = JSON.generate data

  put "ip_address/#{ip_address}", json
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.

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

Returns:

  • HTTParty response object.



477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
 
# File 'lib/upcloud_api.rb', line 477

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

Returns:

  • HTTParty response object.



580
581
582
583
584
585
586
587
588
589
590
591
592
 
# File 'lib/upcloud_api.rb', line 580

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

  json = JSON.generate data

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

  response
end

#create_firewall_rule(server_uuid, params) ⇒ Object

Creates new firewall rule to a server specified by server_uuid.

Calls POST /1.2/server/server_uuid/firewall_rule.

params should contain data as documented in Upcloud’s API: www.upcloud.com/api/1.2.3/11-firewall/#create-firewall-rule . It should not contain “firewall_rule” wrapper hash, but only the values inside a hash.

Examples:

params contents

{
 "position": "1",
 "direction": "in",
 "family": "IPv4",
 "protocol": "tcp",
 "source_address_start": "192.168.1.1",
 "source_address_end": "192.168.1.255",
 "source_port_end": "",
 "source_port_start": "",
 "destination_address_start": "",
 "destination_address_end": "",
 "destination_port_start": "22",
 "destination_port_end": "22",
 "icmp_type": "",
 "action": "accept"
}

Parameters:

  • server_uuid (String) —

    UUID of server

  • params (Hash) —

    Parameters for the firewall rule.

Returns:

  • HTTParty response object.



735
736
737
738
739
740
741
742
743
744
745
 
# File 'lib/upcloud_api.rb', line 735

def create_firewall_rule server_uuid, params
  data = {
    "firewall_rule" => params
  }

  json = JSON.generate data

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

  response
end

#create_server(zone: "fi-hel1", title:, hostname:, core_number: 1, memory_amount: 1024, storage_devices:, ip_addresses: :all, plan: nil, login_user: nil, other: nil) ⇒ Object

Creates new server from template.

Calls POST /1.2/server.

:all, which means the server will get public IPv4, private IPv4 and public IPv6 addresses.

Examples:

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
}

login_user should be following hash or nil

{
  "username": "upclouduser",
  "ssh_keys": {
    "ssh_key": [
       "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
       "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
     ]
  }
}

Parameters:

  • plan (String) (defaults to: nil) —

    Preconfigured plan for the server. If nil, a custom plan will be created from input data, otherwise this overrides custom configuration. Predefined plans can be fetched with #plans.

  • ip_addresses (defaults to: :all) —

    should be an array containing :public, :private and/or :ipv6. It defaults to

  • other (Hash) (defaults to: nil) —

    Other optional arguments create_server API call takes. See Upcloud’s documentation for possible values.

Returns:

  • HTTParty response object.



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/upcloud_api.rb', line 174

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

  if plan.nil?
      data["server"]["core_number"] = core_number
      data["server"]["memory_amount"] = memory_amount
  else
      data["server"]["plan"] = plan
  end

  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

  unless .nil?
      data["login_user"] = 
  end

  unless other.nil?
      data.merge! other
  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.

Examples:

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.

Returns:

  • HTTParty response object.



413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/upcloud_api.rb', line 413

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

#create_tag(server_uuid, params) ⇒ Object

Creates new tag.

Calls POST /1.2/tag.

params should contain following data

name        *required*
description
servers     *required*

Examples:

params hash’s contents

{
  "name": "DEV", # required
  "description": "Development servers",
  "servers":  [
    "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    ".."
  ]
}

Response body

{
  "name": "DEV",
  "description": "Development servers",
  "servers": {
    "server": [
      "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
    ]
  }
}

Parameters:

  • server_uuid (String) —

    UUID of server

  • params (Hash) —

    Parameters for the firewall rule.

Returns:

  • Tag parameters as Hash or HTTParty response object in case of error.



821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
 
# File 'lib/upcloud_api.rb', line 821

def create_tag server_uuid, params
  data = {
    "tag" => params
  }
  temp = data["servers"]
  data["servers"] = { "server" => temp }

  json = JSON.generate data

  response = post "tag", json
  return response unless response.code == 201

  body = JSON.parse response.body
  body["tag"]
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

Returns:

  • HTTParty response object.



629
630
631
632
633
 
# File 'lib/upcloud_api.rb', line 629

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

Returns:

  • HTTParty response object.



241
242
243
244
245
 
# File 'lib/upcloud_api.rb', line 241

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.

Returns:

  • HTTParty response object.



644
645
646
647
648
 
# File 'lib/upcloud_api.rb', line 644

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

  response
end

#delete_tag(tag) ⇒ Object

Deletes existing tag.

Calls DELETE /1.2/tag/tag.

Returns:

  • HTTParty response object.



865
866
867
 
# File 'lib/upcloud_api.rb', line 865

def delete_tag tag
  delete "tag/#{tag}"
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.

Returns:

  • HTTParty response object.



556
557
558
559
560
561
562
563
564
565
566
567
568
 
# File 'lib/upcloud_api.rb', line 556

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

Returns:

  • HTTParty response object.



616
617
618
619
620
 
# File 'lib/upcloud_api.rb', line 616

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

  response
end

#firewall_rules(server_uuid) ⇒ Object

Lists firewall rules of a server.

Calls POST /1.2/server/uuid/firewall_rule.

Examples:

Return values

[
 {
   "action": "accept",
   "destination_address_end": "",
   "destination_address_start": "",
   "destination_port_end": "80",
   "destination_port_start": "80",
   "direction": "in",
   "family": "IPv4",
   "icmp_type": "",
   "position": "1",
   "protocol": "",
   "source_address_end": "",
   "source_address_start": "",
   "source_port_end": "",
   "source_port_start": ""
 }
]

Parameters:

  • server_uuid (String) —

    UUID of server

Returns:

  • Array of firewall rules



697
698
699
700
701
702
 
# File 'lib/upcloud_api.rb', line 697

def firewall_rules server_uuid
  response = get "server/#{server_uuid}/firewall_rule"

  data = JSON.parse response.body
  data["firewall_rules"]["firewall_rule"]
end

#ip_address_details(ip_address) ⇒ Hash

Gives details of specific IP address.

Calls GET /1.2/ip_address/ip_address.

Examples:

Return hash

{
  "access": "public",
  "address": "0.0.0.0"
  "family": "IPv4",
  "part_of_plan": "yes",
  "ptr_record": "test.example.com",
  "server": "009d64ef-31d1-4684-a26b-c86c955cbf46",
}

Parameters:

  • ip_address (String) —

    IP address to get details for.

Returns:

  • (Hash) —

    details of an IP address



935
936
937
938
939
 
# File 'lib/upcloud_api.rb', line 935

def ip_address_details ip_address
  response = get "ip_address/#{ip_address}"
  body = JSON.parse response.body
  body["ip_address"]
end

#ip_addresses ⇒ Hash

Lists all IP addresses visible to user specified in contructor along with their information and UUIDs of the servers they are bound to.

Calls GET /1.2/ip_address.

Examples:

Return hash

[
  {
    "access": "private",
    "address": "10.0.0.0",
    "family": "IPv4",
    "ptr_record": "",
    "server": "0053cd80-5945-4105-9081-11192806a8f7"
  }
]

Returns:

  • (Hash) —

    details of IP addresses



913
914
915
916
917
 
# File 'lib/upcloud_api.rb', line 913

def ip_addresses
  response = get "ip_address"
  body = JSON.parse response.body
  body["ip_addresses"]["ip_address"]
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/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.

Returns:

  • HTTParty response object.



226
227
228
229
230
231
232
 
# File 'lib/upcloud_api.rb', line 226

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.

Examples:

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.

Returns:

  • HTTParty response object.



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

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

#modify_tag(tag) ⇒ Object

Note:

Attributes are same as with create_tag().

Modifies existing tag.

Calls PUT /1.2/tag/tag.

Returns:

  • Tag parameters as Hash or HTTParty response object in case of error.



844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
 
# File 'lib/upcloud_api.rb', line 844

def modify_tag tag
  data = {
    "tag" => params
  }
  temp = data["servers"]
  data["servers"] = { "server" => temp }

  json = JSON.generate data

  response = put "tag/#{tag}", json
  return response unless response.code == 200

  body = JSON.parse response.body
  body["tag"]
end

#new_ip_address_to_server(server_uuid, family: "IPv4") ⇒ Object

Note:

To add a new IP address, the server must be stopped.

Note:

Only public IP addresses can be added. There is always exactly one private IP address per server.

Note:

There is a maximum of five public IP addresses per server.

Adds new IP address to given server.

Calls POST /1.2/ip_address.

Parameters:

  • server_uuid (String) —

    UUID of the server

  • family ("IPv4", "IPv6") (defaults to: "IPv4") —

    Type of the IP address.

Returns:

  • HTTParty response object.

See Also:



955
956
957
958
959
960
961
962
963
964
965
 
# File 'lib/upcloud_api.rb', line 955

def new_ip_address_to_server server_uuid, family: "IPv4"
  data = {
    "ip_address" => {
      "family" => family,
      "server" => server_uuid
    }
  }
  json = JSON.generate data

  post "ip_address", json
end

#plans ⇒ Object

Lists available predefined plans that can be used to create a server.

Examples:

Return values

[
 {
   "core_number" : 1,
   "memory_amount" : 1024,
   "name" : "1xCPU-1GB",
   "public_traffic_out" : 2048,
   "storage_size" : 30,
   "storage_tier" : "maxiops"
 }
]

Returns:

  • Array of plan hashes



664
665
666
667
668
669
 
# File 'lib/upcloud_api.rb', line 664

def plans
  response = get "plan"

  data = JSON.parse response.body
  data["plans"]["plan"]
end

#prices ⇒ Array

Lists prices for specific components that can be tied to a server.

Returns:

  • (Array) —

    list of prices per component

See Also:



1001
1002
1003
1004
1005
 
# File 'lib/upcloud_api.rb', line 1001

def prices
  response = get "price"
  body = JSON.parse response.body
  body["prices"]["zone"]
end

#remove_firewall_rule(server_uuid, position) ⇒ Object

Removes a firewall rule at position position.

Calls DELETE /1.2/server/server_uuid/firewall_rule/position.

A position of a rule can be seen with firewall_rules().

Parameters:

  • server_uuid (String) —

    UUID of server

  • position (Integer) —

    position of the rule in rule list that will be removed

Returns:

  • HTTParty response object.



757
758
759
760
761
 
# File 'lib/upcloud_api.rb', line 757

def remove_firewall_rule server_uuid, position
  response = delete "server/#{server_uuid}/firewall_rule/#{position}"

  response
end

#remove_ip_address(ip_address) ⇒ Object

TODO:

I’m fairly sure the API call is wrong, but this is what their documentation says. Please tell me if you test if this one works.

Removes IP address (from a server).

Calls DELETE /1.2/ip_address.

Returns:

  • HTTParty response object.



992
993
994
 
# File 'lib/upcloud_api.rb', line 992

def remove_ip_address ip_address
  delete "#{ip_address}"
end

#remove_tag_from_server(server_uuid, tags) ⇒ Object

Removes one or more tags to a server.

Calls POST /1.2/server/uuid/untag/tags.

Parameters:

  • server_uuid (String) —

    UUID of the server

  • tags (Array, String) —

    Tags that will be removed from the server

Returns:

  • HTTParty response object.



891
892
893
894
895
 
# File 'lib/upcloud_api.rb', line 891

def remove_tag_from_server server_uuid, tags
  tag = (tags.respond_to? :join && tags.join(",") || tags)

  post "server/#{server_uuid}/untag/#{tag}"
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.

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 did not close cleanly. Only affects :soft type.

  • timeout_action (defaults to: :ignore) —

    What will happen when timeout happens. :destroy hard stops the server and :ignore stops the operation if timeout happens. Default is :ignore.

Returns:

  • HTTParty response object.



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/upcloud_api.rb', line 327

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

Returns:

  • HTTParty response object.



603
604
605
606
607
 
# File 'lib/upcloud_api.rb', line 603

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.

Examples:

Return hash

{
  "core_number": "1",
  "memory_amount": "512"
}

Returns:

  • array of server size hashes



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

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.

Examples:

Return values

{
 "boot_order"         => "cdrom,disk",
 "core_number"        => "3",
 "firewall"           => "off",
 "hostname"           => "dummy",
 "ip_addresses"       => {
   "ip_address" => [
     {
       "access" => "private",
       "address"            => "192.168.0.1",
      "family"             => "IPv4"
     },
     {
       "access"            => "public",
       "address"            => "::1",
       "family"             => "IPv6"
     },
     {
       "access"            => "public",
       "address"            => "198.51.100.1",
       "family"             => "IPv4"
     }
   ]
 },
 "license"            => 0,
 "memory_amount"      => "3072",
 "nic_model"          => "virtio",
 "plan"               => "custom",
 "state"              => "stopped",
 "storage_devices"    => {
   "storage_device" => [
     {
       "address" => "virtio:1",
       "storage"            => "storage_uuid",
       "storage_size"       => 10,
       "storage_title"      => "Disk name",
       "type"               => "disk"
     }
   ]
 },
 "tags"               => {"tag" => []},
 "timezone"           => "UTC",
 "title"              => "Server name",
 "uuid"               => "uuid",
 "video_model"        => "cirrus",
 "vnc"                => "off",
 "vnc_password"       => "1234",
 "zone"               => "de-fra1"
}

Parameters:

  • uuid —

    from UpcloudApi#servers

Returns:

  • hash of server details or nil



133
134
135
136
137
138
139
140
 
# File 'lib/upcloud_api.rb', line 133

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

  return nil if data["server"].nil?

  data["server"]
end

#servers ⇒ Object

Lists servers associated with the account.

Calls GET /1.2/server.

Examples:

Return values

- zone
- core_number
- title
- hostname
- memory_amount
- uuid
- state

Returns:

  • array of servers with following values or empty array if no servers found.



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

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/server_uuid/start.

Parameters:

  • server_uuid —

    UUID of the server.

Returns:

  • HTTParty response object.



254
255
256
257
258
 
# File 'lib/upcloud_api.rb', line 254

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.

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 did not close cleanly. Only affects :soft type.

  • asynchronous (defaults to: false) —

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

Returns:

  • HTTParty response object if server was removed successfully or request is asynchronous and nil otherwise

Raises:

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



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/upcloud_api.rb', line 282

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.nil?
      return response if details["state"] == "stopped"
    end
  end

  nil
end

#storage_details(storage_uuid) ⇒ Object

Shows detailed information of single storage.

Calls GET /1.2/storage/uuid.

Examples:

Return values

{
  "access"  => "public",
  "license" => 0,
  "servers" => {
      "server"=> []
    },
  "size"    => 1,
  "state"   => "online",
  "title"   => "Windows Server 2003 R2 Standard (CD 1)",
  "type"    => "cdrom",
  "uuid"    => "01000000-0000-4000-8000-000010010101"
}

Parameters:

  • storage_uuid —

    UUID of the storage.

Returns:

  • hash of following storage details or nil



385
386
387
388
389
390
391
392
 
# File 'lib/upcloud_api.rb', line 385

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

  return nil if data["storage"].nil?

  data["storage"]
end

#storages(type: nil) ⇒ Object

Lists all storages or storages matching to given type.

Calls GET /1.2/storage or /1.2/storage/type.

Examples:

Available types

- public
- private
- normal
- backup
- cdrom
- template
- favorite

Parameters:

  • type (defaults to: nil) —

    Type of the storages to be returned on nil.

Returns:

  • array of storages, inside “storage” key in the API or empty array if none found.



359
360
361
362
363
 
# File 'lib/upcloud_api.rb', line 359

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

#tags ⇒ Object

Lists all tags with UUIDs of servers they are attached to.

Calls GET /1.2/tags.

Examples:

Return values

[
 {
   "description": "Development servers",
   "name": "DEV",
   "servers": {
     "server": [
       "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
     ]
   }
 }
]

Returns:

  • Array of tag hashes



780
781
782
783
784
785
 
# File 'lib/upcloud_api.rb', line 780

def tags
  response = get "tag"

  data = JSON.parse response.body
  data["tags"]["tag"]
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

Returns:

  • HTTParty response object.



503
504
505
506
507
508
509
510
511
512
513
514
515
 
# File 'lib/upcloud_api.rb', line 503

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

  json = JSON.generate data

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

  response
end

#zones ⇒ Array

Lists available zones and their details.

Returns:

  • (Array) —

    list of zones

See Also:



1012
1013
1014
1015
1016
 
# File 'lib/upcloud_api.rb', line 1012

def zones
  response = get "zone"
  body = JSON.parse response.body
  body["zones"]["zone"]
end