softlayer_api 2.0.1 → 2.1.0

data/lib/softlayer/VirtualServerOrder.rb

@@ -0,0 +1,263 @@
+#
+# Copyright (c) 2014 SoftLayer Technologies, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+module SoftLayer
+  #
+  # VirtualServerOrder orders virtual servers using SoftLayer_Virtual_Guest::createObject.
+  #
+  # http://sldn.softlayer.com/reference/services/SoftLayer_Virtual_Guest/createObject
+  #
+  # +createObject+ allows you to order a virtual server by providing
+  # a simple set of attributes and allows you to avoid much of the
+  # complexity of the SoftLayer ordering system (see ProductPackage)
+  #
+  class VirtualServerOrder
+    #--
+    # Required Attributes
+    # -------------------
+    # The following attributes are required in order to successfully order
+    # a virtual server
+    #++
+
+    # String, short name of the data center that will house the new virtual server (e.g. "dal05" or "sea01")
+    # Corresponds to +datacenter.name+ in the documentation for createObject.  If not provided, the server will
+    # be provisioned in the first available data center.
+    attr_accessor :datacenter
+
+    # String, The hostname to assign to the new server
+    attr_accessor :hostname
+
+    # String, The domain (i.e. softlayer.com) for the new server
+    attr_accessor :domain
+
+    # Integer, The number of virtual CPU cores to include in the instance
+    # Corresponds to +startCpus+ in the documentation for +createObject+
+    attr_accessor :cores
+
+    # Integer, The amount of RAM for the new server (specified in Gigabytes so a value of 4 is 4GB)
+    # Corresponds to +maxMemory+ in the documentation for +createObject+
+    attr_accessor :memory
+
+    #--
+    # These two options are mutually exclusive, but one or the other must be provided.
+    # If you provide both, the image_global_id will be added to the order and the os_reference_code will be ignored
+    #++
+
+    # String, An OS reference code for the operating system to install on the virtual server
+    # Corresponds to +operatingSystemReferenceCode+ in the +createObject+ documentation
+    attr_accessor :os_reference_code
+
+    # String, The globalIdentifier of a disk image to put on the newly created server
+    # Corresponds to +blockDeviceTemplateGroup.globalIdentifier+ in the +createObject+ documentation
+    attr_accessor :image_global_id
+
+    #--
+    # Optional attributes
+    #++
+
+    # Boolean, If true, the virtual server will reside only on hosts with instances from this same account
+    # Corresponds to +dedicatedAccountHostOnlyFlag+ in the +createObject+ documentation
+    attr_accessor :dedicated_host_only
+
+    # Array of Integer, Sizes (in gigabytes... so use 25 to get a 25GB disk) of disks to attach to this server
+    # This roughly Corresponds to +blockDevices+ field in the +createObject+ documentation.
+    # This attribute only allows you to configure the size of disks while +blockDevices+ allows
+    # more configuration options
+    attr_accessor :disks
+
+    # Boolean, If true, an hourly server will be ordered, otherwise a monthly server will be ordered
+    # Corresponds to +hourlyBillingFlag+ in the +createObject+ documentation
+    attr_accessor :hourly
+
+    # Integer, The maximum network interface card speed (in Mbps) for the new instance
+    # Corresponds to +networkComponents.maxSpeed+ in the +createObject+ documentation
+    attr_accessor :max_port_speed
+
+    # Boolean, If true then the virtual server will only have a private network interface (and no public network interface)
+    # Corresponds to +userData.value+ in the +createObject+ documentation
+    attr_accessor :private_network_only
+
+    # Integer, The id of the private VLAN this server should join
+    # Corresponds to +primaryBackendNetworkComponent.networkVlan.id+ in the +createObject+ documentation
+    attr_accessor :private_vlan_id
+
+    # String, The URI of a post provisioning script to run on this server once it is created
+    attr_accessor :provision_script_URI
+
+    # Integer, The id of the public VLAN this server should join
+    # Corresponds to +primaryNetworkComponent.networkVlan.id+ in the +createObject+ documentation
+    attr_accessor :public_vlan_id
+
+    # Array of Strings, SSH keys to add to the root user's account.
+    # Corresponds to +sshKeys+ in the +createObject+ documentation
+    attr_accessor :ssh_key_ids
+
+    # Boolean, If true the server will use a virtual hard drive, if false, data will be stored on a SAN disk
+    # Corresponds to +localDiskFlag+ in the +createObject+ documentation
+    attr_accessor :use_local_disk
+
+    # String, User metadata associated with the instance
+    # Corresponds to +primaryBackendNetworkComponent.networkVlan.id+ in the +createObject+ documentation
+    attr_accessor :user_metadata
+
+    # Create a new order that works thorugh the given client connection
+    def initialize (client = nil)
+      @softlayer_client = client || Client.default_client
+      raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !@softlayer_client
+    end
+
+    # Calls the SoftLayer API to verify that the template provided by this order is valid
+    # This routine will return the order template generated by the API or will throw an exception
+    #
+    # This routine will not actually create a Virtual Server and will not affect billing.
+    #
+    # If you provide a block, it will receive the order template as a parameter and it
+    # should return the order template you wish to forward to the server.
+    def verify()
+      order_template = virtual_guest_template
+      order_template = yield order_template if block_given?
+
+      @softlayer_client["Virtual_Guest"].generateOrderTemplate(order_template)
+    end
+
+    # Calls the SoftLayer API to place an order for a new virtual server based on the template in this
+    # order. If this succeeds then you will be billed for the new Virtual Server.
+    #
+    # If you provide a block, it will receive the order template as a parameter and
+    # should return an order template, **carefully** modified, that will be
+    # sent to create the server
+    def place_order!()
+      order_template = virtual_guest_template
+      order_template = yield order_template if block_given?
+
+      virtual_server_hash = @softlayer_client["Virtual_Guest"].createObject(order_template)
+      SoftLayer::VirtualServer.server_with_id(virtual_server_hash["id"], :client => @softlayer_client) if virtual_server_hash
+    end
+
+    protected
+
+    # Returns a hash of the creation options formatted to be sent to
+    # the SoftLayer API for either verification or completion
+    def virtual_guest_template
+      template = {
+        "startCpus" => @cores.to_i,
+        "maxMemory" => @memory.to_i * 1024,  # we let the user specify memory in GB, but the API expects maxMemory in MB.
+        "hostname" => @hostname,
+        "domain" => @domain,
+
+        # Note : for the values below, we want to use the constants "true" and "false" not nil
+        # the nil value (while false to Ruby) will not translate to XML properly
+        "localDiskFlag" => !!@use_local_disk,
+        "hourlyBillingFlag" => !!@hourly
+      }
+
+      template["dedicatedAccountHostOnlyFlag"] = true if @dedicated_host_only
+      template["privateNetworkOnlyFlag"] = true if @private_network_only
+
+      template["datacenter"] = {"name" => @datacenter} if @datacenter
+      template['userData'] = [{'value' => @user_metadata}] if @user_metadata
+      template['networkComponents'] = [{'maxSpeed'=> @max_port_speed}] if @max_port_speed
+      template['postInstallScriptUri'] = @provision_script_URI.to_s if @provision_script_URI
+      template['sshKeys'] = @ssh_key_ids.collect { |ssh_key_id| {'id'=> ssh_key_id.to_i } } if @ssh_key_ids
+      template['primaryNetworkComponent'] = { "networkVlan" => { "id" => @public_vlan_id.to_i } } if @public_vlan_id
+      template["primaryBackendNetworkComponent"] = { "networkVlan" => {"id" => @private_vlan_id.to_i } } if @private_vlan_id
+
+      if @image_global_id
+          template["blockDeviceTemplateGroup"] = {"globalIdentifier" => @image_global_id}
+      elsif @os_reference_code
+          template["operatingSystemReferenceCode"] = @os_reference_code
+      end
+
+      if @disks && !@disks.empty?
+        template['blockDevices'] = []
+
+        # According to the documentation for +createObject+,
+        # device number 1 is reserved for the SWAP disk of the computing instance.
+        # So we assign device 0 and then assign the rest starting at index 2.
+        @disks.each_with_index do |disk, index|
+          device_id = (index >= 1) ? index + 1 : index
+          template['blockDevices'].push({"device" => "#{device_id}", "diskImage" => {"capacity" => disk}})
+        end
+      end
+
+      template
+    end
+
+    ##
+    # The first time this is called it requests SoftLayer_Virtual_Guest::getCreateObjectOptions:
+    # from the API and remembers the result. On subsequent calls it returns the remembered result.
+    #
+    # http://sldn.softlayer.com/reference/services/SoftLayer_Virtual_Guest/getCreateObjectOptions
+    #
+    def self.create_object_options(client = nil)
+      softlayer_client = client || Client.default_client
+      raise "#{__method__} requires a client but none was given and Client::default_client is not set" if !softlayer_client
+
+      @@create_object_options ||= nil
+      @@create_object_options = softlayer_client["Virtual_Guest"].getCreateObjectOptions() if !@@create_object_options
+      @@create_object_options
+    end
+
+    #--
+    # The following routines offer a way to query the SoftLayer API for values that are
+    # valid in some of the fields of a Virtual Server order.  While the individual values
+    # returned are all valid, it is still possible to create combinations of values which
+    # the ordering system cannot accept.
+    #++
+
+    ##
+    # Return a list of values that are valid for the :datacenter attribute
+    def self.datacenter_options(client = nil)
+      create_object_options(client)["datacenters"].collect { |datacenter_spec| datacenter_spec['template']['datacenter']["name"] }.uniq.sort!
+    end
+
+    ##
+    # Return a list of values that are valid for the :cores attribute
+    def self.core_options(client = nil)
+      create_object_options(client)["processors"].collect { |processor_spec| processor_spec['template']['startCpus'] }.uniq.sort!
+    end
+
+    ##
+    # Return a list of values that are valid for the :memory attribute
+    def self.memory_options(client = nil)
+      create_object_options(client)["memory"].collect { |memory_spec| memory_spec['template']['maxMemory'].to_i / 1024}.uniq.sort!
+    end
+
+    ##
+    # Return a list of values that are valid the array given to the :disks
+    def self.disk_options(client = nil)
+      create_object_options(client)["blockDevices"].collect { |block_device_spec| block_device_spec['template']['blockDevices'][0]['diskImage']['capacity']}.uniq.sort!
+    end
+
+    ##
+    # Returns a list of the valid :os_refrence_codes
+    def self.os_reference_code_options(client = nil)
+      create_object_options(client)["operatingSystems"].collect { |os_spec| os_spec['template']['operatingSystemReferenceCode'] }.uniq.sort!
+    end
+
+    ##
+    # Returns a list of the :max_port_speeds
+    def self.max_port_speed_options(client = nil)
+      create_object_options(client)["networkComponents"].collect { |component_spec| component_spec['template']['networkComponents'][0]['maxSpeed'] }
+    end
+  end # class VirtualServerOrder
+end # module SoftLayer

data/lib/softlayer/base.rb

@@ -22,16 +22,16 @@
 
 require 'rubygems'
 
-# This module is used to provide a namespace for SoftLayer code.  It also declares a number of
+# This module is used to provide a namespace for SoftLayer code. It also declares a number of
 # global variables:
-# - <tt>$SL_API_USERNAME</tt> - The default username passed by clients to the server for authentication.
+# - +$SL_API_USERNAME+ - The default username passed by clients to the server for authentication.
 #   Set this if you want to use the same username for all clients and don't want to have to specify it when the client is created
-# - <tt>$SL_API_KEY</tt> - The default API key passed by clients to the server for authentication.
+# - +$SL_API_KEY+ - The default API key passed by clients to the server for authentication.
 #   Set this if you want to use the same api for all clients and don't want to have to specify it when the client is created
-# - <tt>$SL_API_BASE_URL</tt>- The default URL used to access the SoftLayer API. This defaults to the value of <tt>SoftLayer::API_PUBLIC_ENDPOINT</tt>
+# - +$SL_API_BASE_URL+- The default URL used to access the SoftLayer API. This defaults to the value of +SoftLayer::API_PUBLIC_ENDPOINT+
 #
 module SoftLayer
-  VERSION = "2.0.1"  # version history in the CHANGELOG.textile file at the root of the source
+  VERSION = "2.1.0"  # version history in the CHANGELOG.textile file at the root of the source
 
   # The base URL of the SoftLayer API's REST-like endpoints available to the public internet.
   API_PUBLIC_ENDPOINT = 'https://api.softlayer.com/xmlrpc/v3/'
@@ -43,12 +43,12 @@ module SoftLayer
   # These globals can be used to simplify client creation
   #
 
-  # Set this if you want to provide a default username for each service as it is created.
-  # usernames provided to the service initializer will override the global
+  # Set this if you want to provide a default username for each client as it is created.
+  # usernames provided to the client initializer will override the global
   $SL_API_USERNAME = nil
 
-  # Set this if you want to provide a default api_key for each service as it is
-  # created. API keys provided in the constructor when a service is created will
+  # Set this if you want to provide a default api_key for each client as it is
+  # created. API keys provided in the constructor when a client is created will
   # override the values in this global
   $SL_API_KEY = nil
 

data/lib/softlayer/object_mask_helpers.rb

@@ -20,12 +20,17 @@
 # THE SOFTWARE.
 #
 
-# Ruby Hash Class
+##
+# This extension to the Hash class to allows object masks to be constructed
+# from built-in Ruby types and converted to object masks strings for presentation
+# to the SoftLayer API
 class Hash
-  def __valid_root_property_key?(key_string)
-    return key_string == "mask" || (0 == (key_string =~ /\Amask\([a-z][a-z0-9_]*\)\z/i))
-  end
-
+  # Given a hash, generate an Object Mask string from the structure
+  # found within the hash. This allows object masks to be constructed
+  # as hashes, then converted to strings when they must be passed
+  # to the API. The routine does some very rudimentary validation to
+  # ensure that the hash represents a valid object mask, but care must
+  # still be taken when constructing the hash.
   def to_sl_object_mask()
     raise RuntimeError, "An object mask must contain properties" if empty?
     raise RuntimeError, "An object mask must start with root properties" if keys().find { |key| !__valid_root_property_key?(key) }
@@ -34,25 +39,34 @@ class Hash
     key_strings.count > 1 ? "[#{key_strings.join(',')}]" : "#{key_strings[0]}"
   end
 
-  def to_sl_object_mask_property()
+  # Returns a string representing the hash as a property within a larger
+  # object mask. This routine is an implementation detail used in the conversion
+  # of hashes to object mask strings. You should not have to call this method directly.
+  def _to_sl_object_mask_property()
     key_strings = __sl_object_mask_properties_for_keys();
     "#{key_strings.join(',')}"
   end
 
+  private
+
+  def __valid_root_property_key?(key_string)
+    return key_string == "mask" || (0 == (key_string =~ /\Amask\([a-z][a-z0-9_]*\)\z/i))
+  end
+
   def __sl_object_mask_properties_for_keys
     key_strings = [];
 
     each do |key, value|
       return "" if !value
 
-      string_for_key = key.to_sl_object_mask_property
+      string_for_key = key._to_sl_object_mask_property
 
       if value.kind_of?(String) || value.kind_of?(Symbol) then
-        string_for_key = "#{string_for_key}.#{value.to_sl_object_mask_property}"
+        string_for_key = "#{string_for_key}.#{value._to_sl_object_mask_property}"
       end
 
       if value.kind_of?(Array) || value.kind_of?(Hash) then
-        value_string = value.to_sl_object_mask_property
+        value_string = value._to_sl_object_mask_property
         if value_string && !value_string.empty?
           string_for_key = "#{string_for_key}[#{value_string}]"
         end
@@ -65,30 +79,44 @@ class Hash
   end
 end
 
-# Ruby Array Class
+##
+# SoftLayer Extensions to the Array class to support using arrays to create
+# object masks
 class Array
   # Returns a string representing the object mask content represented by the
   # Array. Each value in the array is converted to its object mask eqivalent
-  def to_sl_object_mask_property()
+  # This routine is an implementation detail used in the conversion of hashes
+  # to object mask strings. You should not have to call this method directly.
+  def _to_sl_object_mask_property()
     return "" if self.empty?
-    property_content = map { |item| item.to_sl_object_mask_property() }.flatten.join(",")
+    property_content = map { |item| item ? item._to_sl_object_mask_property() : nil  }.compact.flatten.join(",")
     "#{property_content}"
   end
 end
 
-# Ruby String Class
+##
+# SoftLayer Extensions to the String class to support using strings to create
+# object masks
 class String
   # Returns a string representing the object mask content represented by the
-  # String. Strings are simply represented as copies of themselves.  We make
+  # String. Strings are simply represented as copies of themselves. We make
   # a copy in case the original String is modified somewhere along the way
-  def to_sl_object_mask_property()
+  # This routine is an implementation detail used in the conversion of hashes
+  # to object mask strings. You should not have to call this method directly.
+  def _to_sl_object_mask_property()
     return self.strip
   end
 end
 
-# Ruby Symbol Class
+##
+# SoftLayer Extensions to the Symbol class to support using symbols to create
+# object masks
 class Symbol
-  def to_sl_object_mask()
-    self.to_s.to_sl_object_mask()
+  # Converts the Symbol to a string, then converts the string to an
+  # object mask property. This routine is an implementation detail used in
+  # the conversion of hashes to object mask strings. You should not have to
+  # call this method directly.
+  def _to_sl_object_mask_property()
+    self.to_s._to_sl_object_mask_property()
   end
 end

data/lib/softlayer_api.rb

@@ -24,7 +24,22 @@ require 'softlayer/base'
 require 'softlayer/object_mask_helpers'
 require 'softlayer/APIParameterFilter'
 require 'softlayer/ObjectFilter'
+require 'softlayer/ObjectMaskParser'
 require 'softlayer/Config'
 
 require 'softlayer/Client'
 require 'softlayer/Service'
+
+# model classes
+require 'softlayer/ModelBase'
+require 'softlayer/DynamicAttribute'
+require 'softlayer/Account'
+require 'softlayer/Ticket'
+require 'softlayer/Server'
+require 'softlayer/BareMetalServer'
+require 'softlayer/BareMetalServerOrder'
+require 'softlayer/BareMetalServerOrder_Package'
+require 'softlayer/ProductPackage'
+require 'softlayer/ProductItemCategory'
+require 'softlayer/VirtualServer'
+require 'softlayer/VirtualServerOrder'

metadata

@@ -1,75 +1,89 @@
 --- !ruby/object:Gem::Specification
 name: softlayer_api
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - SoftLayer Development Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-27 00:00:00.000000000 Z
+date: 2014-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configparser
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.2
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.8.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.8.1
 description: The softlayer_api gem offers a convenient mechanism for invoking the
@@ -79,17 +93,37 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.textile
 - LICENSE.textile
 - README.textile
 - examples/account_info.rb
+- examples/account_servers.rb
 - examples/create_ticket.rb
 - examples/open_tickets.rb
+- examples/order_bare_metal_package.rb
+- examples/order_virtual_server.rb
 - examples/ticket_info.rb
 - lib/softlayer/APIParameterFilter.rb
+- lib/softlayer/Account.rb
+- lib/softlayer/BareMetalServer.rb
+- lib/softlayer/BareMetalServerOrder.rb
+- lib/softlayer/BareMetalServerOrder_Package.rb
 - lib/softlayer/Client.rb
 - lib/softlayer/Config.rb
+- lib/softlayer/DynamicAttribute.rb
+- lib/softlayer/ModelBase.rb
 - lib/softlayer/ObjectFilter.rb
+- lib/softlayer/ObjectMaskParser.rb
+- lib/softlayer/ObjectMaskProperty.rb
+- lib/softlayer/ObjectMaskToken.rb
+- lib/softlayer/ObjectMaskTokenizer.rb
+- lib/softlayer/ProductItemCategory.rb
+- lib/softlayer/ProductPackage.rb
+- lib/softlayer/Server.rb
 - lib/softlayer/Service.rb
+- lib/softlayer/Ticket.rb
+- lib/softlayer/VirtualServer.rb
+- lib/softlayer/VirtualServerOrder.rb
 - lib/softlayer/base.rb
 - lib/softlayer/object_mask_helpers.rb
 - lib/softlayer_api.rb
@@ -103,12 +137,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []