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 Attribute Summary collapse

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) — default: nil —

    AWS access key id credential.

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

    The service endpoint for Amazon EC2.

  • :http_handler (Object) — default: AWS::HTTPartyHandler —

    The http handler that sends requests to AWS.

  • :iam_endpoint (String) — default: 'iam.amazonaws.com' —

    The service endpoint for AWS Idenity Access Management (IAM).

  • :logger (Object, nil) — 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.

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

  • :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 for Amazon S3.

  • :s3_multipart_max_parts (Integer) — default: 1000 —

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

  • :s3_multipart_threshold (Integer) — default: 16777216 —

    When uploading data to S3, if the number of bytes to send exceedes :s3_multipart_threshold then a multi part session is automatically started and the data is sent up in chunks. The size of each part is specified by :s3_multipart_min_part_size. Defaults to 16777216 (16MB).

  • :s3_multipart_min_part_size (Integer) — default: 5242880 —

    The absolute minimum size (in bytes) each S3 multipart segment should be. Defaults to 5242880 (5MB).

  • :secret_access_key (String) — default: nil —

    AWS secret access key credential.

  • :session_token (String, nil) — default: nil —

    AWS secret token credential.

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

    The service endpoint for Amazon SimpleDB.

  • :simple_db_consistent_reads (Boolean) — default: false —

    Determines if all SimpleDB read requests should be done consistently. Consistent reads are slower, but reflect all changes to SDB.

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

    The service endpoint for Amazon Simple Email Service.

  • :signer (Object) — default: AWS::DefaultSigner —

    The request signer. Defaults to a default request signer implementation.

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

  • :ssl_verify_peer (Boolean) — default: true —

    When true the HTTP handler validate server certificates for HTTPS requests.

    This option should only be disabled 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.

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

    The service endpoint for Amazon SNS.

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

    The service endpoint for Amazon SQS.

  • :sts_endpoint (String) — default: 'sts.amazonaws.com' —

    The service endpoint for AWS Security Token Service.

  • :use_ssl (Boolean) — default: true —

    When true, all requests to AWS are sent using HTTPS instead vanilla HTTP.

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



172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/aws/configuration.rb', line 172

def initialize options = {}

  @created = options.delete(:__created__) || {}

  options.each_pair do |opt_name, value|
    opt_name = opt_name.to_sym
    if self.class.accepted_options.include?(opt_name)
      supplied[opt_name] = value
    end
  end

end

Instance Attribute Details

#access_key_id ⇒ String? (readonly)

AWS access key id credential. Defaults to nil.

Returns:

  • (String, nil) —

    the current value of access_key_id



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

def access_key_id
  @access_key_id
end

#ec2_endpoint ⇒ String (readonly)

The service endpoint for Amazon EC2. Defaults to ‘ec2.amazonaws.com’.

Returns:

  • (String) —

    the current value of ec2_endpoint



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

def ec2_endpoint
  @ec2_endpoint
end

#http_handler ⇒ Object (readonly)

The http handler that sends requests to AWS. Defaults to an HTTPartyHandler.

Returns:

  • (Object) —

    the current value of http_handler



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

def http_handler
  @http_handler
end

#iam_endpoint ⇒ String (readonly)

The service endpoint for AWS Idenity Access Management (IAM). Defaults to ‘iam.amazonaws.com’.

Returns:

  • (String) —

    the current value of iam_endpoint



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

def iam_endpoint
  @iam_endpoint
end

#logger ⇒ Object? (readonly)

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. Defaults to nil.

Returns:

  • (Object, nil) —

    the current value of logger



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

def logger
  @logger
end

#max_retries ⇒ Integer (readonly)

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. Defautls to 3.

Returns:

  • (Integer) —

    the current value of max_retries



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

def max_retries
  @max_retries
end

#proxy_uri ⇒ String, ... (readonly)

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

AWS.config(:proxy_uri => 'https://user:[email protected]:443/path?query')

Returns:

  • (String, URI, nil) —

    the current value of proxy_uri



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

def proxy_uri
  @proxy_uri
end

#s3_endpoint ⇒ String (readonly)

The service endpoint for Amazon S3. Defaults to ‘s3.amazonaws.com’.

Returns:

  • (String) —

    the current value of s3_endpoint



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

def s3_endpoint
  @s3_endpoint
end

#s3_multipart_max_parts ⇒ Integer (readonly)

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

Defaults to 1000.

Returns:

  • (Integer) —

    the current value of s3_multipart_max_parts



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

def s3_multipart_max_parts
  @s3_multipart_max_parts
end

#s3_multipart_min_part_size ⇒ Integer (readonly)

The absolute minimum size (in bytes) each S3 multipart segment should be. Defaults to 5242880 (5MB).

Returns:

  • (Integer) —

    the current value of s3_multipart_min_part_size



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

def s3_multipart_min_part_size
  @s3_multipart_min_part_size
end

#s3_multipart_threshold ⇒ Integer (readonly)

(16777216) When uploading data to S3, if the number of bytes to send exceedes :s3_multipart_threshold then a multi part session is automatically started and the data is sent up in chunks. The size of each part is specified by :s3_multipart_min_part_size. Defaults to 16777216 (16MB).

Returns:

  • (Integer) —

    the current value of s3_multipart_threshold



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

def s3_multipart_threshold
  @s3_multipart_threshold
end

#secret_access_key ⇒ String? (readonly)

AWS secret access key credential. Defaults to nil.

Returns:

  • (String, nil) —

    the current value of secret_access_key



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

def secret_access_key
  @secret_access_key
end

#session_token ⇒ String? (readonly)

AWS secret token credential. Defaults to nil.

Returns:

  • (String, nil) —

    the current value of session_token



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

def session_token
  @session_token
end

#signer ⇒ Object (readonly)

The request signer. Defaults to a default request signer implementation.

Returns:

  • (Object) —

    the current value of signer



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

def signer
  @signer
end

#simple_db_consistent_reads ⇒ Boolean (readonly)

Determines if all SimpleDB read requests should be done consistently. Consistent reads are slower, but reflect all changes to SDB. Defaults to false.

Returns:

  • (Boolean) —

    the current value of simple_db_consistent_reads



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

def simple_db_consistent_reads
  @simple_db_consistent_reads
end

#simple_db_endpoint ⇒ String (readonly)

The service endpoint for Amazon SimpleDB. Defaults to ‘sdb.amazonaws.com’.

Returns:

  • (String) —

    the current value of simple_db_endpoint



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

def simple_db_endpoint
  @simple_db_endpoint
end

#simple_email_service_endpoint ⇒ String (readonly)

The service endpoint for Amazon Simple Email Service. Defaults to ‘email.us-east-1.amazonaws.com’.

Returns:

  • (String) —

    the current value of simple_email_service_endpoint



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

def simple_email_service_endpoint
  @simple_email_service_endpoint
end

#sns_endpoint ⇒ String (readonly)

The service endpoint for Amazon SNS. Defaults to ‘sns.us-east-1.amazonaws.com’.

Returns:

  • (String) —

    the current value of sns_endpoint



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

def sns_endpoint
  @sns_endpoint
end

#sqs_endpoint ⇒ String (readonly)

The service endpoint for Amazon SQS. Defaults to ‘sqs.us-east-1.amazonaws.com’.

Returns:

  • (String) —

    the current value of sqs_endpoint



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

def sqs_endpoint
  @sqs_endpoint
end

#ssl_ca_file ⇒ String (readonly)

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.

Returns:

  • (String) —

    the current value of ssl_ca_file



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

def ssl_ca_file
  @ssl_ca_file
end

#ssl_verify_peer ⇒ Boolean (readonly)

When true the HTTP handler validate server certificates for HTTPS requests. Defaults to true.

This option should only be disabled 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:

  • (Boolean) —

    the current value of ssl_verify_peer



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

def ssl_verify_peer
  @ssl_verify_peer
end

#sts_endpoint ⇒ String (readonly)

The service endpoint for AWS Security Token Service. Defaults to ‘sts.amazonaws.com’.

Returns:

  • (String) —

    the current value of sts_endpoint



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

def sts_endpoint
  @sts_endpoint
end

#stub_requests ⇒ Boolean (readonly)

When true requests are not sent to AWS, instead empty reponses are generated and returned to each service request.

Returns:

  • (Boolean) —

    the current value of stub_requests



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

def stub_requests
  @stub_requests
end

#use_ssl ⇒ Boolean (readonly)

When true, all requests to AWS are sent using HTTPS instead vanilla HTTP. Defaults to true.

Returns:

  • (Boolean) —

    the current value of use_ssl



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

def use_ssl
  @use_ssl
end

#user_agent_prefix ⇒ String (readonly)

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. Defaults to nil.

Returns:

  • (String) —

    the current value of user_agent_prefix



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

def user_agent_prefix
  @user_agent_prefix
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql

Returns true if the two configuration objects have the same values.

Returns:

  • (Boolean) —

    Returns true if the two configuration objects have the same values.



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

def == other
  other.is_a?(self.class) and self.supplied == other.supplied
end

#to_h ⇒ Hash

Returns a hash of all configuration values.

Returns:

  • (Hash) —

    Returns a hash of all configuration values.



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

def to_h
  self.class.accepted_options.inject({}) do |h,k|
    h[k] = send(k)
    h
  end
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) — default: nil —

    AWS access key id credential.

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

    The service endpoint for Amazon EC2.

  • :http_handler (Object) — default: AWS::HTTPartyHandler —

    The http handler that sends requests to AWS.

  • :iam_endpoint (String) — default: 'iam.amazonaws.com' —

    The service endpoint for AWS Idenity Access Management (IAM).

  • :logger (Object, nil) — 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.

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

  • :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 for Amazon S3.

  • :s3_multipart_max_parts (Integer) — default: 1000 —

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

  • :s3_multipart_threshold (Integer) — default: 16777216 —

    When uploading data to S3, if the number of bytes to send exceedes :s3_multipart_threshold then a multi part session is automatically started and the data is sent up in chunks. The size of each part is specified by :s3_multipart_min_part_size. Defaults to 16777216 (16MB).

  • :s3_multipart_min_part_size (Integer) — default: 5242880 —

    The absolute minimum size (in bytes) each S3 multipart segment should be. Defaults to 5242880 (5MB).

  • :secret_access_key (String) — default: nil —

    AWS secret access key credential.

  • :session_token (String, nil) — default: nil —

    AWS secret token credential.

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

    The service endpoint for Amazon SimpleDB.

  • :simple_db_consistent_reads (Boolean) — default: false —

    Determines if all SimpleDB read requests should be done consistently. Consistent reads are slower, but reflect all changes to SDB.

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

    The service endpoint for Amazon Simple Email Service.

  • :signer (Object) — default: AWS::DefaultSigner —

    The request signer. Defaults to a default request signer implementation.

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

  • :ssl_verify_peer (Boolean) — default: true —

    When true the HTTP handler validate server certificates for HTTPS requests.

    This option should only be disabled 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.

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

    The service endpoint for Amazon SNS.

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

    The service endpoint for Amazon SQS.

  • :sts_endpoint (String) — default: 'sts.amazonaws.com' —

    The service endpoint for AWS Security Token Service.

  • :use_ssl (Boolean) — default: true —

    When true, all requests to AWS are sent using HTTPS instead vanilla HTTP.

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



205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/aws/configuration.rb', line 205

def with options = {}

  # symbolize option keys
  options = options.inject({}) {|h,kv| h[kv.first.to_sym] = kv.last; h }

  values = supplied.merge(options)

  if supplied == values
    self # nothing changed
  else
    self.class.new(values.merge(:__created__ => @created.dup))
  end

end