Class: AWS::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/configuration.rb

Overview

A configuration object for AWS interfaces and clients.

Configuring Credential

In order to do anything with AWS you will need to assign credentials. The simplest method is to assing your credentials into the default configuration:

AWS.config(:access_key_id => 'KEY', :secret_access_key => 'SECRET')

You can also export them into your environment and they will be picked up automatically:

export AWS_ACCESS_KEY_ID='YOUR_KEY_ID_HERE'
export AWS_SECRET_ACCESS_KEY='YOUR_SECRET_KEY_HERE'

For compatability with other AWS gems, the credentials can also be exported like:

export AMAZON_ACCESS_KEY_ID='YOUR_KEY_ID_HERE'
export AMAZON_SECRET_ACCESS_KEY='YOUR_SECRET_KEY_HERE'

Modifying a Configuration

Configuration objects are read-only. If you need a different set of configuration values, call #with, passing in the updates and a new configuration object will be returned.

config = Configuration.new(:max_retires => 3)
new_config = config.with(:max_retries => 2)

config.max_retries #=> 3
new_config.max_retries #=> 2

Global Configuration

The global default configuration can be found at config

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Configuration

Creates a new Configuration object.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :access_key_id (String) —

    Your account access key id credential.

  • :secret_access_key (String) —

    Your account secret access key credential.

  • :max_retries (Integer) — default: 3 —

    The maximum number of times service errors (500) should be retried. There is an exponential backoff in between service request retries, so the more retries the longer it can take to fail.

  • :ec2_endpoint (String) — default: 'ec2.amazonaws.com' —

    The service endpoint to use when communicating with Amazon EC2.

  • :http_handler (Object) —

    The request/response handler for all service requests. The default handler uses HTTParty to send requests.

  • :logger (Object) — default: nil —

    A logger instance that should receive log messages generated by service requets. A logger needs to respond to #log and must accept a severity (e.g. :info, :error, etc) and a string message.

  • :s3_endpoint (String) — default: 's3.amazonaws.com' —

    The service endpoint to use when communicating with Amazon S3.

  • :simple_db_consistent_reads (Boolean) — default: false —

    When true all read operations against SimpleDB will be consistent reads (slower).

  • :simple_db_endpoint (String) — default: 'sdb.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SimpleDB.

  • :simple_email_service_endpoint (String) — default: 'email.us-east-1.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SimpleEmailService.

  • :signer (Object) —

    The request signer. Defaults to a DefaultSigner.

  • :sns_endpoint (String) — default: 'sns.us-east-1.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SNS.

  • :sqs_endpoint (String) — default: 'sqs.us-east-1.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SQS.

  • :stub_requests (Object) — default: false —

    When true no requests will be made against the live service. Responses returned will have empty values. This is primarily used for writing tests.

  • :use_ssl (Boolean) — default: true —

    When true, all requests are sent over SSL.

  • :user_agent_prefix (String) — default: nil —

    A string prefix to append to all requets against AWS services. This should be set for clients and applications built ontop of the aws-sdk gem.



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/aws/configuration.rb', line 63

def initialize options = {}

  @create_options = options.delete(:__create_options__) || {}

  @overridden = options.delete(:__overridden__) ||
    Set.new(options.keys.map { |k| k.to_sym })

  @options = {
    :ec2_endpoint => 'ec2.amazonaws.com',
    :http_handler => Http::HTTPartyHandler.new,
    :max_retries => 3,
    :s3_endpoint => 's3.amazonaws.com',
    :s3_multipart_threshold => 16 * 1024 * 1024,
    :s3_multipart_min_part_size => 5 * 1024 * 1024,
    :s3_multipart_max_parts => 10000,
    :simple_db_endpoint => 'sdb.amazonaws.com',
    :simple_db_consistent_reads => false,
    :simple_email_service_endpoint => 'email.us-east-1.amazonaws.com',
    :sns_endpoint => 'sns.us-east-1.amazonaws.com',
    :sqs_endpoint => 'sqs.us-east-1.amazonaws.com',
    :stub_requests => false,
    :use_ssl => true,
    :user_agent_prefix => nil,
  }

  {
    'AWS_ACCESS_KEY_ID'        => :access_key_id,
    'AWS_SECRET_ACCESS_KEY'    => :secret_access_key,
    'AMAZON_ACCESS_KEY_ID'     => :access_key_id,
    'AMAZON_SECRET_ACCESS_KEY' => :secret_access_key,
  }.each_pair do |env_key, opt_key|
    if ENV[env_key]
      @options[opt_key] = ENV[env_key]
    end
  end

  options.each do |(k,v)|
    @options[k.to_sym] = v
  end

end

Instance Method Details

#access_key_id ⇒ String

Returns Your AWS account access key id credential.

Returns:

  • (String) —

    Your AWS account access key id credential.



113
114
115
 
# File 'lib/aws/configuration.rb', line 113

def access_key_id
  @options[:access_key_id]
end

#ec2_endpoint ⇒ String

Returns The default service endpoint for Amazon EC2.

Returns:

  • (String) —

    The default service endpoint for Amazon EC2.



160
161
162
 
# File 'lib/aws/configuration.rb', line 160

def ec2_endpoint
  @options[:ec2_endpoint]
end

#http_handler ⇒ Object

Returns the current http handler.

Returns:

  • (Object) —

    Returns the current http handler.



197
198
199
 
# File 'lib/aws/configuration.rb', line 197

def http_handler
  @options[:http_handler]
end

#logger ⇒ Object?

Returns the current logger.

Returns:

  • (Object, nil) —

    Returns the current logger.



209
210
211
 
# File 'lib/aws/configuration.rb', line 209

def logger
  @options[:logger]
end

#max_retries ⇒ Integer

Returns Maximum number of times to retry server errors.

Returns:

  • (Integer) —

    Maximum number of times to retry server errors.



150
151
152
 
# File 'lib/aws/configuration.rb', line 150

def max_retries
  @options[:max_retries]
end

#s3_endpoint ⇒ String

Returns The service endpoint for Amazon S3.

Returns:

  • (String) —

    The service endpoint for Amazon S3.



155
156
157
 
# File 'lib/aws/configuration.rb', line 155

def s3_endpoint
  @options[:s3_endpoint]
end

#s3_multipart_max_parts ⇒ Integer

Returns The maximum number of parts to split a file into when uploading to S3.

Returns:

  • (Integer) —

    The maximum number of parts to split a file into when uploading to S3.



234
235
236
 
# File 'lib/aws/configuration.rb', line 234

def s3_multipart_max_parts
  @options[:s3_multipart_max_parts]
end

#s3_multipart_min_part_size ⇒ Integer

Returns The absolute minimum size (in bytes) each S3 multipart segment should be.

Returns:

  • (Integer) —

    The absolute minimum size (in bytes) each S3 multipart segment should be.



228
229
230
 
# File 'lib/aws/configuration.rb', line 228

def s3_multipart_min_part_size
  @options[:s3_multipart_min_part_size]
end

#s3_multipart_threshold ⇒ Integer

Returns the number of bytes where files larger are uploaded to S3 in multiple parts.

Returns:

  • (Integer) —

    Returns the number of bytes where files larger are uploaded to S3 in multiple parts.



222
223
224
 
# File 'lib/aws/configuration.rb', line 222

def s3_multipart_threshold
  @options[:s3_multipart_threshold]
end

#secret_access_key ⇒ String

Returns Your AWS secret access key credential.

Returns:

  • (String) —

    Your AWS secret access key credential.



118
119
120
 
# File 'lib/aws/configuration.rb', line 118

def secret_access_key
  @options[:secret_access_key]
end

#signer ⇒ Object

Returns the current request signer.

Returns:

  • (Object) —

    Returns the current request signer.



202
203
204
205
206
 
# File 'lib/aws/configuration.rb', line 202

def signer
  return @options[:signer] if @options[:signer]
  raise "Missing credentials" unless access_key_id and secret_access_key
  @options[:signer] ||= DefaultSigner.new(access_key_id, secret_access_key)
end

#simple_db_consistent_reads? ⇒ Boolean

Returns true if all reads to SimpleDB default to consistent reads.

Returns:

  • (Boolean) —

    Returns true if all reads to SimpleDB default to consistent reads.



186
187
188
 
# File 'lib/aws/configuration.rb', line 186

def simple_db_consistent_reads?
  @options[:simple_db_consistent_reads]
end

#simple_db_endpoint ⇒ String

Returns The service endpoint for Amazon SimpleDB.

Returns:

  • (String) —

    The service endpoint for Amazon SimpleDB.



165
166
167
 
# File 'lib/aws/configuration.rb', line 165

def simple_db_endpoint
  @options[:simple_db_endpoint]
end

#simple_email_service_endpoint ⇒ String

Returns The service endpoint for Amazon SimpleEmailService.

Returns:

  • (String) —

    The service endpoint for Amazon SimpleEmailService.



170
171
172
 
# File 'lib/aws/configuration.rb', line 170

def simple_email_service_endpoint
  @options[:simple_email_service_endpoint]
end

#sns_endpoint ⇒ String

Returns The service endpoint for Amazon SNS.

Returns:

  • (String) —

    The service endpoint for Amazon SNS.



175
176
177
 
# File 'lib/aws/configuration.rb', line 175

def sns_endpoint
  @options[:sns_endpoint]
end

#sqs_endpoint ⇒ String

Returns The service endpoint for Amazon SQS.

Returns:

  • (String) —

    The service endpoint for Amazon SQS.



180
181
182
 
# File 'lib/aws/configuration.rb', line 180

def sqs_endpoint
  @options[:sqs_endpoint]
end

#stub_requests? ⇒ Boolean

Returns true if this configuration causes all AWS requests to return stubbed (empty) responses without making a request to the actual service.

Returns:

  • (Boolean) —

    Returns true if this configuration causes all AWS requests to return stubbed (empty) responses without making a request to the actual service.



216
217
218
 
# File 'lib/aws/configuration.rb', line 216

def stub_requests?
  @options[:stub_requests]
end

#use_ssl? ⇒ Boolean Also known as: use_ssl

Returns true if web service requets should be made with HTTPS.

Returns:

  • (Boolean) —

    Returns true if web service requets should be made with HTTPS.



107
108
109
 
# File 'lib/aws/configuration.rb', line 107

def use_ssl?
  @options[:use_ssl]
end

#user_agent_prefix ⇒ String?

Returns the prefix that is appended to the user agent string that is sent with all requests to AWS.

Returns:

  • (String, nil) —

    Returns the prefix that is appended to the user agent string that is sent with all requests to AWS.



192
193
194
 
# File 'lib/aws/configuration.rb', line 192

def user_agent_prefix
  @options[:user_agent_prefix]
end

#with(options = {}) ⇒ Configuration

Used to create a new Configuration object with the given modifications. The current configuration object is not modified.

AWS.config(:max_retries => 2)

no_retries_config = AWS.config.with(:max_retries => 0)

AWS.config.max_retries        #=> 2
no_retries_config.max_retries #=> 0

You can use these configuration objects returned by #with to create AWS objects:

AWS::S3.new(:config => no_retries_config)
AWS::SQS.new(:config => no_retries_config)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :access_key_id (String) —

    Your account access key id credential.

  • :secret_access_key (String) —

    Your account secret access key credential.

  • :max_retries (Integer) — default: 3 —

    The maximum number of times service errors (500) should be retried. There is an exponential backoff in between service request retries, so the more retries the longer it can take to fail.

  • :ec2_endpoint (String) — default: 'ec2.amazonaws.com' —

    The service endpoint to use when communicating with Amazon EC2.

  • :http_handler (Object) —

    The request/response handler for all service requests. The default handler uses HTTParty to send requests.

  • :logger (Object) — default: nil —

    A logger instance that should receive log messages generated by service requets. A logger needs to respond to #log and must accept a severity (e.g. :info, :error, etc) and a string message.

  • :s3_endpoint (String) — default: 's3.amazonaws.com' —

    The service endpoint to use when communicating with Amazon S3.

  • :simple_db_consistent_reads (Boolean) — default: false —

    When true all read operations against SimpleDB will be consistent reads (slower).

  • :simple_db_endpoint (String) — default: 'sdb.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SimpleDB.

  • :simple_email_service_endpoint (String) — default: 'email.us-east-1.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SimpleEmailService.

  • :signer (Object) —

    The request signer. Defaults to a DefaultSigner.

  • :sns_endpoint (String) — default: 'sns.us-east-1.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SNS.

  • :sqs_endpoint (String) — default: 'sqs.us-east-1.amazonaws.com' —

    The service endpoint to use when communicating with Amazon SQS.

  • :stub_requests (Object) — default: false —

    When true no requests will be made against the live service. Responses returned will have empty values. This is primarily used for writing tests.

  • :use_ssl (Boolean) — default: true —

    When true, all requests are sent over SSL.

  • :user_agent_prefix (String) — default: nil —

    A string prefix to append to all requets against AWS services. This should be set for clients and applications built ontop of the aws-sdk gem.

Returns:

  • (Configuration) —

    Copies the current configuration and returns a new one with modifications as provided in :options.



142
143
144
145
146
147
 
# File 'lib/aws/configuration.rb', line 142

def with options = {}
  overridden = @overridden + options.keys.map { |k| k.to_sym }
  self.class.new(@options.merge(options).
                 merge(:__create_options__ => @create_options,
                       :__overridden__ => overridden))
end