ruby_vcloud_sdk 0.6.0 → 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c8100349c1b50cb4fee66f496cd6c1ab4783addd
+  data.tar.gz: eb8dccf37fbec5841a64b0949216b2b595a2174b
+SHA512:
+  metadata.gz: 4919e11c4041564202d38b4e1f2293e77b1df80cd5af8c8760acd25c158e16f6ec2cfef5bd9cfd8d8ba3d3ad720f3e292eb9005bda0250592f73bc282f7f595e
+  data.tar.gz: b7af07e1d38d9cb0e8198bf0d6ef1f7a45c7aa4e1b65826fe380031be0c89f2ba2285ea3394ea6adfd61c801ebd4dc25434b94d2d429ef242545ed592364d0a0

data/README.md

@@ -6,11 +6,20 @@ Copyright (c) VMware, Inc.
   Client
   
     find_vdc_by_name
+      parameters:
+        name (String): name of VDC
       returns: VDC object matching name
       throws:
         'ObjectNotFoundError' when VDC with the name does not exist
         'RestClient::BadRequest' for un-expected errors
 
+    vdc_exists?
+      parameters:
+        name (String): name of VDC
+      returns: boolean
+      throws:
+        'RestClient::BadRequest' for un-expected errors
+
     catalogs
       returns: array of catalog objects
       throws:
@@ -36,10 +45,15 @@ Copyright (c) VMware, Inc.
     delete_catalog_by_name
       parameters:
         name (String): name of catalog
-      returns: nil
+      returns: Client object
       throws:
         'ObjectNotFoundError' when catalog with the name does not exist
         'RestClient::BadRequest' for un-expected errors
+
+    right_records
+      returns: array of RightRecord objects
+      throws:
+        'RestClient::BadRequest' for un-expected errors
     
   VDC
     
@@ -54,11 +68,20 @@ Copyright (c) VMware, Inc.
         'RestClient::BadRequest' for un-expected errors
     
     find_storage_profile_by_name
+      parameters:
+        name (String): name of storage profile
       returns:
         storage profile object matching name
       throws:
         'ObjectNotFoundError' when storage profile with the name does not exist
         'RestClient::BadRequest' for un-expected errors
+
+    storage_profile_exists?
+      parameters:
+        name (String): name of storage profile
+      returns: boolean
+      throws:
+        'RestClient::BadRequest' for un-expected errors
     
     vapps
       returns: array of vapp objects
@@ -71,13 +94,30 @@ Copyright (c) VMware, Inc.
         'RestClient::BadRequest' for un-expected errors
     
     find_vapp_by_name
+      parameters:
+        name (String): name of vapp
       returns:
         vapp object matching name
       throws:
         'ObjectNotFoundError' when vapp with the name does not exist
         'RestClient::BadRequest' for un-expected errors
 
+    vapp_exists?
+      parameters:
+        name (String): name of vapp
+      returns: boolean
+      throws:
+        'RestClient::BadRequest' for un-expected errors
+
+    edge_gateways
+      returns: array of EdgeGateway objects
+      throws:
+        'RestClient::BadRequest' for un-expected errors
+
     resources
+      returns: Resources object
+      throws:
+        'RestClient::BadRequest' for un-expected errors
     
     networks
       returns: array of network objects
@@ -90,12 +130,21 @@ Copyright (c) VMware, Inc.
         'RestClient::BadRequest' for un-expected errors
     
     find_network_by_name
+      parameters:
+        name (String): name of network
       returns:
         network object matching name
       throws:
         'ObjectNotFoundError' when network with the name does not exist
         'RestClient::BadRequest' for un-expected errors
 
+    network_exists?
+      parameters:
+        name (String): name of network
+      returns: boolean
+      throws:
+        'RestClient::BadRequest' for un-expected errors
+
     disks
       returns: array of disk objects
       throws:
@@ -107,12 +156,21 @@ Copyright (c) VMware, Inc.
         'RestClient::BadRequest' for un-expected errors
 
     find_disks_by_name
+      parameters:
+        name (String): name of disk
       returns:
         array of disk objects matching name
       throws:
         'ObjectNotFoundError' when disk with the name does not exist
         'RestClient::BadRequest' for un-expected errors
 
+    disk_exists?
+      parameters:
+        name (String): name of disk
+      returns: boolean
+      throws:
+        'RestClient::BadRequest' for un-expected errors
+
     create_disk
       parameters:
         name (String): name of disk
@@ -130,7 +188,7 @@ Copyright (c) VMware, Inc.
     delete_disk_by_name
       parameters:
         name (String): name of disk
-      returns: nil
+      returns: VDC object
       throws:
         'CloudError' when more than one disks matching the name exist
         'CloudError' when disk is attached to vm
@@ -139,7 +197,7 @@ Copyright (c) VMware, Inc.
     delete_all_disks_by_name
       parameters:
         name (String): name of disk
-      returns: nil
+      returns: VDC object
       throws:
         'CloudError' when any disk deletion failure occurs
         'RestClient::BadRequest' for un-expected errors
@@ -156,37 +214,50 @@ Copyright (c) VMware, Inc.
        throws:
          'RestClient::BadRequest' for un-expected errors
      
-     find_item
-        returns: catalog item matching name and type
-        throws:
-          'ObjectNotFoundError' when an item matching the name and type is not found
-          'RestClient::BadRequest' for un-expected errors
+    find_item
+      parameters:
+        name (String): name of item
+        type (String, optional): type of item - "application/vnd.vmware.vcloud.vAppTemplate+xml" or "application/vnd.vmware.vcloud.media+xml"
+      returns: catalog item matching name and type
+      throws:
+        'ObjectNotFoundError' when an item matching the name and type is not found
+        'RestClient::BadRequest' for un-expected errors
 
-     item_exists?
-        returns: boolean
-        throws:
-          'RestClient::BadRequest' for un-expected errors
+    item_exists?
+      parameters:
+        name (String): name of item
+        type (String, optional): type of item - "application/vnd.vmware.vcloud.vAppTemplate+xml" or "application/vnd.vmware.vcloud.media+xml"
+
+      returns: boolean
+      throws:
+        'RestClient::BadRequest' for un-expected errors
      
      delete_item_by_name_and_type
         parameters:
           name (String): name of item
           type (String, optional): type of item - "application/vnd.vmware.vcloud.vAppTemplate+xml" or "application/vnd.vmware.vcloud.media+xml"
-        returns: nil
+        returns: Catalog object
         throws:
           'ObjectNotFoundError' when an item matching the name and type is not found
           'RestClient::BadRequest' for un-expected errors
 
      delete_all_items
-        returns: nil
+        returns: Catalog object
         throws:
           'RestClient::BadRequest' for un-expected errors
 
-     upload_media
-        returns: catalog item uploaded
-        throws:
-          'CloudError' when media file matching name already exists
-          'ObjectNotFoundError' when storage profile with the name does not exist
-          'RestClient::BadRequest' for un-expected errors
+    upload_media
+      parameters:
+        vdc_name (String): name of vdc
+        media_name (String): name of media
+        file (String): path of media file
+        storage_profile_name (String, optional): name of storage profile to upload vapp template to
+        image_type (String, optional): type of image file
+      returns: catalog item uploaded
+      throws:
+        'CloudError' when media file matching name already exists
+        'ObjectNotFoundError' when storage profile with the name does not exist
+        'RestClient::BadRequest' for un-expected errors
 
      find_media_by_name
         parameters:
@@ -243,25 +314,28 @@ Copyright (c) VMware, Inc.
   VApp
   
      delete
-        returns: task object
+        returns: nil
         throws:
           'CloudError' if VApp is powered on
           'RestClient::BadRequest' for un-expected errors
      
      power_on
-        returns: task object
+        returns: VApp object
         throws:
           'CloudError' if power_on_link of VApp is missing
           'RestClient::BadRequest' for un-expected errors
      
      power_off
-        returns: task object
+        returns: VApp object
         throws:
           'CloudError' if power_off_link of VApp is missing
           'VappSuspendedError' if VApp is suspended
           'RestClient::BadRequest' for un-expected errors
 
      recompose_from_vapp_template
+        parameters:
+          catalog_name (String): name of catalog
+          template_name (String): name of vapp template
         returns: recomposed vapp
         throws:
           'CloudError' when vapp is powered on
@@ -285,7 +359,16 @@ Copyright (c) VMware, Inc.
          'ObjectNotFoundError' when VM with the name does not exist
          'RestClient::BadRequest' for un-expected errors
 
+     vm_exists?
+      parameters:
+        name (String): name of vm
+      returns: boolean
+      throws:
+        'RestClient::BadRequest' for un-expected errors
+
      remove_vm_by_name
+      parameters:
+        name (String): name of vm
        returns: parent VApp object
        throws:
          'ObjectNotFoundError' when VM with the name does not exist
@@ -306,7 +389,7 @@ Copyright (c) VMware, Inc.
          vApps to be powered on without conflict by isolating the MAC and IP addresses of the
          virtual machines. Available options are "bridged", "isolated" and "natRouted". Default
          to "bridged".
-       returns: task object
+       returns: VApp object
        throws:
         'CloudError' when invalid fence mode is specified
         'ObjectNotFoundError' when network with the name does not exist
@@ -315,7 +398,7 @@ Copyright (c) VMware, Inc.
      delete_network_by_name
        parameters:
          name (String): name of network to delete
-       returns: nil
+       returns: VApp object
        throws:
          'ObjectNotFoundError' when network with the name does not exist
          'RestClient::BadRequest' for un-expected errors
@@ -351,8 +434,8 @@ Copyright (c) VMware, Inc.
           'CloudError' when the memory size is less than or equal to 0
           'RestClient::BadRequest' for un-expected errors
 
-    list_networks
-      returns: array of network names
+    nics
+      returns: array of NIC objects
       throws:
         'RestClient::BadRequest' for un-expected errors
 
@@ -367,46 +450,50 @@ Copyright (c) VMware, Inc.
          'RestClient::BadRequest' for un-expected errors
 
      attach_disk
-       returns: task object
+       parameters:
+         disk: The disk object.
+       returns: VM object
        throws:
          'CloudError' if disk is already attached
          'RestClient::BadRequest' for un-expected errors
 
      detach_disk
-       returns: task object
+       parameters:
+         disk: The disk object.
+       returns: VM object
        throws:
          'VmSuspendedError' if containing vApp is suspended
          'CloudError' if disk is not attached or attached to other VM
          'RestClient::BadRequest' for un-expected errors
 
-     status
-       returns: string object
-       throws:
-         'CloudError' if status code is invalid
-         'RestClient::BadRequest' for un-expected errors
-
      power_on
-       returns: task object
+       returns: VM object
        throws:
          'CloudError' if power_on_link of VM is missing
          'RestClient::BadRequest' for un-expected errors
 
      power_off
-       returns: task object
+       returns: VM object
        throws:
          'CloudError' if power_off_link of VM is missing
          'VmSuspendedError' if VM is suspended
          'RestClient::BadRequest' for un-expected errors
 
      insert_media
-       returns: task object
+       parameters:
+         catalog_name (String): name of catalog
+         media_file_name (String): name of media file
+       returns: VM object
        throws:
          'ObjectNotFoundError' if when catalog with the name does not exist
          'ObjectNotFoundError' if when media with the name does not exist
          'RestClient::BadRequest' for un-expected errors
 
      eject_media
-       returns: task object
+       parameters:
+         catalog_name (String): name of catalog
+         media_file_name (String): name of media file
+       returns: VM object
        throws:
          'ObjectNotFoundError' if when catalog with the name does not exist
          'ObjectNotFoundError' if when media with the name does not exist
@@ -418,7 +505,7 @@ Copyright (c) VMware, Inc.
           ip_addressing_mode (String, optional): available options are "NONE", "MANUAL",
           "POOL" and "DHCP". Default to "POOL"
           ip (String, optional): IP address for "MANUAL" IP Mode
-        return: task object
+        return: VM object
         throws:
           'CloudError' if when ip_addressing_mode is invalid
           'CloudError' if ip is not specified in "MANUAL" ip_addressing_mode
@@ -426,6 +513,15 @@ Copyright (c) VMware, Inc.
           'ObjectNotFoundError' if network is not added to VM's parent VApp
           'RestClient::BadRequest' for un-expected errors
 
+    delete_nics
+       parameters:
+         nics (splat NIC objects): NICs to delete
+       return: VM object
+       throws:
+         'CloudError' if vm is powered on
+         'ObjectNotFoundError' if specified nic index does not exist
+         'RestClient::BadRequest' for un-expected errors
+
      product_section_properties
         returns:
           array of hash values representing properties of product section of VM
@@ -452,13 +548,21 @@ Copyright (c) VMware, Inc.
          capcity (Integer): disk size in megabyte
          bus_type (String, optional): bus type of disk, defaults to "scsi"
          bus_sub_type (String, optional): bus sub type of disk, defaults to "lsilogic"
-       returns: InternalDisk object created
+       returns: VM object
        throws:
          'CloudError' when capcity is less than or equal to 0
          'CloudError' when bus_type is invalid
          'CloudError' when bus_sub_type is invalid
          'RestClient::BadRequest' for un-expected errors
 
+     delete_internal_disk_by_name
+       parameters:
+         name (String): name of disk
+       returns: VM object
+       throws:
+         'ObjectNotFoundError' if no disk matching the given name
+         'RestClient::BadRequest' for un-expected errors
+
   VdcStorageProfile
   
      available_storage
@@ -472,4 +576,22 @@ Copyright (c) VMware, Inc.
        returns: IpRanges object
        throws:
          'RestClient::BadRequest' for un-expected errors
-  
+
+
+## Example
+  VCloud_SDK is straightforward to use. Here is an example of creating vApp from vApp template.
+  
+    1. Create vCloud client object
+        
+       client = VCloudSdk::Client.new(url, username, password)
+
+       Note that the parameter 'username' should be the VDC user_name@organization_name. For example,
+	   the VDC user name is admin, the organization name is myorg, then the 'username' parameter 
+       here should be admin@myorg. 
+	    
+    2. Find the catalog where the vapp template is stored
+       catalog = client.find_catalog_by_name(catalog_name)
+
+    3. Create vApp from that vapp template
+	   vapp = instantiate_vapp_template(vapp_template_name, vdc_name, vapp_name)
+       

data/lib/ruby_vcloud_sdk/catalog.rb

@@ -57,7 +57,7 @@ module VCloudSdk
 
       check_item_type(item, item_type)
       delete_item_by_link(link)
-      nil
+      self
     end
 
     def delete_all_items
@@ -65,7 +65,7 @@ module VCloudSdk
         Config.logger.info "Deleting catalog item \"#{link.name}\""
         delete_item_by_link(link)
       end
-      nil
+      self
     end
 
     def upload_media(
@@ -137,10 +137,10 @@ module VCloudSdk
     end
 
     def instantiate_vapp_template(template_name, vdc_name, vapp_name,
-        description = nil, disk_locality = nil)
+        description = nil, disk_locality = nil, network_config = nil)
 
       instantiate_vapp_params = create_instantiate_vapp_params(
-          template_name, vapp_name, description, disk_locality)
+          template_name, vapp_name, description, disk_locality, network_config)
 
       vdc = find_vdc_by_name vdc_name
 
@@ -179,7 +179,7 @@ module VCloudSdk
       entity_xml = connection.get(link)
       delete_item_entity entity_xml.entity
 
-      connection.delete(entity_xml.remove_link)
+      connection.delete(entity_xml.remove_link.href)
     end
 
     def delete_item_entity(entity)
@@ -330,7 +330,7 @@ module VCloudSdk
     end
 
     def create_instantiate_vapp_params(template_name,
-        vapp_name, description, disk_locality)
+        vapp_name, description, disk_locality, network_config)
 
       source_vapp_template = retrieve_vapp_template_xml_node(template_name)
 
@@ -338,6 +338,9 @@ module VCloudSdk
           "InstantiateVAppTemplateParams")
       instantiate_vapp_params.name = vapp_name
       instantiate_vapp_params.description = description
+
+      set_vapp_network_config_param(instantiate_vapp_params, network_config)
+
       instantiate_vapp_params.source = source_vapp_template
       instantiate_vapp_params.all_eulas_accepted = true
       instantiate_vapp_params.linked_clone = false
@@ -378,5 +381,19 @@ module VCloudSdk
       connection.put_file(incomplete_file.upload_link, media_file)
       connection.get(media)
     end
+
+    private
+
+    def set_vapp_network_config_param(instantiate_vapp_params, network_config)
+      return unless network_config
+
+      network = find_network_by_name(network_config.network_name)
+      target_vapp_net_name = network_config.vapp_net_name.nil? ?
+                             network.name : network_config.vapp_net_name
+
+      instantiate_vapp_params.set_network_config(target_vapp_net_name,
+                                                 network.href["href"].to_s,
+                                                 network_config.fence_mode.to_s)
+    end
   end
 end

data/lib/ruby_vcloud_sdk/client.rb

@@ -12,7 +12,8 @@ module VCloudSdk
     VCLOUD_VERSION_NUMBER = "5.1"
 
     public :find_vdc_by_name, :catalogs, :list_catalogs,
-           :catalog_exists?, :find_catalog_by_name
+           :catalog_exists?, :find_catalog_by_name,
+           :vdc_exists?
 
     def initialize(url, username, password, options = {}, logger = nil)
       @url = url
@@ -36,7 +37,7 @@ module VCloudSdk
       catalog = find_catalog_by_name(name)
       catalog.delete_all_items
       connection.delete("/api/admin/catalog/#{catalog.id}")
-      nil
+      self
     end
 
     def right_records

data/lib/ruby_vcloud_sdk/infrastructure.rb

@@ -14,6 +14,12 @@ module VCloudSdk
       VCloudSdk::VDC.new(@session, vdc_link)
     end
 
+    def vdc_exists?(name)
+      @session.org.vdcs.any? do |vdc|
+        vdc.name == name
+      end
+    end
+
     def find_network_by_name(name)
       @session.org.networks.each do |network_link|
         if network_link.name == name
@@ -24,6 +30,12 @@ module VCloudSdk
       fail ObjectNotFoundError, "Network '#{name}' is not found"
     end
 
+    def network_exists?(name)
+      @session.org.networks.any? do |network|
+        network.name == name
+      end
+    end
+
     def catalogs
       @session.org.catalogs.map do |catalog_link|
         VCloudSdk::Catalog.new(@session, catalog_link)

data/lib/ruby_vcloud_sdk/internal_disk.rb

@@ -1,9 +1,10 @@
 module VCloudSdk
 
   class InternalDisk
-    attr_reader :capacity, :bus_type, :bus_sub_type
+    attr_reader :name, :capacity, :bus_type, :bus_sub_type
 
     def initialize(entity_xml)
+      @name = entity_xml.element_name
       @capacity = entity_xml.host_resource.attribute("capacity").to_s.to_i
       @bus_type = entity_xml.host_resource.attribute("busType").to_s
       @bus_sub_type = entity_xml.host_resource.attribute("busSubType").to_s

data/lib/ruby_vcloud_sdk/network_config.rb

@@ -0,0 +1,16 @@
+module VCloudSdk
+
+  class NetworkConfig
+    attr_reader :network_name, :vapp_net_name, :fence_mode
+
+    def initialize(
+        network_name,
+        vapp_net_name = nil,
+        fence_mode = Xml::FENCE_MODES[:BRIDGED])
+      @network_name = network_name
+      @vapp_net_name = vapp_net_name
+      @fence_mode = fence_mode
+    end
+  end
+
+end

data/lib/ruby_vcloud_sdk/nic.rb

@@ -0,0 +1,26 @@
+module VCloudSdk
+  class NIC
+    extend Forwardable
+
+    def_delegators :@entity_xml,
+                   :ip_address, :is_connected, :mac_address,
+                   :ip_address_allocation_mode, :network
+
+    attr_reader :is_primary
+
+    def initialize(entity_xml, is_primary)
+      @entity_xml = entity_xml
+      @is_primary = is_primary
+    end
+
+    def network_connection_index
+      @entity_xml.network_connection_index.to_i
+    end
+
+    def is_connected
+      @entity_xml.is_connected == "true"
+    end
+
+    alias_method :nic_index, :network_connection_index
+  end
+end

data/lib/ruby_vcloud_sdk/powerable.rb

@@ -28,10 +28,10 @@ module VCloudSdk
       end
 
       Config.logger.info "Powering on #{class_name} #{target.name}."
-      task = connection.post(power_on_link, nil)
+      task = connection.post(power_on_link.href, nil)
       task = monitor_task task, @session.time_limit[:power_on]
       Config.logger.info "#{class_name} #{target.name} is powered on."
-      task
+      self
     end
 
     # Power off VApp or VM
@@ -54,11 +54,12 @@ module VCloudSdk
         fail CloudError, "#{class_name} #{target.name} is not in a state that could be powered off."
       end
 
-      task = connection.post(power_off_link, nil)
+      task = connection.post(power_off_link.href, nil)
       monitor_task task, @session.time_limit[:power_off]
       Config.logger.info "#{class_name} #{target.name} is powered off."
 
       undeploy(target, class_name)
+      self
     end
 
     private
@@ -69,7 +70,7 @@ module VCloudSdk
 
     def undeploy(target, class_name)
       params = Xml::WrapperFactory.create_instance("UndeployVAppParams") # Even for VM it's called UndeployVappParams
-      task = connection.post(target.undeploy_link, params)
+      task = connection.post(target.undeploy_link.href, params)
       task = monitor_task(task, @session.time_limit[:undeploy])
       Config.logger.info "#{class_name} #{target.name} is undeployed."
       task