softlayer_api 2.0.1 → 2.1.0

data/lib/softlayer/BareMetalServerOrder.rb

@@ -0,0 +1,227 @@
+#
+# 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
+  #
+  # This class allows you to order a Bare Metal Server by providing
+  # a simple set of attributes for the newly created server. The
+  # SoftLayer system will select a server that matches the attributes
+  # provided and provision it or will report an error.
+  #
+  # If you wish to have more exacting control over the set of options
+  # that go into configuring the server, please see the
+  # BareMetalServerOrder_Package class.
+  #
+  # This class creates the server with the SoftLayer_Hardware::createObject
+  # method.
+  #
+  # http://sldn.softlayer.com/reference/services/SoftLayer_Hardware/createObject
+  #
+  # Reading that documentation may help you understand the options presented here.
+  #
+  class BareMetalServerOrder
+    #--
+    # Required Attributes
+    # -------------------
+    # The following attributes are required in order to successfully order
+    # a Bare Metal Instance
+    #++
+
+    # String, short name of the data center that will house the new Bare Metal Instance (e.g. "dal05" or "sea01")
+    # Corresponds to +datacenter.name+ in the documentation for +createObject+.
+    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 cpu cores to include in the instance
+    # Corresponds to +processorCoreAmount+ 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 +memoryCapacity+ in the documentation for +createObject+
+    attr_accessor :memory
+
+    # String, An OS reference code for the operating system to install on the server
+    # Corresponds to +operatingSystemReferenceCode+ in the +createObject+ documentation
+    attr_accessor :os_reference_code
+
+    #--
+    # Optional attributes
+    #++
+
+    # 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 id of the public VLAN this server should join
+    # Corresponds to +primaryNetworkComponent.networkVlan.id+ in the +createObject+ documentation
+    attr_accessor :public_vlan_id
+
+    # 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
+
+    # 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 +hardDrives+ field in the +createObject+ documentation.
+    attr_accessor :disks
+
+    # 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
+
+    # Object responding to to_s and providing a valid URI, The URI of a post provisioning script to run on
+    # this server once it is created.
+    # Corresponds to +postInstallScriptUri+ in the +createObject+ documentation
+    attr_accessor :provision_script_URI
+
+    # Boolean, If true then the server will only have a private network interface (and no public network interface)
+    # Corresponds to +privateNetworkOnlyFlag+ in the +createObject+ documentation
+    attr_accessor :private_network_only
+
+    # String, User metadata associated with the instance
+    # Corresponds to +userData.value+ in the +createObject+ documentation
+    attr_accessor :user_metadata
+
+    # Integer (Should be 10, 100, or 1000), 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
+
+    ##
+    # 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 Bare Metal Instance and will not affect billing.
+    #
+    # If you provide a block, it will receive the order template as a parameter and
+    # the block may make changes to the template before it is submitted.
+    def verify()
+      order_template = hardware_instance_template
+      order_template = yield order_template if block_given?
+
+      @softlayer_client["Hardware"].generateOrderTemplate(order_template)
+    end
+
+    ##
+    # Calls the SoftLayer API to place an order for a new server based on the template in this
+    # order. If this succeeds then you will be billed for the new server.
+    #
+    # If you provide a block, it will receive the order template as a parameter and
+    # the block may make changes to the template before it is submitted.
+    def place_order!()
+      order_template = hardware_instance_template
+      order_template = yield order_template if block_given?
+
+      server_hash = @softlayer_client["Hardware"].createObject(order_template)
+      SoftLayer::BareMetalServer.server_with_id(server_hash["id"], :client => @softlayer_client) if 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 hardware_instance_template
+      template = {
+        "processorCoreAmount" => @cores.to_i,
+        "memoryCapacity" => @memory.to_i,
+        "hostname" => @hostname,
+        "domain" => @domain,
+        "operatingSystemReferenceCode" => @os_reference_code,
+
+        # 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["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'=> ssh_key.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 @disks && !@disks.empty?
+        template['hardDrives'] = @disks.collect do |disk|
+          {"capacity" => disk.to_i}
+        end
+      end
+
+      template
+    end
+
+    ##
+    # The first time this is called it requests SoftLayer_Hardware::getCreateObjectOptions
+    # from the API and remembers the result. On subsequent calls it returns the remembered result.
+    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["Hardware"].getCreateObjectOptions() if !@@create_object_options
+      @@create_object_options
+    end
+
+    ##
+    # 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
+
+    def self.core_options(client = nil)
+      create_object_options(client)["processors"].collect { |processor_spec| processor_spec['template']['processorCoreAmount'] }.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)["hardDrives"].collect { |disk_spec| disk_spec['template']['hardDrives'][0]['capacity'].to_i}.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 BareMetalServerOrder
+end # module SoftLayer

data/lib/softlayer/BareMetalServerOrder_Package.rb

@@ -0,0 +1,162 @@
+#
+# 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
+  #
+  # This class is used to order a hardware server using a product package.
+  #
+  # Ordering a server using a product package is a more complex process than
+  # ordering with simple attributes (as is done by the BareMetalServerOrder class).
+  # However with that complexity comes the the ability to specify the configuration
+  # of the server in exacting detail.
+  #
+  # To use this class, you first select a product package. The product package
+  # defines the base configuration, the chassis, of the server as well as the set of configuration
+  # options available for that chassis. To fully configure the server you must select
+  # the value for each configuration option.
+  #
+  # This class roughly Corresponds to the SoftLayer_Container_Product_Order_Hardware_Server
+  # data type in the SoftLayer API
+  #
+  # http://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Product_Order_Hardware_Server
+  #
+  class BareMetalServerOrder_Package < Server
+    # The following properties are required in a server order.
+
+    # The product package identifying the base configuration for the server.
+    # a list of Bare Metal Server product packages is returned by
+    # SoftLayer::ProductPackage.bare_metal_server_packages
+    attr_reader :package
+
+    # String, short name of the data center that will house the new virtual server (e.g. "dal05" or "sea01")
+    # A list of valid data centers can be found in ProductPackage#datacenter_options
+    attr_accessor :datacenter
+
+    # The hostname of the server being created (i.e. 'sldn' is the hostname of sldn.softlayer.com).
+    attr_accessor :hostname
+
+    # The domain of the server being created (i.e. 'softlayer.com' is the domain of sldn.softlayer.com)
+    attr_accessor :domain
+
+    # The value of this property should be a hash. The keys of the hash are ProdcutItemCategory
+    # codes (like 'os' and 'ram') while the values may be Integers or Objects. The Integer values
+    # should be the +id+ of a +SoftLayer_Product_Item_Price+ representing the configuration option
+    # chosen for that category. Objects must respond to the +price_id+ message and return an integer
+    # that is the +id+ of a +SoftLayer_Product_Item_Price+. Instances of the ProductConfigurationOption
+    # class behave this way.
+    #
+    # At a minimum, the configuation_options should include entries for each of the categories
+    # required by the package (i.e. those returned from ProductPackage#required_categories)
+    attr_accessor :configuration_options
+
+    # The following properties are optional, but allow further fine tuning of
+    # the server
+
+    # An array of the ids of SSH keys to install on the server upon provisioning
+    # To obtain a list of existing SSH keys, call getSshKeys on the SoftLayer_Account service:
+    #     client['Account'].getSshKeys()
+    attr_accessor :ssh_key_ids
+
+    # The URI of a script to execute on the server after it has been provisioned. This may be
+    # any object which accepts the to_s message. The resulting string will be passed to SoftLayer API.
+    attr_accessor :provision_script_URI
+
+    ##
+    # You initialize a BareMetalServerOrder_Package by passing in the package that you
+    # are ordering from.
+    def initialize(package, 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
+
+      @package = package
+      @configuration_options = []
+    end
+
+    ##
+    # Present the order for verification by the SoftLayer ordering system.
+    # The order is verified, but not executed. This should not
+    # change the billing of your account.
+    #
+    # If you add a block to the method call, it will receive the product
+    # order template before it is sent to the API. You may **carefully** make
+    # changes to the template to provide specialized configuration.
+    #
+    def verify
+      product_order = hardware_order
+      product_order = yield product_order if block_given?
+      softlayer_client["Product_Order"].verifyOrder(product_order)
+    end
+
+    ##
+    # Submit the order to be executed by the SoftLayer ordering system.
+    # If successful this will probably result in additional billing items
+    # applied to your account!
+    #
+    # If you add a block to the method call, it will receive the product
+    # order template before it is sent to the API. You may **carefully** make
+    # changes to the template to provide specialized configuration.
+    #
+    # The return value of this call is a product order receipt. After
+    # submitting the order, it will proceed to Sales for authorization.
+    #
+    def place_order!
+      product_order = hardware_order
+      product_order = yield product_order if block_given?
+      softlayer_client["Product_Order"].placeOrder(product_order)
+    end
+
+    protected
+
+    ##
+    # Construct and return a hash representing a +SoftLayer_Container_Product_Order_Hardware_Server+
+    # based on the configuration options given.
+    def hardware_order
+      product_order = {
+        'packageId' => @package.id,
+        'useHourlyPricing' => false,
+        'hardware' => {
+          'hostname' => @hostname,
+          'domain' => @domain
+        }
+      }
+
+      product_order['location'] = @package.location_id_for_datacenter_name(@datacenter.downcase) if @datacenter
+
+      product_order['sshKeys'] = [{ 'sshKeyIds' => @ssh_key_ids }] if @ssh_key_ids
+      product_order['provisionScripts'] = [@provision_script_URI.to_s] if @provision_script_URI
+
+      product_order['prices'] = @configuration_options.collect do |key, value|
+        if value.respond_to?(:price_id)
+          price_id = value.price_id
+        else
+          price_id = value.to_i
+        end
+
+        { 'id' => price_id }
+      end
+
+      product_order
+    end
+
+  end # BareMetalServerOrder_Package
+
+end # SoftLayer

data/lib/softlayer/Client.rb

@@ -1,18 +1,40 @@
+#
+# 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
   # Initialize an instance of the Client class. You pass in the service name
   # and optionally hash arguments specifying how the client should access the
   # SoftLayer API.
   #
   # The following symbols can be used as hash arguments to pass options to the constructor:
-  # - <tt>:username</tt> - a non-empty string providing the username to use for requests to the service
-  # - <tt>:api_key</tt> - a non-empty string providing the api key to use for requests to the service
-  # - <tt>:endpoint_url</tt> - a non-empty string providing the endpoint URL to use for requests to the service
+  # - +:username+ - a non-empty string providing the username to use for requests to the client
+  # - +:api_key+ - a non-empty string providing the api key to use for requests to the client
+  # - +:endpoint_url+ - a non-empty string providing the endpoint URL to use for requests to the client
   #
   # If any of the options above are missing then the constructor will try to use the corresponding
   # global variable declared in the SoftLayer Module:
-  # - <tt>$SL_API_USERNAME</tt>
-  # - <tt>$SL_API_KEY</tt>
-  # - <tt>$SL_API_BASE_URL</tt>
+  # - +$SL_API_USERNAME+
+  # - +$SL_API_KEY+
+  # - +$SL_API_BASE_URL+
   #
   class Client
     # A username passed as authentication for each request. Cannot be emtpy or nil.
@@ -27,6 +49,30 @@ module SoftLayer
     # A string passsed as the value for the User-Agent header when requests are sent to SoftLayer API.
     attr_accessor :user_agent
 
+    ##
+    # The client class maintains an (optional) default client. The default client
+    # will be used by many methods if you do not provide an explicit client.
+    @@default_client = nil
+
+    def self.default_client
+      return @@default_client
+    end
+
+    def self.default_client=(new_default)
+      @@default_client = new_default
+    end
+
+    ##
+    #
+    # Clients are built with a number of settings:
+    # * <b>+:username+</b> - The username of the account you wish to access through the API
+    # * <b>+:api_key+</b> - The API key used to authenticate the user with the API
+    # * <b>+:enpoint_url+</b> - The API endpoint the client should connect to.  This defaults to API_PUBLIC_ENDPOINT
+    # * <b>+:user_agent+</b> - A string that is passed along as the user agent when the client sends requests to the server
+    #
+    # If these arguments are not provided then the client will try to locate them using other
+    # sources including global variables, and the SoftLayer config file (if one exists)
+    #
     def initialize(options = {})
       @services = { }
 
@@ -64,12 +110,11 @@ module SoftLayer
     # will be returned each time it is called for by name. Otherwise the system
     # will try to construct a new service object and return that.
     #
-    #
     # If the service has to be created then the service_options will be passed
-    # along to the creative function.  However, when returning a previously created
+    # along to the creative function. However, when returning a previously created
     # Service, the service_options will be ignored.
     #
-    # If the service_name provided does not start with 'SoftLayer__' that prefix
+    # If the service_name provided does not start with 'SoftLayer_' that prefix
     # will be added
     def service_named(service_name, service_options = {})
       raise ArgumentError,"Please provide a service name" if service_name.nil? || service_name.empty?