rest_connection 1.0.5 → 1.0.6

data/README.md

@@ -0,0 +1,140 @@
+# RightScale REST Connection
+
+The rest_connection gem is a Ruby library for RightScale's API 0.1, 1.0 and 1.5.
+
+Legacy clusters:
+- API 0.1 AWS clouds
+- API 1.0 AWS clouds
+- API 1.5 non-AWS clouds
+
+Unified clusters:
+- API 1.0 AWS clouds
+- API 1.5 all clouds
+
+This gem also supports RightScale's instance facing API 1.0, which use the instance token to login.
+The instance token is found in the instance's user data as 'RS_rn_auth' or alternatively as part of 'RS_api_url'.
+The user data is available under the 'Info' tab on the server's page in the RightScale Dashboard.
+
+This gem should be considered deprecated!
+
+If you only use API 1.5, you should use the right_api_client gem instead:
+https://rubygems.org/gems/right_api_client
+
+- API 1.0 Documentation: http://support.rightscale.com/12-Guides/03-RightScale_API
+- API 1.0 Reference Docs: http://reference.rightscale.com/api1.0
+- API 1.5 Documentation: http://support.rightscale.com/12-Guides/RightScale_API_1.5
+- API 1.5 Reference Docs: http://reference.rightscale.com/api1.5
+
+Maintained by the RightScale "Yellow_team" 
+
+## Installation
+
+Ruby 1.8.7 or higher is required.
+
+### Installing from RubyGems
+
+    "gem install rest_connection"
+
+### Installing from source
+
+    "git clone git@github.com:rightscale/rest_connection.git"
+    "cd rest_connection"
+    "gem install rconf"
+    "rconf" <- follow any further instructions from rconf
+    "bundle install"
+
+## Versioning
+
+This gem follows semantic versioning: http://semver.org
+
+## Usage Instructions
+
+You must setup '~/.rest_connection/rest_api_config.yaml' or '/etc/rest_connection/rest_api_config.yaml'
+
+Copy the example from '$GEMHOME/rest_connection/config/rest_api_config.yaml.sample' and fill in your connection info.
+
+Pro Tip: to find a $GEMHOME, use gemedit
+
+    "gem install gemedit"
+    "gem edit rest_connection"
+
+The following examples assume an interactive ruby session (irb):
+
+    $ bundle exec irb
+    ruby> require 'rubygems'; require 'rest_connection'
+
+### Look up and run a RightScript
+
+    first_fe = Server.find(:first) { |s| s.nickname =~ /Front End/ }
+    st = ServerTemplate.find(first_fe.server_template_href)
+    connect_script = st.executables.detect { |ex| ex.name =~ /LB [app|mongrels]+ to HA proxy connect/i }
+    state = first_fe.run_executable(connect_script)
+    state.wait_for_completed
+
+### Stop a Deployment
+
+    deployment = Deployment.find(opts[:id])
+    my_servers = deployment.servers
+    my_servers.each { |s| s.stop }
+    my_servers.each { |s| s.wait_for_state("stopped") }
+
+### Activate an Ec2ServerArray / Display instances IPs
+
+    my_array = Ec2ServerArray.find(opts[:href])
+    my_array.active = true
+    my_array.save
+
+    puts my_array.instances.map { |i| i['ip-address'] }
+
+## Design Decisions
+
+Currently, all API resources are represented by classes in 'lib/rest_connection/rightscale'.
+Various helper modules are also located in this directory.
+
+### API 0.1 resources
+
+API 0.1 resources are often named with suffix '_internal'.
+
+They often pull in common internal code:
+
+    include RightScale::Api::Internal
+    extend RightScale::Api::InternalExtend
+
+### API 1.0 resources
+
+API 1.0 resources are often named with prefix 'ec2_' for Amazon Elastic Compute Cloud.
+
+They often pull in common internal code:
+
+    include RightScale::Api::Base
+    extend RightScale::Api::BaseExtend
+
+### API 1.5 resources
+
+API 1.5 resources are often named with prefix 'mc_' for MultiCloud.
+They often talk to the MultiCloud gateway and therefore pull in some common gateway code:
+
+    include RightScale::Api::Gateway
+    extend RightScale::Api::GatewayExtend
+
+## Troubleshooting
+
+### Wrong ruby version
+
+Ruby 1.8.7 or higher is required.
+
+## Publishing
+
+To cut a new gem and push to RubyGems:
+
+Edit lib/rest_connection/version.rb with semantic version number.
+
+    "bundle exec gem build rest_connection.gemspec"
+    "ls *.gem" <- verify that gem was built
+    "cd /tmp"
+    "bundle exec gem install /path/to/local/rest_connection-X.Y.Z.gem" <- replace X.Y.Z with your new version number
+    "bundle exec gem uninstall rest_connection"
+    "cd -"
+    "bundle exec gem push rest_connection-X.Y.Z.gem"
+
+Check it out: https://rubygems.org/gems/rest_connection

data/lib/rest_connection/rightscale/account.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 
 #

data/lib/rest_connection/rightscale/alert_spec.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class AlertSpec
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/alert_spec_subject.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class AlertSpecSubject
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/audit_entry.rb

@@ -33,6 +33,9 @@
 #  end
 #end
 
+#
+# API 1.0
+#
 class AuditEntry
   include  RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/backup.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class Backup
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/child_account.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 
 #

data/lib/rest_connection/rightscale/cloud.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class Cloud
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/cloud_account.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class CloudAccount
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/credential.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Credential
   include  RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/deployment.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Deployment
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/ec2_ebs_snapshot.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Ec2EbsSnapshot
   include  RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/ec2_ebs_volume.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Ec2EbsVolume
   include  RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/ec2_elastic_ip.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Ec2ElasticIp
   include  RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/ec2_security_group.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Ec2SecurityGroup
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/ec2_server_array.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Ec2ServerArray
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend
@@ -31,9 +34,6 @@ class Ec2ServerArray
 
   def initialize(*args, &block)
     super(*args, &block)
-    if RightScale::Api::api0_1?
-      @internal = Ec2ServerArrayInternal.new(*args, &block)
-    end
   end
 
 #  Example:
@@ -50,6 +50,37 @@ class Ec2ServerArray
      connection.post("#{serv_href.path}/run_script_on_all", options)
   end
 
+  #
+  # Run a script on individual instances in a ServerArray
+  #
+  # This was formerly located in Ec2ServerArrayInternal but has 
+  # been moved here to Ec2ServerArray as the call has been ported
+  # from API 0.1 to API 1.0.
+  #
+  # Example: array.run_script_on_instances(right_script, server_href, options_hash)
+  #
+  def run_script_on_instances(script, ec2_instance_hrefs=[], opts={})
+    uri = URI.parse(self.href)
+    case script
+    when Executable then script = script.right_script
+    when String then script = RightScript.new('href' => script)
+    end
+
+    params = {:right_script_href => script.href }
+    unless ec2_instance_hrefs.nil? || ec2_instance_hrefs.empty?
+      params[:ec2_instance_hrefs] = ec2_instance_hrefs
+    end
+    unless opts.nil? || opts.empty?
+      params[:parameters] = opts
+    end
+    params = {:ec2_server_array => params}
+    status_array=[]
+    connection.post(uri.path + "/run_script_on_instances", params).map do |work_unit|
+      status_array.push Status.new('href' => work_unit)
+    end
+    return(status_array)
+  end
+
   def instances
     serv_href = URI.parse(self.href)
     connection.get("#{serv_href.path}/instances")

data/lib/rest_connection/rightscale/ec2_ssh_key.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Ec2SshKey
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/ec2_ssh_key_internal.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 0.1
+#
 class Ec2SshKeyInternal
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/executable.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Executable
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/instance.rb

@@ -21,9 +21,11 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-# This is an instance facing api and can only be used with
-# an authentication URL normally found in the instance's userdata called
-# RS_API_URL
+#
+# API 1.0
+#
+
+# Requires instance token for authentication
 class Instance
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/instance_type.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class InstanceType
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/macro.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class Macro
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend

data/lib/rest_connection/rightscale/mc_audit_entry.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McAuditEntry
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_datacenter.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McDatacenter
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_deployment.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McDeployment
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_image.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McImage
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_instance.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McInstance
   include RightScale::Api::Gateway
@@ -151,7 +151,7 @@ class McInstance
     return href
   end
 
-  def run_executable(executable, opts=nil)
+  def run_executable(executable, opts=nil, ignore_lock=false)
     run_options = Hash.new
     if executable.is_a?(Executable)
       if executable.recipe?
@@ -165,8 +165,15 @@ class McInstance
       raise "Invalid class passed to run_executable, needs Executable or RightScript, was:#{executable.class}"
     end
 
+    if not opts.nil? and opts.has_key?(:ignore_lock)
+      run_options[:ignore_lock] = "true"
+      opts.delete(:ignore_lock)
+      opts = nil if opts.empty?
+    end
+
     inst_href = URI.parse(self.href)
     run_options[:inputs] = transform_inputs(:to_a, opts) unless opts.nil?
+    run_options[:ignore_lock] = "true" if ignore_lock
     location = connection.post(inst_href.path + '/run_executable', run_options)
     Task.new('href' => location)
   end

data/lib/rest_connection/rightscale/mc_instance_type.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McInstanceType
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_multi_cloud_image.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McMultiCloudImage
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_multi_cloud_image_setting.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McMultiCloudImageSetting
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_security_group.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McSecurityGroup
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_server.rb

@@ -21,7 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McServer < Server
   include RightScale::Api::Gateway
@@ -161,9 +161,9 @@ class McServer < Server
     raise "You shouldn't be here."
   end
 
-  def run_executable(executable, opts=nil)
+  def run_executable(executable, opts=nil, ignore_lock=false)
     raise "Instance isn't running; Can't run executable" unless @current_instance
-    @current_instance.run_executable(executable, opts)
+    @current_instance.run_executable(executable, opts, ignore_lock)
   end
 
   def transform_inputs(sym, parameters)

data/lib/rest_connection/rightscale/mc_server_array.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McServerArray
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_server_template.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McServerTemplate
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_server_template_multi_cloud_image.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 
 class McServerTemplateMultiCloudImage

data/lib/rest_connection/rightscale/mc_ssh_key.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McSshKey
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_tag.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McTag
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_volume.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McVolume
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_volume_attachment.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McVolumeAttachment
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_volume_snapshot.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McVolumeSnapshot
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/mc_volume_type.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class McVolumeType
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/monitoring_metric.rb

@@ -22,7 +22,7 @@
 #++
 
 #
-# You must have Beta v1.5 API access to use these internal API calls.
+# API 1.5
 #
 class MonitoringMetric
   include RightScale::Api::Gateway

data/lib/rest_connection/rightscale/multi_cloud_image.rb

@@ -21,6 +21,9 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#
+# API 1.0
+#
 class MultiCloudImage
   include RightScale::Api::Base
   extend RightScale::Api::BaseExtend