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.

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



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
104
105
106
 
# 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,
    :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.



116
117
118
 
# File 'lib/aws/configuration.rb', line 116

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.



163
164
165
 
# File 'lib/aws/configuration.rb', line 163

def ec2_endpoint
  @options[:ec2_endpoint]
end

#http_handler ⇒ Object

Returns the current http handler.

Returns:

  • (Object) —

    Returns the current http handler.



200
201
202
 
# File 'lib/aws/configuration.rb', line 200

def http_handler
  @options[:http_handler]
end

#logger ⇒ Object?

Returns the current logger.

Returns:

  • (Object, nil) —

    Returns the current logger.



212
213
214
 
# File 'lib/aws/configuration.rb', line 212

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.



153
154
155
 
# File 'lib/aws/configuration.rb', line 153

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.



158
159
160
 
# File 'lib/aws/configuration.rb', line 158

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.



237
238
239
 
# File 'lib/aws/configuration.rb', line 237

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.



231
232
233
 
# File 'lib/aws/configuration.rb', line 231

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.



225
226
227
 
# File 'lib/aws/configuration.rb', line 225

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.



121
122
123
 
# File 'lib/aws/configuration.rb', line 121

def secret_access_key
  @options[:secret_access_key]
end

#signer ⇒ Object

Returns the current request signer.

Returns:

  • (Object) —

    Returns the current request signer.



205
206
207
208
209
 
# File 'lib/aws/configuration.rb', line 205

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.



189
190
191
 
# File 'lib/aws/configuration.rb', line 189

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.



168
169
170
 
# File 'lib/aws/configuration.rb', line 168

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.



173
174
175
 
# File 'lib/aws/configuration.rb', line 173

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.



178
179
180
 
# File 'lib/aws/configuration.rb', line 178

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.



183
184
185
 
# File 'lib/aws/configuration.rb', line 183

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.



258
259
260
 
# File 'lib/aws/configuration.rb', line 258

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.



248
249
250
 
# File 'lib/aws/configuration.rb', line 248

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.



219
220
221
 
# File 'lib/aws/configuration.rb', line 219

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.



110
111
112
 
# File 'lib/aws/configuration.rb', line 110

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.



195
196
197
 
# File 'lib/aws/configuration.rb', line 195

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.

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



145
146
147
148
149
150
 
# File 'lib/aws/configuration.rb', line 145

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