rbvmomi 1.0.2 → 1.1.0

data/.yardopts

@@ -0,0 +1,5 @@
+--title "RbVmomi - a Ruby interface to the vSphere API"
+--no-private
+--readme README.rdoc
+lib/rbvmomi/vim.rb
+lib/rbvmomi/vim/*.rb

data/README.rdoc

@@ -0,0 +1,71 @@
+= RbVmomi
+
+== Introduction
+
+RbVmomi is a Ruby interface to the vSphere API. Like the Perl and Java SDKs,
+you can use it to manage ESX and VirtualCenter servers. The current release
+supports the vSphere 4.1 API. RbVmomi specific documentation is
+online[http://rdoc.info/github/rlane/rbvmomi/master/frames] and is meant to
+be used alongside the official documentation[http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/index.html].
+
+== Usage
+
+A simple example of turning on a VM:
+
+    require 'rbvmomi'
+    vim = RbVmomi::VIM.connect host: 'foo', user: 'bar', password: 'baz'
+    dc = vim.serviceInstance.find_datacenter("mydatacenter") or fail "datacenter not found"
+    vm = dc.find_vm("myvm") or fail "VM not found"
+    vm.PowerOnVM_Task.wait_for_completion
+
+This code uses several RbVmomi extensions to the VI API for concision. The
+expanded snippet below uses only standard API calls and should be familiar to
+users of the Java SDK:
+
+    require 'rbvmomi'
+    vim = RbVmomi::VIM.connect host: 'foo', user: 'bar', password: 'baz'
+    rootFolder = vim.serviceInstance.content.rootFolder
+    dc = rootFolder.childEntity.grep(RbVmomi::VIM::Datacenter).find { |x| x.name == "mydatacenter" } or fail "datacenter not found"
+    vm = dc.vmFolder.childEntity.grep(RbVmomi::VIM::VirtualMachine).find { |x| x.name == "myvm" } or fail "VM not found"
+    task = vm.PowerOnVM_Task
+    filter = vim.propertyCollector.CreateFilter(
+      spec: {
+        propSet: [{ type: 'Task', all: false, pathSet: ['info.state']}],
+        objectSet: [{ obj: task }]
+      },
+      partialUpdates: false
+    )
+    ver = ''
+    while true
+      result = vim.propertyCollector.WaitForUpdates(version: ver)
+      ver = result.version
+      break if ['success', 'error'].member? task.info.state
+    end
+    filter.DestroyPropertyFilter
+    raise task.info.error if task.info.state == 'error'
+
+As you can see, the extensions RbVmomi adds can dramatically decrease the code
+needed to perform simple tasks while still letting you use the full power of
+the API when necessary. RbVmomi extensions are often more efficient than a
+naive implementation; for example, the find_vm method on VIM::Datacenter used
+in the first example uses the SearchIndex for fast lookups.
+
+A few important points:
+
+* Ruby 1.9 is required.
+* Properties are exposed as accessor methods.
+* All class, method, parameter, and property names match the official documentation[http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/index.html].
+* Data object types can usually be inferred from context, so you may use a hash instead.
+* Enumeration values are simply strings.
+* Example code is included in the examples/ directory.
+* A set of helper methods for Trollop is included to speed up development of
+  command line apps. See the included examples for usage.
+* This is a side project of a VMware employee and is entirely unsupported by VMware.
+
+Built-in extensions are under +lib/rbvmomi/vim/+. You are encouraged to
+reopen VIM classes in your applications and add extensions of your own. If you
+write something generally useful please send it to me and I'll add it in.
+
+== Development
+
+Send patches to rlane@vmware.com.

data/Rakefile

@@ -1,3 +1,7 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'yard'
+
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
@@ -18,3 +22,10 @@ rescue LoadError
   puts "Jeweler not available. Install it with: gem install jeweler"
 end
 
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end
+
+YARD::Rake::YardocTask.new

data/VERSION

@@ -1 +1 @@
-1.0.2
+1.1.0

data/devel/analyze-xml.rb

@@ -2,45 +2,45 @@ require 'nokogiri'
 
 # removes line breaks and whitespace between xml nodes.
 def prepare_xml(xml)
-	xml = xml.gsub(/\n+/, "")
-	xml = xml.gsub(/(>)\s*(<)/, '\1\2')
+  xml = xml.gsub(/\n+/, "")
+  xml = xml.gsub(/(>)\s*(<)/, '\1\2')
 end
 
 def analyze_xml x, tree
-	subtree = (tree[x.name] ||= { :attributes => [], :min_occur => nil, :max_occur => nil })
-	attrs = x.attributes.keys.sort
-	subtree[:attributes] << attrs unless subtree[:attributes].member? attrs
+  subtree = (tree[x.name] ||= { :attributes => [], :min_occur => nil, :max_occur => nil })
+  attrs = x.attributes.keys.sort
+  subtree[:attributes] << attrs unless subtree[:attributes].member? attrs
 
-	child_occurs = Hash.new 0
-	x.children.select(&:element?).each do |c|
-		child_occurs[c.name] += 1
-		analyze_xml c, subtree
-	end
+  child_occurs = Hash.new 0
+  x.children.select(&:element?).each do |c|
+    child_occurs[c.name] += 1
+    analyze_xml c, subtree
+  end
 
-	subtree.select { |k,v| k.is_a? String }.each do |k,v|
-		v[:min_occur] = [v[:min_occur], child_occurs[k]].compact.min
-		v[:max_occur] = [v[:max_occur], child_occurs[k]].compact.max
-	end
+  subtree.select { |k,v| k.is_a? String }.each do |k,v|
+    v[:min_occur] = [v[:min_occur], child_occurs[k]].compact.min
+    v[:max_occur] = [v[:max_occur], child_occurs[k]].compact.max
+  end
 end
 
 def print_tree tree, indent=0
-	tree.select { |k,v| k.is_a? String }.sort.each do |k,v|
-		attrs = v[:attributes] || []
-		min, max = v[:min_occur], v[:max_occur]
-		numsym = if min == 0 and max == 0 then fail
-		         elsif min == 0 and max == 1 then '?'
-						 elsif min == 0 then '*'
-						 elsif min == 1 and max == 1 then ''
-						 else '+'
-						 end
-		puts "#{'  '*indent}#{k}#{numsym}: #{attrs.sort.map { |a| "[#{a * ' '}]"} * ', '} {#{min},#{max}}"
-		print_tree v, (indent+1)
-	end
-end	
+  tree.select { |k,v| k.is_a? String }.sort.each do |k,v|
+    attrs = v[:attributes] || []
+    min, max = v[:min_occur], v[:max_occur]
+    numsym = if min == 0 and max == 0 then fail
+             elsif min == 0 and max == 1 then '?'
+             elsif min == 0 then '*'
+             elsif min == 1 and max == 1 then ''
+             else '+'
+             end
+    puts "#{'  '*indent}#{k}#{numsym}: #{attrs.sort.map { |a| "[#{a * ' '}]"} * ', '} {#{min},#{max}}"
+    print_tree v, (indent+1)
+  end
+end  
 
 tree = {}
 ARGV.each do |fn|
-	nk = Nokogiri(prepare_xml(File.read fn))
-	analyze_xml nk.root, tree
+  nk = Nokogiri(prepare_xml(File.read fn))
+  analyze_xml nk.root, tree
 end
 print_tree tree

data/{test/test.rb → examples/create_vm.rb}

@@ -1,23 +1,51 @@
 #!/usr/bin/env ruby
+require 'trollop'
 require 'rbvmomi'
-include RbVmomi
+require 'rbvmomi/trollop'
 
-vim = RbVmomi.connect ENV['RBVMOMI_URI']
+VIM = RbVmomi::VIM
+N = 2
+
+opts = Trollop.options do
+  banner <<-EOS
+Create and destroy a couple of VMs.
+
+Usage:
+    create_vm.rb [options]
+
+VIM connection options:
+    EOS
+
+    rbvmomi_connection_opts
+
+    text <<-EOS
 
-rootFolder = vim.serviceInstance.RetrieveServiceContent.rootFolder
+VM location options:
+    EOS
 
-dc = rootFolder.childEntity.first
+    rbvmomi_datacenter_opt
+
+    text <<-EOS
+
+Other options:
+  EOS
+end
+
+Trollop.die("must specify host") unless opts[:host]
+vm_name = ARGV[0] or abort "must specify VM name"
+
+vim = VIM.connect opts
+dc = vim.serviceInstance.find_datacenter(opts[:datacenter]) or abort "datacenter not found"
 vmFolder = dc.vmFolder
-vms = vmFolder.childEntity
-hosts = dc.hostFolder.childEntity
+hosts = dc.hostFolder.children
 rp = hosts.first.resourcePool
 
 vm_cfg = {
-  name: 'vm',
-  guestId: 'otherGuest64',
+  name: vm_name,
+  guestId: 'otherGuest',
   files: { vmPathName: '[datastore1]' },
-  numCPUs: 2,
-  memoryMB: 3072,
+  numCPUs: 1,
+  memoryMB: 128,
   deviceChange: [
     {
       operation: :add,
@@ -58,12 +86,9 @@ vm_cfg = {
   extraConfig: [
     {
       key: 'bios.bootOrder',
-      value: XSD.string('ethernet0')
+      value: 'ethernet0'
     }
   ]
 }
 
-N = 2
-create_tasks = (0...N).map { vmFolder.CreateVM_Task(:config => vm_cfg, :pool => rp) }
-destroy_tasks = create_tasks.map { |x| x.wait_task.Destroy_Task }
-destroy_tasks.each { |x| x.wait_task }
+vmFolder.CreateVM_Task(:config => vm_cfg, :pool => rp).wait_for_completion

data/examples/extraConfig.rb

@@ -0,0 +1,54 @@
+require 'trollop'
+require 'rbvmomi'
+require 'rbvmomi/trollop'
+
+VIM = RbVmomi::VIM
+CMDS = %w(list set)
+
+opts = Trollop.options do
+  banner <<-EOS
+View and modify VM extraConfig options.
+
+Usage:
+    extraConfig.rb [options] VM list
+    extraConfig.rb [options] VM set key=value [key=value...]
+
+Commands: #{CMDS * ' '}
+
+VIM connection options:
+    EOS
+
+    rbvmomi_connection_opts
+
+    text <<-EOS
+
+VM location options:
+    EOS
+
+    rbvmomi_datacenter_opt
+
+    text <<-EOS
+
+Other options:
+  EOS
+
+  stop_on CMDS
+end
+
+vm_name = ARGV[0] or Trollop.die("no VM name given")
+cmd = ARGV[1] or Trollop.die("no command given")
+abort "invalid command" unless CMDS.member? cmd
+Trollop.die("must specify host") unless opts[:host]
+
+vim = VIM.connect opts
+
+dc = vim.serviceInstance.find_datacenter(opts[:datacenter]) or abort "datacenter not found"
+vm = dc.find_vm(vm_name) or abort "VM not found"
+
+case cmd
+when 'list'
+  vm.config.extraConfig.each { |x| puts "#{x.key}: #{x.value}" }
+when 'set'
+  extraConfig = ARGV.map { |x| x.split("=", 2) }.map { |k,v| { key: k, value: v } }
+  vm.ReconfigVM_Task(spec: VIM.VirtualMachineConfigSpec(extraConfig: extraConfig)).wait_for_completion
+end

data/examples/power.rb

@@ -0,0 +1,57 @@
+require 'trollop'
+require 'rbvmomi'
+require 'rbvmomi/trollop'
+
+VIM = RbVmomi::VIM
+CMDS = %w(on off reset suspend)
+
+opts = Trollop.options do
+  banner <<-EOS
+Perform VM power operations.
+
+Usage:
+    power.rb [options] cmd VM
+
+Commands: #{CMDS * ' '}
+
+VIM connection options:
+    EOS
+
+    rbvmomi_connection_opts
+
+    text <<-EOS
+
+VM location options:
+    EOS
+
+    rbvmomi_datacenter_opt
+
+    text <<-EOS
+
+Other options:
+  EOS
+
+  stop_on CMDS
+end
+
+cmd = ARGV[0] or Trollop.die("no command given")
+vm_name = ARGV[1] or Trollop.die("no VM name given")
+Trollop.die("must specify host") unless opts[:host]
+
+vim = VIM.connect opts
+
+dc = vim.serviceInstance.content.rootFolder.traverse(opts[:datacenter], VIM::Datacenter) or abort "datacenter not found"
+vm = dc.vmFolder.traverse(vm_name, VIM::VirtualMachine) or abort "VM not found"
+
+case cmd
+when 'on'
+  vm.PowerOnVM_Task.wait_for_completion
+when 'off'
+  vm.PowerOffVM_Task.wait_for_completion
+when 'reset'
+  vm.ResetVM_Task.wait_for_completion
+when 'suspend'
+  vm.SuspendVM_Task.wait_for_completion
+else
+  abort "invalid command"
+end

data/examples/readme-1.rb

@@ -0,0 +1,35 @@
+require 'rbvmomi'
+require 'rbvmomi/trollop'
+
+opts = Trollop.options do
+  banner <<-EOS
+Example 1 from the README: Power on a VM.
+
+Usage:
+    readme-1.rb [options] VM name
+
+VIM connection options:
+    EOS
+
+    rbvmomi_connection_opts
+
+    text <<-EOS
+
+VM location options:
+    EOS
+
+    rbvmomi_datacenter_opt
+
+    text <<-EOS
+
+Other options:
+  EOS
+end
+
+Trollop.die("must specify host") unless opts[:host]
+vm_name = ARGV[0] or abort "must specify VM name"
+
+vim = RbVmomi::VIM.connect opts
+dc = vim.serviceInstance.find_datacenter(opts[:datacenter]) or fail "datacenter not found"
+vm = dc.find_vm(vm_name) or fail "VM not found"
+vm.PowerOnVM_Task.wait_for_completion

data/examples/readme-2.rb

@@ -0,0 +1,51 @@
+require 'rbvmomi'
+require 'rbvmomi/trollop'
+
+opts = Trollop.options do
+  banner <<-EOS
+Example 2 from the README: Power on a VM the hard way.
+
+Usage:
+    readme-2.rb [options] VM name
+
+VIM connection options:
+    EOS
+
+    rbvmomi_connection_opts
+
+    text <<-EOS
+
+VM location options:
+    EOS
+
+    rbvmomi_datacenter_opt
+
+    text <<-EOS
+
+Other options:
+  EOS
+end
+
+Trollop.die("must specify host") unless opts[:host]
+vm_name = ARGV[0] or abort "must specify VM name"
+
+vim = RbVmomi::VIM.connect opts
+rootFolder = vim.serviceInstance.content.rootFolder
+dc = rootFolder.childEntity.grep(RbVmomi::VIM::Datacenter).find { |x| x.name == opts[:datacenter] } or fail "datacenter not found"
+vm = dc.vmFolder.childEntity.grep(RbVmomi::VIM::VirtualMachine).find { |x| x.name == vm_name } or fail "VM not found"
+task = vm.PowerOnVM_Task
+filter = vim.propertyCollector.CreateFilter(
+  spec: {
+    propSet: [{ type: 'Task', all: false, pathSet: ['info.state']}],
+    objectSet: [{ obj: task }]
+  },
+  partialUpdates: false
+)
+ver = ''
+while true
+  result = vim.propertyCollector.WaitForUpdates(version: ver)
+  ver = result.version
+  break if ['success', 'error'].member? task.info.state
+end
+filter.DestroyPropertyFilter
+raise task.info.error if task.info.state == 'error'