fog-xenserver 0.0.1.alpha

data/lib/fog/xenserver/examples/chage_default_storage_repository.md

@@ -0,0 +1,99 @@
+# How To Change the Default Storage Repository to File-based VHD-on-EXT3
+
+**NOTE: Requires fog > 1.8 (currently in development as of this writing)**
+
+This tutorial explains how to convert a local Logical Volume Manager (LVM)
+based storage repository into a file-based (VHD) storage repository.
+
+It's the fog/xenserver version of the original Citrix KB article:
+
+http://support.citrix.com/article/ctx116324
+
+To create this tutorial, I've used a vanilla XCP 1.6 ISO install in VirtualBox.
+
+## Create the connection
+
+```ruby
+require 'fog'
+
+conn = Fog::Compute.new({
+  :provider => 'XenServer',
+  :xenserver_url => '192.168.1.39',
+  :xenserver_username => 'root',
+  :xenserver_password => 'secret'
+})
+```
+
+## Remove the LVM-backed storage repository (SR).
+
+Find the default LVM storage repository:
+
+```ruby
+#
+# Equivalent to:
+# xe sr-list type=lvm
+#
+lvm_sr = nil
+conn.storage_repositories.each do |sr|
+  lvm_sr = sr if sr.type == 'lvm'
+end
+```
+
+Determine the UUID for your default SR's physical block device:
+
+```ruby
+#
+# Equivalent to:
+# xe pbd-list sr-uuid=your SR UUID
+#
+if lvm_sr
+  conn.pbds.each do |pbd|
+    # Unplug it if found
+    # Equivalent to:
+    # xe pbd-unplug uuid=your PBD UUID
+    #
+    pbd.unplug if pbd.storage_repository.uuid == lvm_sr.uuid
+  end
+  # Destroy the SR
+  lvm_sr.destroy
+end
+```
+
+Create a new VHD-backed SR:
+
+```ruby
+#
+# Equivalent to:
+#
+# xe sr-create content-type="local SR" \
+#              host-uuid=5d189b7a-cd5e-4029-9940-d4daaa34633d \
+#              type=ext device-config-device=/dev/sda3 shared=false \
+#              name-label="Local File SR"
+#
+sr = conn.storage_repositories.create :name => 'Local File SR',
+                                      :host => conn.hosts.first,
+                                      :type => 'ext',
+                                      :content_type => 'local SR',
+                                      :device_config => { :device => '/dev/sda3' },
+                                      :shared => false
+```
+
+Set your SR as the default SR on the system:
+
+```ruby
+#
+# Equivalent command:
+# xe pool-param-set suspend-image-SR='YOUR NEW SR UUID' uuid=bleh
+#
+conn.pools.first.default_storage_repository = sr
+```
+
+Set your SR as the default location for suspended VM images:
+
+```ruby
+#
+# Equivalent command:
+# xe pool-param-set suspend-image-SR= YOUR NEW SR UUID  uuid=bleh
+#
+conn.pools.first.suspend_image_sr = sr
+```

data/lib/fog/xenserver/examples/creating_servers.md

@@ -0,0 +1,168 @@
+# Creating servers (VMs) and templates
+
+The basic server creation steps are detailed in the getting started tutorial.
+
+Now let's do something a little bit more complex and probably more useful in
+day-to-day operations. That is:
+
+1. Uploading a VHD image.
+2. Create a new template with it.
+3. Spin a new server using the recently added template.
+
+## Part I: Upload the VHD
+
+Assuming we have an image file 'ubuntu.vhd' ready to be uploaded, let's create
+the connection to the XenServer host and upload the image to the storage repository,
+using SSH. The code also assumes that you have a file storage repository mounted
+somewhere in /var/run/sr-mount/#{sr-UUID} (the standard XenServer base directory
+for mounted storage repositories).
+
+    require 'fog'
+    require 'net/scp'
+    require 'uuidtools'
+
+    #
+    # Create the connection to the XenServer host
+    #
+    xenserver = Fog::Compute.new({
+      :provider           => 'XenServer',
+      :xenserver_url      => 'xenserver-test',
+      :xenserver_username => 'root',
+      :xenserver_password => 'secret',
+    })
+
+
+We'll be uploading the image to the "Local File SR" storage repository, so
+we need the reference to this SR (Storage Repository):
+
+    sr = xenserver.storage_repositories.find { |sr| sr.name ==  "Local File SR" }
+
+XenServer uses UUIDs to store images in the storage repositories, so we will
+emulate that behavior, creating a new UUID for our image and uploading it.
+
+    #
+    # Use the excelent uuidtools gem to create the new UUID
+    # for the image
+    #
+    image_uuid = UUIDTools::UUID.random_create.to_s
+
+
+To upload the new image using SCP, we need the destination directory, where the
+SR is mounted. In our case, the storage repository mount point is
+/var/run/sr-mount/#{sr.uuid} (where sr.uuid is the UUID of the storage
+repository). We will upload the new image there:
+
+    sr_mount_point = "/var/run/sr-mount/#{sr.uuid}"
+    # Target image file path. We will upload the local image to the destination
+    # using SCP
+    destination = File.join(sr_mount_point, "#{image_uuid}.vhd")
+    # source image, located in the current directory
+    source = 'ubuntu.vhd'
+    # Use the XenServer root credentials to upload
+    Net::SSH.start('xenserver-test', 'root', :password => 'secret') do |ssh|
+      ssh.scp.upload!(source, destination) do |ch, name, sent, total|
+        # print progress
+        p = (sent.to_f * 100 / total.to_f).to_i.to_s
+        print "\rProgress: #{p}% completed"
+      end
+    end
+
+We need to let the XenServer know, that there's a new image:
+
+    sr.scan
+
+Now that XenServer is aware of the new image, get its reference
+and set the image name attribute to 'ubuntu-template'
+
+    ubuntu_vdi = xenserver.vdis.find { |vdi| vdi.uuid == image_uuid }
+    ubuntu_vdi.set_attribute 'name_label', 'ubuntu-template'
+
+Good! the image is ready to be used.
+
+## Part II: create the server template
+
+We have the image ready to be used by our new template.
+
+Templates are regular servers, so let's create one with 512 MB of RAM, 1 CPU
+and a network card. The main difference with a regular server from an API
+point of view is that we will not start it.
+
+We will also create the template as PV (paravirtual):
+
+    server_mem = (512 * 1024 * 1024).to_s
+    server = xenserver.servers.new :name               => "ubuntu-template",
+                                   # Required when using Server.new
+                                   :affinity           => xenserver.hosts.first,
+                                   :other_config       => {},
+                                   :pv_bootloader      => 'pygrub',          # PV related
+                                   :hvm_boot_policy    => '',                # PV related
+                                   :pv_args            => '-- console=hvc0', # PV related
+                                   :memory_static_max  => mem,
+                                   :memory_static_min  => mem,
+                                   :memory_dynamic_max => mem,
+                                   :memory_dynamic_min => mem
+    server.save
+
+We need to attach the disk image to a VBD and to the server
+
+    xenserver.vbds.create :server => server, :vdi => ubuntu_vdi
+
+Note that we're using Server.new here, instead of Server.create.
+Server.create would start the server, and that's not what we want here.
+
+Let's add the NIC (VIF or virtual interface) to the server.
+
+I have a network in my XenServer named "Pool-wide network associated with eth0"
+bridged to the physical eth0 NIC and I will attach the new NIC to that network.
+
+Don't be scared by the VIF creation code. There are easier ways to create a
+VIF, and we'll be dealing with that and some other cases in the networking
+tutorial (TODO).
+
+First, let's find the network since we'll need the reference.
+
+    net = xenserver.networks.find { |n| n.name == 'Pool-wide network associated with eth0' }
+
+To create the VM VIF, we need to set some attributes and use the
+create_vif_custom request:
+
+    vif_attr = {
+      'MAC_autogenerated' => 'True',
+      'VM'                => server.reference, # we need the VM reference here
+      'network'           => net.reference, # we need the Network reference here
+      'MAC'               => '', # ignored, since we use autogeneration
+      'device'            => '0',
+      'MTU'               => '0',
+      'other_config'      => {},
+      'qos_algorithm_type' => 'ratelimit',
+      'qos_algorithm_params' => {}
+    }
+    xenserver.create_vif_custom vif_attr
+
+
+The template is now ready to be used and we can list it!
+
+    xenserver.servers.custom_templates.find { |t| puts t.name }
+
+## Party III: spin a new server using the brand new template
+
+Now that we have the template in place, it's easy to create as many servers
+as you want. All of them will share hardware specs with the template. That is,
+512 MB of RAM, 1 CPU, 1 NIC attached to the 'Pool-wide network...':
+
+    xenserver.servers.create :name => 'my-brand-new-server',
+                             :template_name => 'ubuntu-template'
+
+
+# The End
+
+Pretty similar code is used by knife-xenserver (http://github.com/bvox/knife-xenserver)
+to upload new templates. Have a look at it if you're interested, it's full of
+examples and fog/xenserver tricks to manage XenServer/XCP hosts.
+
+The full source code used in this tutorial is available at:
+
+https://github.com/bvox/fog-xenserver-examples/blob/master/upload_template_and_create.rb
+
+Enjoy!
+

data/lib/fog/xenserver/examples/getting_started.md

@@ -0,0 +1,163 @@
+# 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
+

data/lib/fog/xenserver/examples/networks-and-vlans.rb

@@ -0,0 +1,45 @@
+require 'fog'
+
+#
+# Create the connection to the XenServer host
+#
+xenserver = Fog::Compute.new({
+  :provider           => 'XenServer',
+  :xenserver_url      => '1.2.3.4',
+  :xenserver_username => 'root',
+  :xenserver_password => 'secret',
+})
+
+# We have a bonded interface in XenServer, bond0 and
+# we want to add the VLANs there.
+# Note the VLAN ID -1, it is important since you
+# will problably have many PIFs with device == bond0
+# but we need the one without a proper VLAN ID
+#
+bondmaster_pif = xenserver.pifs.find do |pif|
+  pif.vlan == "-1" and pif.device == "bond0"
+end
+
+# Another valid way of finding a PIF, without bonding
+# pif = xenserver.pifs.find { |pif| pif.physical and pif.device == 'eth0' }
+
+# We want to create these new VLANs
+vlans = [
+  { "name" => "VLAN 44", "vlanid" => 44},
+  { "name" => "VLAN 55", "vlanid" => 55}
+]
+
+
+vlans.each do |vlan|
+  # Do not create duplicated networks
+  if xenserver.networks.find { |n| n.name == vlan['name'] }
+    puts "Network #{vlan['name']} available, skipping"
+    next
+  end
+
+  puts "Craeting Network #{vlan['name']}, VLAN ID #{vlan['vlanid']}"
+  network = xenserver.networks.create :name => vlan['name']
+  xenserver.vlans.create :tag => vlan['vlanid'],
+                         :network => network,
+                         :pif => bondmaster_pif
+end