Class: SoftLayer::VirtualServer

Inherits:
Server show all
Includes:
DynamicAttribute
Defined in:
lib/softlayer/VirtualServer.rb

Overview

Instance of this class represent servers that are virtual machines in the SoftLayer environment.

This class roughly corresponds to the entity SoftLayer_Virtual_Guest in the API.

Instance Attribute Summary

Attributes inherited from ModelBase

#softlayer_client

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DynamicAttribute

included

Methods inherited from Server

#change_port_speed, #datacenter, #domain, #firewall_port_speed, #fullyQualifiedDomainName, #hostname, #initialize, #notes, #notes=, #primary_private_ip, #primary_public_ip, #reboot!, #reload_os!, #set_domain!, #set_hostname!, #softlayer_properties, #software, #to_s, #user_metadata=

Methods inherited from ModelBase

#[], #has_sl_property?, #initialize, #refresh_details, sl_attr, #to_ary

Constructor Details

This class inherits a constructor from SoftLayer::Server

Class Method Details

.default_object_mask ⇒ Object

Returns the default object mask used when fetching servers from the API



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

def self.default_object_mask
  sub_mask = {
    "mask(SoftLayer_Virtual_Guest)" => [
      'createDate',
      'modifyDate',
      'provisionDate',
      'dedicatedAccountHostOnlyFlag',
      'lastKnownPowerState.name',
      'powerState',
      'status',
      'maxCpu',
      'maxMemory',
      'activeTransaction[id, transactionStatus[friendlyName,name]]',
      'networkComponents[id, status, speed, maxSpeed, name, macAddress, primaryIpAddress, port, primarySubnet]',
      'lastOperatingSystemReload.id',
      'blockDevices',
      'blockDeviceTemplateGroup[id, name, globalIdentifier]'
    ]
  }

  super.merge(sub_mask)
end

.find_servers(options_hash = {}) ⇒ Object

Retrieve a list of virtual servers from the account.

The options parameter should contain:

:client - The client used to connect to the API

If no client is given, then the routine will try to use Client.default_client If no client can be found the routine will raise an error.

You may filter the list returned by adding options:

  • :hourly (boolean) - Include servers billed hourly in the list

  • :monthly (boolean) - Include servers billed monthly in the list

  • :tags (array) - an array of strings representing tags to search for on the instances

  • :cpus (int) - return virtual servers with the given number of (virtual) CPUs

  • :memory (int) - return servers with at least the given amount of memory (in MB. e.g. 4096 = 4GB)

  • :hostname (string) - return servers whose hostnames match the query string given (see ObjectFilter::query_to_filter_operation)

  • :domain (string) - filter servers to those whose domain matches the query string given (see ObjectFilter::query_to_filter_operation)

  • :local_disk (boolean) - include servers that do, or do not, have local disk storage

  • :datacenter (string) - find servers whose short data center name (e.g. dal05, sjc01) matches the query string given (see ObjectFilter::query_to_filter_operation)

  • :nic_speed (int) - include servers with the given nic speed (in Mbps, usually 10, 100, or 1000)

  • :public_ip (string) - return servers whose public IP address matches the query string given (see ObjectFilter::query_to_filter_operation)

  • :private_ip (string) - same as :public_ip, but for private IP addresses

Additionally you may provide options related to the request itself:

  • :object_mask (string) - A object mask of properties, in addition to the default properties, that you wish to retrieve for the servers

  • :result_limit (hash with :limit, and :offset keys) - Limit the scope of results returned.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/softlayer/VirtualServer.rb', line 207

def self.find_servers(options_hash = {})
  softlayer_client = options_hash[:client] || Client.default_client
  raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client

  if(options_hash.has_key? :object_filter)
    object_filter = options_hash[:object_filter]
    raise "Expected an instance of SoftLayer::ObjectFilter" unless object_filter.kind_of?(SoftLayer::ObjectFilter)
  else
    object_filter = ObjectFilter.new()
  end

  option_to_filter_path = {
    :cores => "virtualGuests.maxCpu",
    :memory => "virtualGuests.maxMemory",
    :hostname => "virtualGuests.hostname",
    :domain => "virtualGuests.domain",
    :local_disk => "virtualGuests.localDiskFlag",
    :datacenter => "virtualGuests.datacenter.name",
    :nic_speed => "virtualGuests.networkComponents.maxSpeed",
    :public_ip => "virtualGuests.primaryIpAddress",
    :private_ip => "virtualGuests.primaryBackendIpAddress"
  }

  if options_hash.has_key?(:local_disk) then
    options_hash[:local_disk] = options_hash[:local_disk] ? 1 : 0
  end

  # For each of the options in the option_to_filter_path map, if the options hash includes
  # that particular option, add a clause to the object filter that filters for the matching
  # value
  option_to_filter_path.each do |option, filter_path|
    object_filter.modify { |filter| filter.accept(filter_path).when_it is(options_hash[option])} if options_hash[option]
  end

  # Tags get a much more complex object filter operation so we handle them separately
  if options_hash.has_key?(:tags)
    object_filter.set_criteria_for_key_path("virtualGuests.tagReferences.tag.name", {
      'operation' => 'in',
      'options' => [{
        'name' => 'data',
        'value' => options_hash[:tags].collect{ |tag_value| tag_value.to_s }
        }]
      } );
  end

  required_properties_mask = 'mask.id'

   = softlayer_client[:Account]
   = .object_filter(object_filter) unless object_filter.empty?
   = .object_mask(default_object_mask.to_sl_object_mask)

  if options_hash.has_key? :object_mask
     = .object_mask(options_hash[:object_mask])
  end

  if options_hash.has_key?(:result_limit)
    offset = options[:result_limit][:offset]
    limit = options[:result_limit][:limit]

     = .result_limit(offset, limit)
  end

  case
  when options_hash[:hourly] && options_hash[:monthly]
    virtual_server_data = .getVirtualGuests()
  when options_hash[:hourly]
    virtual_server_data = .getHourlyVirtualGuests()
  when options_hash[:monthly]
    virtual_server_data = .getMonthlyVirtualGuests()
  else
    virtual_server_data = .getVirtualGuests()
  end

  virtual_server_data.collect { |server_data| VirtualServer.new(softlayer_client, server_data) }
end

.server_with_id(server_id, options = {}) ⇒ Object

Retrive the virtual server with the given server ID from the API

The options parameter should contain:

:client - The client used to connect to the API

If no client is given, then the routine will try to use Client.default_client If no client can be found the routine will raise an error.

The options may include the following keys

  • :object_mask (string) - A object mask of properties, in addition to the default properties, that you wish to retrieve for the server



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/softlayer/VirtualServer.rb', line 163

def self.server_with_id(server_id, options = {})
  softlayer_client = options[:client] || Client.default_client
  raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client

  vg_service = softlayer_client[:Virtual_Guest]
  vg_service = vg_service.object_mask(default_object_mask.to_sl_object_mask)

  if options.has_key?(:object_mask)
    vg_service = vg_service.object_mask(options[:object_mask])
  end

  server_data = vg_service.object_with_id(server_id).getObject()

  return VirtualServer.new(softlayer_client, server_data)
end

Instance Method Details

#activeTransaction ⇒ Object

:attr_reader: The active transaction (if any) for this virtual server. Transactions are used to make configuration changes to the server and only one transaction can be active at a time.



37
 
# File 'lib/softlayer/VirtualServer.rb', line 37

sl_attr :activeTransaction

#blockDevices ⇒ Object

:attr_reader: Storage devices attached to the server. Storage may be local to the host running the Virtual Server, or it may be located on the SAN



44
 
# File 'lib/softlayer/VirtualServer.rb', line 44

sl_attr :blockDevices

#cancel! ⇒ Object

IMMEDIATELY cancel this virtual server



71
72
73
 
# File 'lib/softlayer/VirtualServer.rb', line 71

def cancel!
  self.service.deleteObject()
end

#capture_image(image_name, include_attached_storage = false, image_notes = '') ⇒ Object

Capture a disk image of this virtual server for use with other servers.

image_name will become the name of the image in the portal.

If include_attached_storage is true, the images of attached storage will be included as well.

The image_notes should be a string and will be added to the image as notes.

The routine returns the instance of SoftLayer::ImageTemplate that is created. That image template will probably not be available immediately, however. You may use the wait_until_ready routine of SoftLayer::ImageTemplate to wait on it.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/softlayer/VirtualServer.rb', line 90

def capture_image(image_name, include_attached_storage = false, image_notes = '')
  image_notes = '' if !image_notes
  image_name = 'Captured Image' if !image_name

  disk_filter = lambda { |disk| disk['device'] == '0' }
  disk_filter = lambda { |disk| disk['device'] != '1' } if include_attached_storage

  disks = self.blockDevices.select(&disk_filter)

  self.service.createArchiveTransaction(image_name, disks, image_notes) if disks && !disks.empty?

  image_templates = SoftLayer::ImageTemplate.find_private_templates(:name => image_name)
  image_templates[0] if !image_templates.empty?
end

#cores ⇒ Object

:attr_reader: A count of the nubmer of virtual processing cores allocated to the server.



22
 
# File 'lib/softlayer/VirtualServer.rb', line 22

sl_attr :cores, 'maxCpu'

#lastOperatingSystemReload ⇒ Object

:attr_reader: The last operating system reload transaction that was run for this server. #wait_until_ready compares the ID of this transaction to the ID of the active transaction to determine if an OS reload is in progress.



52
 
# File 'lib/softlayer/VirtualServer.rb', line 52

sl_attr :lastOperatingSystemReload

#provisionDate ⇒ Object

:attr_reader: The date the Virtual Server was provisioned. This attribute can be nil if the SoftLayer system has not yet finished provisioning the server (consequently this attribute is used by the #wait_until_ready method to determine when a server has been provisioned)



30
 
# File 'lib/softlayer/VirtualServer.rb', line 30

sl_attr :provisionDate

#service ⇒ Object

Returns the SoftLayer Service that represents calls to this object For VirtualServers the service is SoftLayer_Virtual_Guest and addressing this object is done by id.



312
313
314
 
# File 'lib/softlayer/VirtualServer.rb', line 312

def service
  return softlayer_client[:Virtual_Guest].object_with_id(self.id)
end

#upgrade_options ⇒ Object

A virtual server can find out about items that are available for upgrades.



58
59
60
61
62
63
64
65
66
 
# File 'lib/softlayer/VirtualServer.rb', line 58

sl_dynamic_attr :upgrade_options do |resource|
  resource.should_update? do
    @upgrade_options == nil
  end

  resource.to_update do
    self.service.object_mask("mask[id,categories.categoryCode,item[id,capacity,units,attributes,prices]]").getUpgradeItemPrices(true)
  end
end

#wait_until_ready(max_trials, wait_for_transactions = false, seconds_between_tries = 2) ⇒ Object

Repeatedly polls the API to find out if this server is ‘ready’.

The server is ready when it is provisioned and any operating system reloads have completed.

If wait_for_transactions is true, then the routine will poll until all transactions (not just an OS Reload) have completed on the server.

max_trials is the maximum number of times the routine will poll the API seconds_between_tries is the polling interval (in seconds)

The routine returns true if the server was found to be ready. If max_trials is exceeded and the server is still not ready, the routine returns false

If a block is passed to this routine it will be called on each trial with a boolean argument representing whether or not the server is ready

Calling this routine will (in essence) block the thread on which the request is made.



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/softlayer/VirtualServer.rb', line 124

def wait_until_ready(max_trials, wait_for_transactions = false, seconds_between_tries = 2)
  # pessimistically assume the server is not ready
  num_trials = 0
  begin
    self.refresh_details()

    has_os_reload = has_sl_property? :lastOperatingSystemReload
    has_active_transaction = has_sl_property? :activeTransaction

    reloading_os = has_active_transaction && has_os_reload && (self.lastOperatingSystemReload['id'] == self.activeTransaction['id'])
    provisioned = has_sl_property?(:provisionDate) && ! self['provisionDate'].empty?

    # a server is ready when it is provisioned, not reloading the OS
    # (and if wait_for_transactions is true, when there are no active transactions).
    ready = provisioned && !reloading_os && (!wait_for_transactions || !has_active_transaction)

    num_trials = num_trials + 1

    yield ready if block_given?

    sleep(seconds_between_tries) if !ready && (num_trials <= max_trials)
  end until ready || (num_trials >= max_trials)

  ready
end