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.

  • :proxy_uri (String, URI, nil) — default: nil —

    The URI of the proxy to send service requests through. You can pass a URI object or a URI string:

    AWS.config(:proxy_uri => 'https://user:[email protected]:443/path?query')
  • :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.

  • :ssl_verify_peer (Boolean) — default: true —

    True if the HTTPS client should validate the server certificate. Note: This option should only be used for diagnostic purposes; leaving this option set to false exposes your application to man-in-the-middle attacks and can pose a serious security risk.

  • :ssl_ca_file (String) —

    The path to a CA cert bundle in PEM format. If :ssl_verify_peer is true (the default) this bundle will be used to validate the server certificate in each HTTPS request. The AWS SDK for Ruby ships with a CA cert bundle, which is the default value for this option.

  • :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.



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
104
105
106
107
108
 
# File 'lib/aws/configuration.rb', line 64

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,
    :proxy_uri => nil,
    :use_ssl => true,
    :user_agent_prefix => nil,
    :ssl_verify_peer => true,
    :ssl_ca_file => File.expand_path(File.dirname(__FILE__)+
                                     "/../../ca-bundle.crt")
  }

  {
    '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.



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

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.



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

def ec2_endpoint
  @options[:ec2_endpoint]
end

#http_handler ⇒ Object

Returns the current http handler.

Returns:

  • (Object) —

    Returns the current http handler.



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

def http_handler
  @options[:http_handler]
end

#logger ⇒ Object?

Returns the current logger.

Returns:

  • (Object, nil) —

    Returns the current logger.



214
215
216
 
# File 'lib/aws/configuration.rb', line 214

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.



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

def max_retries
  @options[:max_retries]
end

#proxy_uri ⇒ URI::HTTP, ...

Returns the URI for the configured proxy if there is one. Defaults to nil.

Returns:

  • (URI::HTTP, URI::HTTPS, nil) —

    Returns the URI for the configured proxy if there is one. Defaults to nil.



266
267
268
 
# File 'lib/aws/configuration.rb', line 266

def proxy_uri
  @options[:proxy_uri] ? URI.parse(@options[:proxy_uri].to_s) : nil
end

#s3_endpoint ⇒ String

Returns The service endpoint for Amazon S3.

Returns:

  • (String) —

    The service endpoint for Amazon S3.



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

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.



239
240
241
 
# File 'lib/aws/configuration.rb', line 239

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.



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

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.



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

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.



123
124
125
 
# File 'lib/aws/configuration.rb', line 123

def secret_access_key
  @options[:secret_access_key]
end

#signer ⇒ Object

Returns the current request signer.

Returns:

  • (Object) —

    Returns the current request signer.



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

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.



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

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.



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

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.



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

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.



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

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.



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

def sqs_endpoint
  @options[:sqs_endpoint]
end

#ssl_ca_file ⇒ String

If #ssl_verify_peer? is true (the default) this bundle will be used to validate the server certificate in each HTTPS request. The AWS SDK for Ruby ships with a CA cert bundle, which is the default value for this option.

Returns:

  • (String) —

    The path to a CA cert bundle in PEM format.



260
261
262
 
# File 'lib/aws/configuration.rb', line 260

def ssl_ca_file
  @options[:ssl_ca_file]
end

#ssl_verify_peer? ⇒ Boolean

Note:

This option should only be used for diagnostic purposes; leaving this option set to false exposes your application to man-in-the-middle attacks and can pose a serious security risk.

Returns True if the HTTPS client should validate the server certificate.

Returns:

  • (Boolean) —

    True if the HTTPS client should validate the server certificate.



250
251
252
 
# File 'lib/aws/configuration.rb', line 250

def ssl_verify_peer?
  @options[:ssl_verify_peer]
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.



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

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.



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

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.



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

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.

  • :proxy_uri (String, URI, nil) — default: nil —

    The URI of the proxy to send service requests through. You can pass a URI object or a URI string:

    AWS.config(:proxy_uri => 'https://user:[email protected]:443/path?query')
  • :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.

  • :ssl_verify_peer (Boolean) — default: true —

    True if the HTTPS client should validate the server certificate. Note: This option should only be used for diagnostic purposes; leaving this option set to false exposes your application to man-in-the-middle attacks and can pose a serious security risk.

  • :ssl_ca_file (String) —

    The path to a CA cert bundle in PEM format. If :ssl_verify_peer is true (the default) this bundle will be used to validate the server certificate in each HTTPS request. The AWS SDK for Ruby ships with a CA cert bundle, which is the default value for this option.

  • :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.



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

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