class CloudServers::Connection

Attributes

auth_host[R]
auth_port[R]
auth_scheme[R]
authkey[R]
authok[RW]
authtoken[RW]
authuser[R]
proxy_host[R]
proxy_port[R]
svrmgmthost[RW]
svrmgmtpath[RW]
svrmgmtport[RW]
svrmgmtscheme[RW]

Public Class Methods

new(options = {:retry_auth => true}) click to toggle source

Creates a new CloudServers::Connection object. Uses CloudServers::Authentication to perform the login for the connection.

Setting the retry_auth option to false will cause an exception to be thrown if your authorization token expires. Otherwise, it will attempt to reauthenticate.

This is useful if you are using the library on a Rackspace-hosted system, as it provides faster speeds, keeps traffic off of the public network, and the bandwidth is not billed.

This will likely be the base class for most operations.

The constructor takes a hash of options, including:

:username - Your Rackspace Cloud username *required*
:api_key - Your Rackspace Cloud API key *required*
:auth_url - Configurable auth_url endpoint.
:retry_auth - Whether to retry if your auth token expires (defaults to true)
:proxy_host - If you need to connect through a proxy, supply the hostname here
:proxy_port - If you need to connect through a proxy, supply the port here

cf = CloudServers::Connection.new(:username => 'YOUR_USERNAME', :api_key => 'YOUR_API_KEY')
# File lib/cloudservers/connection.rb, line 38
def initialize(options = {:retry_auth => true}) 
  @authuser = options[:username] || (raise Exception::Authentication, "Must supply a :username")
  @authkey = options[:api_key] || (raise Exception::Authentication, "Must supply an :api_key")
  @auth_url = options[:auth_url] || @auth_url = CloudServers::AUTH_USA

  auth_uri=nil
  begin
    auth_uri=URI.parse(@auth_url)
  rescue Exception => e
    raise Exception::InvalidArgument, "Invalid :auth_url parameter: #{e.message}"
  end
  raise Exception::InvalidArgument, "Invalid :auth_url parameter." if auth_uri.nil? or auth_uri.host.nil?
  @auth_host = auth_uri.host
  @auth_port = auth_uri.port
  @auth_scheme = auth_uri.scheme

  @retry_auth = options[:retry_auth]
  @proxy_host = options[:proxy_host]
  @proxy_port = options[:proxy_port]
  @authok = false
  @http = {}
  CloudServers::Authentication.new(self)
end

Public Instance Methods

authok?() click to toggle source

Returns true if the authentication was successful and returns false otherwise.

cs.authok?
=> true
# File lib/cloudservers/connection.rb, line 66
def authok?
  @authok
end
create_server(options) click to toggle source

Creates a new server instance on Cloud Servers

The argument is a hash of options. The keys :name, :flavorId, and :imageId are required, :metadata and :personality are optional.

:flavorId and :imageId are numbers identifying a particular server flavor and image to use when building the server. The :imageId can either be a stock Cloud Servers image, or one of your own created with the server.create_image method.

The :metadata argument will take a hash of up to five key/value pairs. This metadata will be applied to the server at the Cloud Servers API level.

The "Personality" option allows you to include up to five files, of 10Kb or less in size, that will be placed on the created server. For :personality, you may pass either

  1. a hash of the form {'local_path' => 'server_path'}. The file contents of the file located at local_path will be placed at the location identified by server_path on the new server.

  2. an array of items like {:path => "/path/on/server", :contents=>"contents of file on server"}

Returns a CloudServers::Server object. The root password is available in the adminPass instance method.

>> server = cs.create_server(:name => "New Server", :imageId => 2, :flavorId => 2, :metadata => {'Racker' => 'Fanatical'}, :personality => {'/Users/me/Pictures/wedding.jpg' => '/root/me.jpg'})
=> #<CloudServers::Server:0x101229eb0 ...>
>> server.name
=> "NewServer"
>> server.status
=> "BUILD"
>> server.adminPass
=> "NewServerSHMGpvI"
# File lib/cloudservers/connection.rb, line 168
def create_server(options)
  raise CloudServers::Exception::MissingArgument, "Server name, flavor ID, and image ID must be supplied" unless (options[:name] && options[:flavorId] && options[:imageId])
  options[:personality] = get_personality(options[:personality])
  raise TooManyMetadataItems, "Metadata is limited to a total of #{MAX_PERSONALITY_METADATA_ITEMS} key/value pairs" if options[:metadata].is_a?(Hash) && options[:metadata].keys.size > MAX_PERSONALITY_METADATA_ITEMS
  data = JSON.generate(:server => options)
  response = csreq("POST",svrmgmthost,"#{svrmgmtpath}/servers",svrmgmtport,svrmgmtscheme,{'content-type' => 'application/json'},data)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  server_info = JSON.parse(response.body)['server']
  server = CloudServers::Server.new(self,server_info['id'])
  server.adminPass = server_info['adminPass']
  return server
end
create_shared_ip_group(options) click to toggle source

Creates a new Shared IP group. Takes a hash as an argument.

Valid hash keys are :name (required) and :server (optional), which indicates the one server to place into this group by default.

>> sig = cs.create_shared_ip_group(:name => "Production Web", :server => 110917) 
=> #<CloudServers::SharedIPGroup:0x101501d18 ...>
>> sig.name
=> "Production Web"
>> sig.servers
=> [110917]
# File lib/cloudservers/connection.rb, line 273
def create_shared_ip_group(options)
  data = JSON.generate(:sharedIpGroup => options)
  response = csreq("POST",svrmgmthost,"#{svrmgmtpath}/shared_ip_groups",svrmgmtport,svrmgmtscheme,{'content-type' => 'application/json'},data)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  ip_group = JSON.parse(response.body)['sharedIpGroup']
  CloudServers::SharedIPGroup.new(self,ip_group['id'])
end
flavor(id) click to toggle source
Alias for: get_flavor
flavors(options = {}) click to toggle source
Alias for: list_flavors
get_flavor(id) click to toggle source

Returns a CloudServers::Flavor object for the flavor identified by the provided ID.

>> flavor = cs.flavor(1)
=> #<CloudServers::Flavor:0x10156dcc0 @name="256 server", @disk=10, @id=1, @ram=256>
# File lib/cloudservers/connection.rb, line 235
def get_flavor(id)
  CloudServers::Flavor.new(self,id)
end
Also aliased as: flavor
get_image(id) click to toggle source

Returns a CloudServers::Image object for the image identified by the provided id.

>> image = cs.get_image(8)
=> #<CloudServers::Image:0x101659698 ...>
# File lib/cloudservers/connection.rb, line 206
def get_image(id)
  CloudServers::Image.new(self,id)
end
Also aliased as: image
get_server(id) click to toggle source

Returns the CloudServers::Server object identified by the given id.

>> server = cs.get_server(110917)
=> #<CloudServers::Server:0x101407ae8 ...>
>> server.name
=> "MyServer"
# File lib/cloudservers/connection.rb, line 99
def get_server(id)
  CloudServers::Server.new(self,id)
end
Also aliased as: server
get_shared_ip_group(id) click to toggle source

Returns a CloudServers::SharedIPGroup object for the IP group identified by the provided ID.

>> sig = cs.get_shared_ip_group(127)
=> #<CloudServers::SharedIPGroup:0x10153ca30  ...>
# File lib/cloudservers/connection.rb, line 258
def get_shared_ip_group(id)
  CloudServers::SharedIPGroup.new(self,id)
end
Also aliased as: shared_ip_group
image(id) click to toggle source
Alias for: get_image
images(options = {}) click to toggle source
Alias for: list_images
limits() click to toggle source

Returns the current state of the programatic API limits. Each account has certain limits on the number of resources allowed in the account, and a rate of API operations.

The operation returns a hash. The :absolute hash key reveals the account resource limits, including the maxmimum amount of total RAM that can be allocated (combined among all servers), the maximum members of an IP group, and the maximum number of IP groups that can be created.

The :rate hash key returns an array of hashes indicating the limits on the number of operations that can be performed in a given amount of time. An entry in this array looks like:

{:regex=>"^/servers", :value=>50, :verb=>"POST", :remaining=>50, :unit=>"DAY", :resetTime=>1272399820, :URI=>"/servers*"}

This indicates that you can only run 50 POST operations against URLs in the /servers URI space per day, we have not run any operations today (50 remaining), and gives the Unix time that the limits reset.

Another example is:

{:regex=>".*", :value=>10, :verb=>"PUT", :remaining=>10, :unit=>"MINUTE", :resetTime=>1272399820, :URI=>"*"}

This says that you can run 10 PUT operations on all possible URLs per minute, and also gives the number remaining and the time that the limit resets.

Use this information as you're building your applications to put in relevant pauses if you approach your API limitations.

# File lib/cloudservers/connection.rb, line 304
def limits
  response = csreq("GET",svrmgmthost,"#{svrmgmtpath}/limits",svrmgmtport,svrmgmtscheme)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  CloudServers.symbolize_keys(JSON.parse(response.body)['limits'])
end
list_flavors(options = {}) click to toggle source

Returns an array of hashes listing all available server flavors. The :id key in the hash can be used when flavorId is required.

You can also provide :limit and :offset parameters to handle pagination.

>> cs.list_flavors
=> [{:name=>"256 server", :id=>1, :ram=>256, :disk=>10}, 
    {:name=>"512 server", :id=>2, :ram=>512, :disk=>20},...

>> cs.list_flavors(:limit => 3, :offset => 2)
=> [{:ram=>1024, :disk=>40, :name=>"1GB server", :id=>3}, 
    {:ram=>2048, :disk=>80, :name=>"2GB server", :id=>4}, 
    {:ram=>4096, :disk=>160, :name=>"4GB server", :id=>5}]
# File lib/cloudservers/connection.rb, line 223
def list_flavors(options = {})
  path = CloudServers.paginate(options).empty? ? "#{svrmgmtpath}/flavors/detail" : "#{svrmgmtpath}/flavors/detail?#{CloudServers.paginate(options)}"
  response = csreq("GET",svrmgmthost,path,svrmgmtport,svrmgmtscheme)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  CloudServers.symbolize_keys(JSON.parse(response.body)['flavors'])
end
Also aliased as: flavors
list_images(options = {}) click to toggle source

Returns an array of hashes listing available server images that you have access too, including stock Cloud Servers images and any that you have created. The "id" key in the hash can be used where imageId is required.

You can also provide :limit and :offset parameters to handle pagination.

>> cs.list_images
=> [{:name=>"CentOS 5.2", :id=>2, :updated=>"2009-07-20T09:16:57-05:00", :status=>"ACTIVE", :created=>"2009-07-20T09:16:57-05:00"}, 
    {:name=>"Gentoo 2008.0", :id=>3, :updated=>"2009-07-20T09:16:57-05:00", :status=>"ACTIVE", :created=>"2009-07-20T09:16:57-05:00"},...

>> cs.list_images(:limit => 3, :offset => 2) 
=> [{:status=>"ACTIVE", :name=>"Fedora 11 (Leonidas)", :updated=>"2009-12-08T13:50:45-06:00", :id=>13}, 
    {:status=>"ACTIVE", :name=>"CentOS 5.3", :updated=>"2009-08-26T14:59:52-05:00", :id=>7}, 
    {:status=>"ACTIVE", :name=>"CentOS 5.4", :updated=>"2009-12-16T01:02:17-06:00", :id=>187811}]
# File lib/cloudservers/connection.rb, line 194
def list_images(options = {})
  path = CloudServers.paginate(options).empty? ? "#{svrmgmtpath}/images/detail" : "#{svrmgmtpath}/images/detail?#{CloudServers.paginate(options)}"
  response = csreq("GET",svrmgmthost,path,svrmgmtport,svrmgmtscheme)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  CloudServers.symbolize_keys(JSON.parse(response.body)['images'])
end
Also aliased as: images
list_servers(options = {}) click to toggle source

Returns an array of hashes, one for each server that exists under this account. The hash keys are :name and :id.

You can also provide :limit and :offset parameters to handle pagination.

>> cs.list_servers
=> [{:name=>"MyServer", :id=>110917}]

>> cs.list_servers(:limit => 2, :offset => 3)
=> [{:name=>"demo-standingcloud-lts", :id=>168867}, 
    {:name=>"demo-aicache1", :id=>187853}]
# File lib/cloudservers/connection.rb, line 114
def list_servers(options = {})
  anti_cache_param="cacheid=#{Time.now.to_i}"
  path = CloudServers.paginate(options).empty? ? "#{svrmgmtpath}/servers?#{anti_cache_param}" : "#{svrmgmtpath}/servers?#{CloudServers.paginate(options)}&#{anti_cache_param}"
  response = csreq("GET",svrmgmthost,path,svrmgmtport,svrmgmtscheme)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  CloudServers.symbolize_keys(JSON.parse(response.body)["servers"])
end
Also aliased as: servers
list_servers_detail(options = {}) click to toggle source

Returns an array of hashes with more details about each server that exists under this account. Additional information includes public and private IP addresses, status, hostID, and more. All hash keys are symbols except for the metadata hash, which are verbatim strings.

You can also provide :limit and :offset parameters to handle pagination.

>> cs.list_servers_detail
=> [{:name=>"MyServer", :addresses=>{:public=>["67.23.42.37"], :private=>["10.176.241.237"]}, :metadata=>{"MyData" => "Valid"}, :imageId=>10, :progress=>100, :hostId=>"36143b12e9e48998c2aef79b50e144d2", :flavorId=>1, :id=>110917, :status=>"ACTIVE"}]

>> cs.list_servers_detail(:limit => 2, :offset => 3)
=> [{:status=>"ACTIVE", :imageId=>10, :progress=>100, :metadata=>{}, :addresses=>{:public=>["x.x.x.x"], :private=>["x.x.x.x"]}, :name=>"demo-standingcloud-lts", :id=>168867, :flavorId=>1, :hostId=>"xxxxxx"}, 
    {:status=>"ACTIVE", :imageId=>8, :progress=>100, :metadata=>{}, :addresses=>{:public=>["x.x.x.x"], :private=>["x.x.x.x"]}, :name=>"demo-aicache1", :id=>187853, :flavorId=>3, :hostId=>"xxxxxx"}]
# File lib/cloudservers/connection.rb, line 134
def list_servers_detail(options = {})
  path = CloudServers.paginate(options).empty? ? "#{svrmgmtpath}/servers/detail" : "#{svrmgmtpath}/servers/detail?#{CloudServers.paginate(options)}"
  response = csreq("GET",svrmgmthost,path,svrmgmtport,svrmgmtscheme)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  CloudServers.symbolize_keys(JSON.parse(response.body)["servers"])
end
Also aliased as: servers_detail
list_shared_ip_groups(options = {}) click to toggle source

Returns an array of hashes for all Shared IP Groups that are available. The :id key can be used to find that specific object.

You can also provide :limit and :offset parameters to handle pagination.

>> cs.list_shared_ip_groups
=> [{:name=>"New Group", :id=>127}]
# File lib/cloudservers/connection.rb, line 246
def list_shared_ip_groups(options = {})
  path = CloudServers.paginate(options).empty? ? "#{svrmgmtpath}/shared_ip_groups/detail" : "#{svrmgmtpath}/shared_ip_groups/detail?#{CloudServers.paginate(options)}"
  response = csreq("GET",svrmgmthost,path,svrmgmtport,svrmgmtscheme)
  CloudServers::Exception.raise_exception(response) unless response.code.match(%r^20.$/)
  CloudServers.symbolize_keys(JSON.parse(response.body)['sharedIpGroups'])
end
Also aliased as: shared_ip_groups
server(id) click to toggle source
Alias for: get_server
servers(options = {}) click to toggle source
Alias for: list_servers
servers_detail(options = {}) click to toggle source
Alias for: list_servers_detail
shared_ip_group(id) click to toggle source
Alias for: get_shared_ip_group
shared_ip_groups(options = {}) click to toggle source