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",
    :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



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

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)



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

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 



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

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

.get_reason(reason) ⇒ Object 



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

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:



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

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



343
344
345
 
# File 'lib/opennebula/virtual_machine.rb', line 343

def boot
    action('boot')
end

#cancel ⇒ Object

Deprecated.

use #shutdown



259
260
261
 
# File 'lib/opennebula/virtual_machine.rb', line 259

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:



458
459
460
461
462
 
# File 'lib/opennebula/virtual_machine.rb', line 458

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:



449
450
451
 
# File 'lib/opennebula/virtual_machine.rb', line 449

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



440
441
442
 
# File 'lib/opennebula/virtual_machine.rb', line 440

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

#delete(recreate = false) ⇒ Object

Deletes a VM from the pool



329
330
331
332
333
334
335
 
# File 'lib/opennebula/virtual_machine.rb', line 329

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:



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

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

#deploy_id ⇒ Object

Returns the deploy_id of the VirtualMachine (numeric value)



594
595
596
 
# File 'lib/opennebula/virtual_machine.rb', line 594

def deploy_id
    self['DEPLOY_ID']
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:



293
294
295
 
# File 'lib/opennebula/virtual_machine.rb', line 293

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:



304
305
306
 
# File 'lib/opennebula/virtual_machine.rb', line 304

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



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

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



338
339
340
 
# File 'lib/opennebula/virtual_machine.rb', line 338

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

#gid ⇒ Object

Returns the group identifier

return

Integer the element’s group ID



589
590
591
 
# File 'lib/opennebula/virtual_machine.rb', line 589

def gid
    self['GID'].to_i
end

#hold ⇒ Object

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



264
265
266
 
# File 'lib/opennebula/virtual_machine.rb', line 264

def hold
    action('hold')
end

#info ⇒ Object Also known as: info!

Retrieves the information of the given VirtualMachine.



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

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

#lcm_state ⇒ Object

Returns the LCM state of the VirtualMachine (numeric value)



567
568
569
 
# File 'lib/opennebula/virtual_machine.rb', line 567

def lcm_state
    self['LCM_STATE'].to_i
end

#lcm_state_str ⇒ Object

Returns the LCM state of the VirtualMachine (string value)



572
573
574
 
# File 'lib/opennebula/virtual_machine.rb', line 572

def lcm_state_str
    LCM_STATE[lcm_state]
end

#live_migrate(host_id, enforce = false) ⇒ Object

Deprecated.

use #migrate instead



383
384
385
 
# File 'lib/opennebula/virtual_machine.rb', line 383

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:



377
378
379
380
 
# File 'lib/opennebula/virtual_machine.rb', line 377

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



485
486
487
488
 
# File 'lib/opennebula/virtual_machine.rb', line 485

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



493
494
495
496
497
 
# File 'lib/opennebula/virtual_machine.rb', line 493

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:



315
316
317
 
# File 'lib/opennebula/virtual_machine.rb', line 315

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:



324
325
326
 
# File 'lib/opennebula/virtual_machine.rb', line 324

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

#poweroff(hard = false) ⇒ Object

Powers off a running VM



244
245
246
 
# File 'lib/opennebula/virtual_machine.rb', line 244

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

#reboot(hard = false) ⇒ Object

Reboots an already deployed VM



249
250
251
 
# File 'lib/opennebula/virtual_machine.rb', line 249

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:



548
549
550
 
# File 'lib/opennebula/virtual_machine.rb', line 548

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

#release ⇒ Object

Releases a VM from hold state



269
270
271
 
# File 'lib/opennebula/virtual_machine.rb', line 269

def release
    action('release')
end

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

Renames this VM

Parameters:

  • name (String) —

    New name for the VM.

Returns:



505
506
507
 
# File 'lib/opennebula/virtual_machine.rb', line 505

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

#resched ⇒ Object

Sets the re-scheduling flag for the VM



355
356
357
 
# File 'lib/opennebula/virtual_machine.rb', line 355

def resched
    action('resched')
end

#reset ⇒ Object

Deprecated.

use #reboot



254
255
256
 
# File 'lib/opennebula/virtual_machine.rb', line 254

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:



432
433
434
 
# File 'lib/opennebula/virtual_machine.rb', line 432

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

#resubmit ⇒ Object

Deprecated.

use #delete instead



350
351
352
 
# File 'lib/opennebula/virtual_machine.rb', line 350

def resubmit
    action('delete-recreate')
end

#resume ⇒ Object

Resumes the execution of a saved VM



284
285
286
 
# File 'lib/opennebula/virtual_machine.rb', line 284

def resume
    action('resume')
end

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

Deprecated.

use #disk_snapshot



417
418
419
 
# File 'lib/opennebula/virtual_machine.rb', line 417

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



234
235
236
 
# File 'lib/opennebula/virtual_machine.rb', line 234

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



515
516
517
518
519
520
 
# File 'lib/opennebula/virtual_machine.rb', line 515

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:



538
539
540
 
# File 'lib/opennebula/virtual_machine.rb', line 538

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:



528
529
530
 
# File 'lib/opennebula/virtual_machine.rb', line 528

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)



557
558
559
 
# File 'lib/opennebula/virtual_machine.rb', line 557

def state
    self['STATE'].to_i
end

#state_str ⇒ Object

Returns the VM state of the VirtualMachine (string value)



562
563
564
 
# File 'lib/opennebula/virtual_machine.rb', line 562

def state_str
    VM_STATE[state]
end

#status ⇒ Object

Returns the short status string for the VirtualMachine



577
578
579
580
581
582
583
584
585
 
# File 'lib/opennebula/virtual_machine.rb', line 577

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



274
275
276
 
# File 'lib/opennebula/virtual_machine.rb', line 274

def stop
    action('stop')
end

#suspend ⇒ Object

Saves a running VM



279
280
281
 
# File 'lib/opennebula/virtual_machine.rb', line 279

def suspend
    action('suspend')
end

#undeploy(hard = false) ⇒ Object

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



239
240
241
 
# File 'lib/opennebula/virtual_machine.rb', line 239

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

#unresched ⇒ Object

Unsets the re-scheduling flag for the VM



360
361
362
 
# File 'lib/opennebula/virtual_machine.rb', line 360

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:



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

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



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

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



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

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