[xenserver|compute] added getting started examples

lib/fog/xenserver/examples/getting_started.md

@@ -0,0 +1,174 @@
+# fog/xenserver compute examples
+
+fog/xenserver examples contributed by BVox World S.L.U.
+Original examples from https://github.com/bvox/fog-xenserver-examples
+
+Maintainer: Sergio Rubio <rubiojr@bvox.net>
+
+A general introduction to fog/compute is available at:
+
+http://fog.io/1.8.0/compute/
+
+# Getting started: the compute service
+
+## Connecting, retrieving and managing server objects
+
+First, create a connection to the XenServer host:
+
+    require 'fog'
+    require 'pp'
+    
+    #
+    # http://rubydoc.info/github/fog/fog/Fog/Compute/XenServer/Real
+    #
+    conn = Fog::Compute.new({
+      :provider => 'XenServer',
+      :xenserver_url => 'xenserver-test',
+      :xenserver_username => 'root',
+      :xenserver_password => 'changeme',
+      :xenserver_defaults => { 
+        :template => "squeeze-test" 
+      }
+    })
+
+## Listing servers (VMs) and templates
+
+We try to follow fog naming conventions and behavior as much as we can, so the
+terminology used in fog/xenserver is a little bit different from the one
+used in XAPI/XenServer documents. In particular:
+
+* A Fog::Compute::XenServer::Server is a XenServer VM or DomU
+
+* A Fog::Compute::XenServer::Host is a Hypervisor or Dom0
+
+Having that in mind, we can start doing things with out XenServer host.
+
+Listing all the servers (VMs):
+
+    conn.servers.all 
+
+This will return a list of Fog::Compute::XenServer::Server.
+
+List all the servers whose name matches Ubuntu:
+
+    conn.servers.all :name_matches => "Ubuntu"
+
+Listing the first server running (templates aren't included by default 
+in the list):
+
+    server = conn.servers.first
+
+Listing custom templates, that is, the ones created by the user:
+
+    custom = conn.servers.custom_templates
+
+Listing built-in templates (the templates available after a fresh install):
+
+    built_in = conn.servers.builtin_templates
+
+Templates are regular Fog::Compute::XenServer::Server objects too, so you can
+inspect some of their attributes. The relevant XAPI documentation:
+
+http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VM
+
+Fog::Compute::XenServer::Server attributes and operations usually map to the
+ones found in the official Citrix documentation, and they are available at:
+
+http://rubydoc.info/github/fog/fog/Fog/Compute/XenServer/Server
+
+and 
+
+https://github.com/fog/fog/blob/master/lib/fog/xenserver/models/compute/server.rb
+
+## Server operations and attributes
+
+Getting server VIFs (virtual network interfaces):
+
+    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VIF
+    server.networks
+    # or server.vifs
+
+Listing the server VBDs (virtual block devices):
+
+    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VBD
+    server.vbds
+
+
+Get VDIs objects (virtual disk images) attached to the server:
+
+    server.vbds.each do |vbd|
+      # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VDI
+      vdi = vbd.vdi
+      # In bytes
+      puts vdi.virtual_size
+      puts vdi.physical_utilisation
+    end
+
+## Server creation and life-cycle management
+
+Creating a new server/VM:
+
+    server = conn.servers.create :name => 'foobar',
+                                 :template_name => 'squeeze-test'
+
+The server is automatically started after that.
+
+Note that template_name is optional if you have specified the ':template'
+parameter when when creating the connection.
+
+If you don't want to automatically start the server, use 'new' instead of 'create':
+
+    server = conn.servers.new :name => 'foobar',
+                              :template_name => 'squeeze-test'
+
+and set auto_start to false when saving it:
+
+    server.save :auto_start => false
+
+Shutting down the server, By forcing it
+
+    server.stop 'hard'
+    # server.hard_shutdown is equivalent
+
+Doing a clean shutdown
+
+    server.stop 'clean'
+    # server.clean_shutdown is equivalent
+
+And finally, destroy it (it will force a shutdown first if running):
+
+    server.destroy
+
+# XenServer Host (Dom0) operations
+
+The are some operations that can be performed on the host, without retrieving
+and/or manipulating servers:
+
+Listing all the VBDs (virtual block devices):
+
+    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VBD
+    conn.vbds.all
+
+This will retrieve the list of every single VBD available in the XenServer.
+
+Same thing applies to the virtual disk images:
+
+    conn.vdis.all
+
+Listing Storage Repositories (Xen SRs), where the disk images are stored:
+    
+    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=SR
+    conn.storage_repositories
+
+
+XenServer Pools:
+
+    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=pool
+    conn.pools
+
+
+Retrieve the default storage repository in a pool:
+
+    conn.pools.first.default_storage_repository
+    # or the equivalent conn.pools.first.default_sr
+