Class: OpenNebula::VirtualMachine

Inherits:
PoolElement show all
Defined in:
lib/opennebula/virtual_machine.rb

Constant Summary collapse

VM_METHODS =

Constants and Class Methods

{
    :info       => "vm.info",
    :allocate   => "vm.allocate",
    :action     => "vm.action",
    :migrate    => "vm.migrate",
    :deploy     => "vm.deploy",
    :savedisk   => "vm.savedisk",
    :chown      => "vm.chown",
    :chmod      => "vm.chmod",
    :monitoring => "vm.monitoring",
    :attach     => "vm.attach",
    :detach     => "vm.detach",
    :rename     => "vm.rename",
    :update     => "vm.update",
    :resize     => "vm.resize",
    :snapshotcreate => "vm.snapshotcreate",
    :snapshotrevert => "vm.snapshotrevert",
    :snapshotdelete => "vm.snapshotdelete",
    :attachnic  => "vm.attachnic",
    :detachnic  => "vm.detachnic",
    :resize     => "vm.resize",
    :recover    => "vm.recover"
}
VM_STATE = 
%w{INIT PENDING HOLD ACTIVE STOPPED SUSPENDED DONE FAILED
POWEROFF UNDEPLOYED}
LCM_STATE = 
%w{LCM_INIT PROLOG BOOT RUNNING MIGRATE SAVE_STOP SAVE_SUSPEND
SAVE_MIGRATE PROLOG_MIGRATE PROLOG_RESUME EPILOG_STOP EPILOG
SHUTDOWN CANCEL FAILURE CLEANUP_RESUBMIT UNKNOWN HOTPLUG SHUTDOWN_POWEROFF
BOOT_UNKNOWN BOOT_POWEROFF BOOT_SUSPENDED BOOT_STOPPED CLEANUP_DELETE
HOTPLUG_SNAPSHOT HOTPLUG_NIC HOTPLUG_SAVEAS HOTPLUG_SAVEAS_POWEROFF
HOTPLUG_SAVEAS_SUSPENDED SHUTDOWN_UNDEPLOY EPILOG_UNDEPLOY
PROLOG_UNDEPLOY BOOT_UNDEPLOY}
SHORT_VM_STATES = 
{
    "INIT"      => "init",
    "PENDING"   => "pend",
    "HOLD"      => "hold",
    "ACTIVE"    => "actv",
    "STOPPED"   => "stop",
    "SUSPENDED" => "susp",
    "DONE"      => "done",
    "FAILED"    => "fail",
    "POWEROFF"  => "poff",
    "UNDEPLOYED"=> "unde"
}
SHORT_LCM_STATES = 
{
    "PROLOG"            => "prol",
    "BOOT"              => "boot",
    "RUNNING"           => "runn",
    "MIGRATE"           => "migr",
    "SAVE_STOP"         => "save",
    "SAVE_SUSPEND"      => "save",
    "SAVE_MIGRATE"      => "save",
    "PROLOG_MIGRATE"    => "migr",
    "PROLOG_RESUME"     => "prol",
    "EPILOG_STOP"       => "epil",
    "EPILOG"            => "epil",
    "SHUTDOWN"          => "shut",
    "CANCEL"            => "shut",
    "FAILURE"           => "fail",
    "CLEANUP_RESUBMIT"  => "clea",
    "UNKNOWN"           => "unkn",
    "HOTPLUG"           => "hotp",
    "SHUTDOWN_POWEROFF" => "shut",
    "BOOT_UNKNOWN"      => "boot",
    "BOOT_POWEROFF"     => "boot",
    "BOOT_SUSPENDED"    => "boot",
    "BOOT_STOPPED"      => "boot",
    "CLEANUP_DELETE"    => "clea",
    "HOTPLUG_SNAPSHOT"  => "snap",
    "HOTPLUG_NIC"       => "hotp",
    "HOTPLUG_SAVEAS"           => "hotp",
    "HOTPLUG_SAVEAS_POWEROFF"  => "hotp",
    "HOTPLUG_SAVEAS_SUSPENDED" => "hotp",
    "SHUTDOWN_UNDEPLOY" => "shut",
    "EPILOG_UNDEPLOY"   => "epil",
    "PROLOG_UNDEPLOY"   => "prol",
    "BOOT_UNDEPLOY"     => "boot"
}
MIGRATE_REASON = 
%w{NONE ERROR USER}
SHORT_MIGRATE_REASON = 
{
    "NONE"          => "none",
    "ERROR"         => "erro",
    "USER"          => "user"
}
HISTORY_ACTION = 
%w{none migrate live-migrate shutdown shutdown-hard
undeploy undeploy-hard hold release stop suspend resume boot delete
delete-recreate reboot reboot-hard resched unresched poweroff
poweroff-hard}

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from PoolElement

#id, #name, new_with_id, #to_str

Methods inherited from XMLElement

#[], #add_element, #attr, #delete_element, #each, #each_xpath, #element_xml, #has_elements?, #initialize_xml, #name, #retrieve_elements, #template_like_str, #template_str, #template_xml, #text, #to_hash, #to_xml

Constructor Details

#initialize(xml, client) ⇒ VirtualMachine

Class constructor



151
152
153
 
# File 'lib/opennebula/virtual_machine.rb', line 151

def initialize(xml, client)
    super(xml,client)
end

Class Method Details

.build_xml(pe_id = nil) ⇒ Object

Creates a VirtualMachine description with just its identifier this method should be used to create plain VirtualMachine objects. id the id of the vm

Example:

vnet = VirtualMachine.new(VirtualMachine.build_xml(3),rpc_client)



129
130
131
132
133
134
135
136
137
 
# File 'lib/opennebula/virtual_machine.rb', line 129

def VirtualMachine.build_xml(pe_id=nil)
    if pe_id
        vm_xml = "<VM><ID>#{pe_id}</ID></VM>"
    else
        vm_xml = "<VM></VM>"
    end

    XMLElement.build_xml(vm_xml, 'VM')
end

.get_history_action(action) ⇒ Object 



146
147
148
 
# File 'lib/opennebula/virtual_machine.rb', line 146

def VirtualMachine.get_history_action(action)
    return HISTORY_ACTION[action.to_i]
end

.get_reason(reason) ⇒ Object 



139
140
141
142
143
144
 
# File 'lib/opennebula/virtual_machine.rb', line 139

def VirtualMachine.get_reason(reason)
    reason=MIGRATE_REASON[reason.to_i]
    reason_str=SHORT_MIGRATE_REASON[reason]

    reason_str
end

Instance Method Details

#allocate(description, hold = false) ⇒ nil, OpenNebula::Error

Allocates a new VirtualMachine in OpenNebula

Parameters:

  • description (String) —

    A string containing the template of the VirtualMachine.

  • hold (true, false) (defaults to: false) —

    false to create the VM in pending state, true to create it on hold

Returns:



175
176
177
 
# File 'lib/opennebula/virtual_machine.rb', line 175

def allocate(description, hold=false)
    super(VM_METHODS[:allocate], description, hold)
end

#boot ⇒ Object Also known as: restart

Forces a re-deployment of a VM in UNKNOWN or BOOT state



340
341
342
 
# File 'lib/opennebula/virtual_machine.rb', line 340

def boot
    action('boot')
end

#cancel ⇒ Object

Deprecated.

use #shutdown



256
257
258
 
# File 'lib/opennebula/virtual_machine.rb', line 256

def cancel
    shutdown(true)
end

#chmod(owner_u, owner_m, owner_a, group_u, group_m, group_a, other_u, other_m, other_a) ⇒ nil, OpenNebula::Error

Changes the permissions. Each [Integer] argument must be 1 to allow, 0 deny, -1 do not change

Returns:



455
456
457
458
459
 
# File 'lib/opennebula/virtual_machine.rb', line 455

def chmod(owner_u, owner_m, owner_a, group_u, group_m, group_a, other_u,
        other_m, other_a)
    super(VM_METHODS[:chmod], owner_u, owner_m, owner_a, group_u,
        group_m, group_a, other_u, other_m, other_a)
end

#chmod_octet(octet) ⇒ nil, OpenNebula::Error

Changes the permissions.

Parameters:

  • octet (String) —

    Permissions octed , e.g. 640

Returns:



446
447
448
 
# File 'lib/opennebula/virtual_machine.rb', line 446

def chmod_octet(octet)
    super(VM_METHODS[:chmod], octet)
end

#chown(uid, gid) ⇒ Object

Changes the owner/group

uid

Integer the new owner id. Set to -1 to leave the current one

gid

Integer the new group id. Set to -1 to leave the current one

return

nil in case of success or an Error object



437
438
439
 
# File 'lib/opennebula/virtual_machine.rb', line 437

def chown(uid, gid)
    super(VM_METHODS[:chown], uid, gid)
end

#delete(recreate = false) ⇒ Object

Deletes a VM from the pool



326
327
328
329
330
331
332
 
# File 'lib/opennebula/virtual_machine.rb', line 326

def delete(recreate=false)
    if recreate
        action('delete-recreate')
    else
        action('delete')
    end
end

#deploy(host_id, enforce = false, ds_id = -1)) ⇒ nil, OpenNebula::Error

Initiates the instance of the VM on the target host.

Parameters:

  • host_id (Interger) —

    The host id (hid) of the target host where the VM will be instantiated.

  • enforce (true|false) (defaults to: false) —

    If it is set to true, the host capacity will be checked, and the deployment will fail if the host is overcommited. Defaults to false

  • ds_id (Integer) (defaults to: -1)) —

    The System Datastore where to deploy the VM. To use the default, set it to -1

Returns:



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

def deploy(host_id, enforce=false, ds_id=-1)
    enforce ||= false
    ds_id ||= -1
    return call(VM_METHODS[:deploy], @pe_id, host_id.to_i, enforce, ds_id.to_i)
end

#disk_attach(disk_template) ⇒ nil, OpenNebula::Error Also known as: attachdisk

Attaches a disk to a running VM

Parameters:

  • disk_template (String) —

    Template containing a DISK element

Returns:



290
291
292
 
# File 'lib/opennebula/virtual_machine.rb', line 290

def disk_attach(disk_template)
    return call(VM_METHODS[:attach], @pe_id, disk_template)
end

#disk_detach(disk_id) ⇒ nil, OpenNebula::Error Also known as: detachdisk

Detaches a disk from a running VM

Parameters:

  • disk_id (Integer) —

    Id of the disk to be detached

Returns:



301
302
303
 
# File 'lib/opennebula/virtual_machine.rb', line 301

def disk_detach(disk_id)
    return call(VM_METHODS[:detach], @pe_id, disk_id)
end

#disk_snapshot(disk_id, image_name, image_type = "", hot = false, do_template = false) ⇒ Integer, OpenNebula::Error

Set the specified vm’s disk to be saved in a new image when the VirtualMachine shutdowns

template and replace the disk with the saved image

Parameters:

  • disk_id (Integer) —

    ID of the disk to be saved

  • image_name (String) —

    Name for the new image where the disk will be saved

  • image_type (String) (defaults to: "") —

    Type of the new image. Set to empty string to use the default type

  • hot (true|false) (defaults to: false) —

    True to save the disk immediately, false will perform the operation when the VM shuts down

  • do_template (true|false) (defaults to: false) —

    True to clone also the VM originating

Returns:

  • (Integer, OpenNebula::Error) —

    the new Image ID in case of success, error otherwise



399
400
401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/opennebula/virtual_machine.rb', line 399

def disk_snapshot(disk_id, image_name, image_type="", hot=false,
    do_template=false)
    return Error.new('ID not defined') if !@pe_id

    rc = @client.call(VM_METHODS[:savedisk],
                      @pe_id,
                      disk_id,
                      image_name,
                      image_type,
                      hot,
                      do_template)
    return rc
end

#finalize(recreate = false) ⇒ Object

Deprecated.

use #delete instead



335
336
337
 
# File 'lib/opennebula/virtual_machine.rb', line 335

def finalize(recreate=false)
    delete(recreate)
end

#gid ⇒ Object

Returns the group identifier

return

Integer the element’s group ID



586
587
588
 
# File 'lib/opennebula/virtual_machine.rb', line 586

def gid
    self['GID'].to_i
end

#hold ⇒ Object

Sets a VM to hold state, scheduler will not deploy it



261
262
263
 
# File 'lib/opennebula/virtual_machine.rb', line 261

def hold
    action('hold')
end

#info ⇒ Object Also known as: info!

Retrieves the information of the given VirtualMachine.



160
161
162
 
# File 'lib/opennebula/virtual_machine.rb', line 160

def info()
    super(VM_METHODS[:info], 'VM')
end

#lcm_state ⇒ Object

Returns the LCM state of the VirtualMachine (numeric value)



564
565
566
 
# File 'lib/opennebula/virtual_machine.rb', line 564

def lcm_state
    self['LCM_STATE'].to_i
end

#lcm_state_str ⇒ Object

Returns the LCM state of the VirtualMachine (string value)



569
570
571
 
# File 'lib/opennebula/virtual_machine.rb', line 569

def lcm_state_str
    LCM_STATE[lcm_state]
end

#live_migrate(host_id, enforce = false) ⇒ Object

Deprecated.

use #migrate instead



380
381
382
 
# File 'lib/opennebula/virtual_machine.rb', line 380

def live_migrate(host_id, enforce=false)
    migrate(host_id, true, enforce)
end

#migrate(host_id, live = false, enforce = false) ⇒ nil, OpenNebula::Error

Moves a running VM to the specified host. With live=true the migration is done withdout downtime.

Parameters:

  • host_id (Interger) —

    The host id (hid) of the target host where the VM will be migrated.

  • live (true|false) (defaults to: false) —

    If true the migration is done without downtime. Defaults to false

  • enforce (true|false) (defaults to: false) —

    If it is set to true, the host capacity will be checked, and the deployment will fail if the host is overcommited. Defaults to false

Returns:



374
375
376
377
 
# File 'lib/opennebula/virtual_machine.rb', line 374

def migrate(host_id, live=false, enforce=false)
    call(VM_METHODS[:migrate], @pe_id, host_id.to_i, live==true,
        enforce)
end

#monitoring(xpath_expressions) ⇒ Hash<String, Array<Array<int>>>, OpenNebula::Error

Retrieves this VM’s monitoring data from OpenNebula

Examples:

vm.monitoring( ['CPU', 'NET_TX', 'TEMPLATE/CUSTOM_PROBE'] )

{ "NET_TX" =>
    [["1337264510", "210"],
     ["1337264553", "220"],
     ["1337264584", "230"]],
  "TEMPLATE/CUSTOM_PROBE" =>
    [],
  "CPU" =>
    [["1337264510", "0"],
     ["1337264553", "0"],
     ["1337264584", "0"]]
}

Parameters:

  • xpath_expressions (Array<String>) —

    Elements to retrieve.

Returns:

  • (Hash<String, Array<Array<int>>>, OpenNebula::Error) —

    Hash with the requested xpath expressions, and an Array of ‘timestamp, value’.



482
483
484
485
 
# File 'lib/opennebula/virtual_machine.rb', line 482

def monitoring(xpath_expressions)
    return super(VM_METHODS[:monitoring], 'VM',
        'LAST_POLL', xpath_expressions)
end

#monitoring_xml ⇒ String

Retrieves this VM’s monitoring data from OpenNebula, in XML

Returns:

  • (String) —

    VM monitoring data, in XML



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

def monitoring_xml()
    return Error.new('ID not defined') if !@pe_id

    return @client.call(VM_METHODS[:monitoring], @pe_id)
end

#nic_attach(nic_template) ⇒ nil, OpenNebula::Error

Attaches a NIC to a running VM

Parameters:

  • nic_template (String) —

    Template containing a NIC element

Returns:



312
313
314
 
# File 'lib/opennebula/virtual_machine.rb', line 312

def nic_attach(nic_template)
    return call(VM_METHODS[:attachnic], @pe_id, nic_template)
end

#nic_detach(nic_id) ⇒ nil, OpenNebula::Error

Detaches a NIC from a running VM

Parameters:

  • nic_id (Integer) —

    Id of the NIC to be detached

Returns:



321
322
323
 
# File 'lib/opennebula/virtual_machine.rb', line 321

def nic_detach(nic_id)
    return call(VM_METHODS[:detachnic], @pe_id, nic_id)
end

#poweroff(hard = false) ⇒ Object

Powers off a running VM



241
242
243
 
# File 'lib/opennebula/virtual_machine.rb', line 241

def poweroff(hard=false)
    action(hard ? 'poweroff-hard' : 'poweroff')
end

#reboot(hard = false) ⇒ Object

Reboots an already deployed VM



246
247
248
 
# File 'lib/opennebula/virtual_machine.rb', line 246

def reboot(hard=false)
    action(hard ? 'reboot-hard' : 'reboot')
end

#recover(result) ⇒ nil, OpenNebula::Error

Recovers an ACTIVE VM

Parameters:

  • result (Boolean) —

    Recover with success (true) or failure (false)

  • result (info) —

    Additional information needed to recover the VM

Returns:



545
546
547
 
# File 'lib/opennebula/virtual_machine.rb', line 545

def recover(result)
    return call(VM_METHODS[:recover], @pe_id, result)
end

#release ⇒ Object

Releases a VM from hold state



266
267
268
 
# File 'lib/opennebula/virtual_machine.rb', line 266

def release
    action('release')
end

#rename(name) ⇒ nil, OpenNebula::Error

Renames this VM

Parameters:

  • name (String) —

    New name for the VM.

Returns:



502
503
504
 
# File 'lib/opennebula/virtual_machine.rb', line 502

def rename(name)
    return call(VM_METHODS[:rename], @pe_id, name)
end

#resched ⇒ Object

Sets the re-scheduling flag for the VM



352
353
354
 
# File 'lib/opennebula/virtual_machine.rb', line 352

def resched
    action('resched')
end

#reset ⇒ Object

Deprecated.

use #reboot



251
252
253
 
# File 'lib/opennebula/virtual_machine.rb', line 251

def reset
    reboot(true)
end

#resize(capacity_template, enforce) ⇒ nil, OpenNebula::Error

Resize the VM

Parameters:

  • capacity_template (String) —

    Template containing the new capacity elements CPU, VCPU, MEMORY. If one of them is not present, or its value is 0, it will not be resized

  • enforce (true|false) —

    If it is set to true, the host capacity will be checked. This will only affect oneadmin requests, regular users resize requests will always be enforced

Returns:



429
430
431
 
# File 'lib/opennebula/virtual_machine.rb', line 429

def resize(capacity_template, enforce)
    return call(VM_METHODS[:resize], @pe_id, capacity_template, enforce)
end

#resubmit ⇒ Object

Deprecated.

use #delete instead



347
348
349
 
# File 'lib/opennebula/virtual_machine.rb', line 347

def resubmit
    action('delete-recreate')
end

#resume ⇒ Object

Resumes the execution of a saved VM



281
282
283
 
# File 'lib/opennebula/virtual_machine.rb', line 281

def resume
    action('resume')
end

#save_as(disk_id, image_name, image_type = "", hot = false) ⇒ Object

Deprecated.

use #disk_snapshot



414
415
416
 
# File 'lib/opennebula/virtual_machine.rb', line 414

def save_as(disk_id, image_name, image_type="", hot=false)
    return disk_snapshot(disk_id, image_name, image_type, hot)
end

#shutdown(hard = false) ⇒ Object

Shutdowns an already deployed VM



231
232
233
 
# File 'lib/opennebula/virtual_machine.rb', line 231

def shutdown(hard=false)
    action(hard ? 'shutdown-hard' : 'shutdown')
end

#snapshot_create(name = "") ⇒ Integer, OpenNebula::Error

Creates a new VM snapshot

Parameters:

  • name (String) (defaults to: "") —

    Name for the snapshot.

Returns:

  • (Integer, OpenNebula::Error) —

    The new snaphost ID in case of success, Error otherwise



512
513
514
515
516
517
 
# File 'lib/opennebula/virtual_machine.rb', line 512

def snapshot_create(name="")
    return Error.new('ID not defined') if !@pe_id

    name ||= ""
    return @client.call(VM_METHODS[:snapshotcreate], @pe_id, name)
end

#snapshot_delete(snap_id) ⇒ nil, OpenNebula::Error

Deletes a VM snapshot

Parameters:

  • snap_id (Integer) —

    Id of the snapshot

Returns:



535
536
537
 
# File 'lib/opennebula/virtual_machine.rb', line 535

def snapshot_delete(snap_id)
    return call(VM_METHODS[:snapshotdelete], @pe_id, snap_id)
end

#snapshot_revert(snap_id) ⇒ nil, OpenNebula::Error

Reverts to a snapshot

Parameters:

  • snap_id (Integer) —

    Id of the snapshot

Returns:



525
526
527
 
# File 'lib/opennebula/virtual_machine.rb', line 525

def snapshot_revert(snap_id)
    return call(VM_METHODS[:snapshotrevert], @pe_id, snap_id)
end

#state ⇒ Object

Returns the VM state of the VirtualMachine (numeric value)



554
555
556
 
# File 'lib/opennebula/virtual_machine.rb', line 554

def state
    self['STATE'].to_i
end

#state_str ⇒ Object

Returns the VM state of the VirtualMachine (string value)



559
560
561
 
# File 'lib/opennebula/virtual_machine.rb', line 559

def state_str
    VM_STATE[state]
end

#status ⇒ Object

Returns the short status string for the VirtualMachine



574
575
576
577
578
579
580
581
582
 
# File 'lib/opennebula/virtual_machine.rb', line 574

def status
    short_state_str=SHORT_VM_STATES[state_str]

    if short_state_str=="actv"
        short_state_str=SHORT_LCM_STATES[lcm_state_str]
    end

    short_state_str
end

#stop ⇒ Object

Stops a running VM



271
272
273
 
# File 'lib/opennebula/virtual_machine.rb', line 271

def stop
    action('stop')
end

#suspend ⇒ Object

Saves a running VM



276
277
278
 
# File 'lib/opennebula/virtual_machine.rb', line 276

def suspend
    action('suspend')
end

#undeploy(hard = false) ⇒ Object

Shuts down an already deployed VM, saving its state in the system DS



236
237
238
 
# File 'lib/opennebula/virtual_machine.rb', line 236

def undeploy(hard=false)
    action(hard ? 'undeploy-hard' : 'undeploy')
end

#unresched ⇒ Object

Unsets the re-scheduling flag for the VM



357
358
359
 
# File 'lib/opennebula/virtual_machine.rb', line 357

def unresched
    action('unresched')
end

#update(new_template = nil, append = false) ⇒ nil, OpenNebula::Error

Replaces the template contents

Parameters:

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

    New template contents

  • append (true, false) (defaults to: false) —

    True to append new attributes instead of replace the whole template

Returns:



187
188
189
 
# File 'lib/opennebula/virtual_machine.rb', line 187

def update(new_template=nil, append=false)
    super(VM_METHODS[:update], new_template, append ? 1 : 0)
end

#user_template_str(indent = true) ⇒ String

Returns the <USER_TEMPLATE> element in text form

Parameters:

  • indent (true, false) (defaults to: true) —

    indents the resulting string, defaults to true

Returns:

  • (String) —

    The USER_TEMPLATE



196
197
198
 
# File 'lib/opennebula/virtual_machine.rb', line 196

def user_template_str(indent=true)
    template_like_str('USER_TEMPLATE', indent)
end

#user_template_xml ⇒ String

Returns the <USER_TEMPLATE> element in XML form

Returns:

  • (String) —

    The USER_TEMPLATE



203
204
205
206
207
208
209
 
# File 'lib/opennebula/virtual_machine.rb', line 203

def user_template_xml
    if NOKOGIRI
        @xml.xpath('TEMPLATE').to_s
    else
        @xml.elements['TEMPLATE'].to_s
    end
end