Class: AWS::Core::Configuration

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

Overview

A configuration object for AWS interfaces and clients.

Configuring Credentials

In order to do anything with AWS you will need to assign credentials. The simplest method is to assign 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 AWS.config

Instance Attribute Summary collapse

Class Method 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)

    AWS access key id credential.

  • :secret_access_key (String)

    AWS secret access key credential.

  • :session_token (String, nil)

    AWS secret token credential.

  • :auto_scaling_endpoint (String) — default: 'autoscaling.us-east-1.amazonaws.com'

    The service endpoint for Auto Scaling.

  • :cloud_formation_endpoint (String) — default: 'cloudformation.us-east-1.amazonaws.com'

    The service endpoint for AWS CloudFormation.

  • :cloud_front_endpoint (String) — default: 'cloudfront.amazonaws.com'

    The service endpoint for Amazon CloudFront.

  • :cloud_search (String) — default: 'cloudsearch.us-east-1.amazonaws.com'

    The service endpoint for Amazon CloudSearch.

  • :cloud_watch_endpoint (String) — default: 'monitoring.us-east-1.amazonaws.com'

    The service endpoint for Amazon CloudWatch.

  • :dynamo_db_big_decimals (Boolean) — default: true

    When true, DynamoDB will convert number values returned by DynamoDB::Client from strings to BigDecimal objects. If you set this to false, they will be converted from strings into floats (with a potential loss of precision).

  • :dynamo_db_endpoint (String) — default: 'dynamodb.amazonaws.com'

    The service endpoint for Amazon DynamoDB.

  • :dynamo_db_retry_throughput_errors (String) — default: true

    When true, AWS::DynamoDB::Errors::ProvisionedThroughputExceededException errors will be retried.

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

    The service endpoint for Amazon EC2.

  • :elasticache_endpoint (String) — default: 'elasticache.us-east-1.amazonaws.com'
  • :elastic_beanstalk_endpoint (String) — default: 'elasticbeanstalk.us-east-1.amazonaws.com'

    The service endpoint for AWS Elastic Beanstalk.

  • :elastic_transcoder_endpoint (String) — default: 'elastictranscoderbeanstalk.us-east-1.amazonaws.com'

    The service endpoint for Elastic Transcoder.

  • :elb_endpoint (String) — default: 'elasticloadbalancing.us-east-1.amazonaws.com'

    The service endpoint for Elastic Load Balancing.

  • :glacier_endpoint (String) — default: 'glacier.us-east-1.amazonaws.com'

    The service endpoint for Amazon Glacier.

  • :http_handler (Object) — default: AWS::Core::Http::NetHttpHandler

    The http handler that sends requests to AWS.

  • :http_idle_timeout (Integer) — default: 60

    The number of seconds a persistent connection is allowed to sit idle before it should no longer be used.

  • :http_open_timeout (Integer) — default: 15

    The number of seconds before the :http_handler should timeout while trying to open a new HTTP session.

  • :http_read_timeout (Integer) — default: 60

    The number of seconds before the :http_handler should timeout while waiting for a HTTP response.

  • :http_wire_trace (Boolean) — default: false

    When true, the http handler will log all wire traces to the :logger. If a :logger is not configured, then wire traces will be sent to standard out.

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

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

  • :import_export_endpoint (String) — default: 'importexport.amazonaws.com'

    The service endpoint for AWS Import/Export.

  • :logger (Logger, nil) — default: nil

    A logger to send log messages to. Here is an example that logs to standard out.

    require 'logger'
    AWS.config(:logger => Logger.new($stdout))
    
  • :log_level (Symbol) — default: :info

    The level log messages are sent to the logger with (e.g. :notice, :info, :warn, :debug, etc).

  • :log_formatter (Object)

    The log formatter is responsible for building log messages from responses. You can quickly change log formats by providing a pre-configured log formatter.

    AWS.config(:log_formatter => AWS::Core::LogFormatter.colored)
    

    Here is a list of pre-configured log formatters:

    • AWS::Core::LogFormatter.default

    • AWS::Core::LogFormatter.short

    • AWS::Core::LogFormatter.debug

    • AWS::Core::LogFormatter.colored

    You can also create an instance of AWS::Core::LogFormatter with a custom log message pattern. See LogFormatter for a complete list of pattern substitutions.

    pattern = "[AWS :operation :duration] :error_message"
    AWS.config(:log_formatter => AWS::Core::LogFormatter.new(pattern))
    

    Lastly you can pass any object that responds to #format accepting and instance of Response and returns a string.

  • :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')
    
  • :ops_works_endpoint (String) — default: 'opsworks.us-east-1.amazonaws.com'

    The service endpoint for AWS OpsWorks.

  • :redshift_endpoint (String) — default: 'redshift.us-east-1.amazonaws.com'

    The service endpoint for Amazon Redshift.

  • :rds_endpoint (String) — default: 'rds.us-east-1.amazonaws.com'

    The service endpoint for Amazon Relational Database Service (RDS).

  • :route_53_endpoint (String) — default: 'route53.amazonaws.com'

    The service endpoint for Amazon Route 53.

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

    The service endpoint for Amazon S3.

  • :s3_force_path_style (Boolean) — default: false

    When true, requests will always use path style. This can be useful for testing environments.

  • :s3_multipart_max_parts (Integer) — default: 10000

    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 exceeds :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).

  • :s3_server_side_encryption (Symbol) — default: nil

    The algorithm to use when encrypting object data on the server side. The only valid value is :aes256, which specifies that the object should be stored using the AES encryption algorithm with 256 bit keys. Defaults to nil, meaning server side encryption is not used unless specified on each individual call to upload an object. This option controls the default behavior for the following methods:

  • :s3_encryption_key (OpenSSL::PKey::RSA, String) — default: nil

    If this is set, AWS::S3::S3Object #read and #write methods will always perform client-side encryption with this key. The key can be overridden at runtime by using the :encryption_key option. A value of nil means that client-side encryption will not be used.

  • :s3_encryption_materials_location (Symbol) — default: :metadata

    When set to :instruction_file, AWS::S3::S3Object will store encryption materials in a separate object, instead of the object metadata.

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

  • :simple_workflow_endpoint (String) — default: 'swf.us-east-1.amazonaws.com'

    The service endpoint for Amazon Simple Workflow Service.

  • :credential_provider (CredentialProviders::Provider) — default: AWS::Core::CredentialProviders::DefaultProvider.new

    Returns the credential provider. The default credential provider attempts to check for statically assigned credentials, ENV credentials and credentials in the metadata service of EC2.

  • :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_ca_path (String) — default: nil

    The path the a CA cert directory.

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

  • :stub_requests (Boolean) — default: false

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

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

  • :storage_gateway_endpoint (String) — default: 'storagegateway.us-east-1.amazonaws.com'

    The service endpoint for AWS Storage Gateway.

  • :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 requests against AWS services. This should be set for clients and applications built ontop of the aws-sdk gem.



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
# File 'lib/aws/core/configuration.rb', line 278

def initialize options = {}

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

  # :signer is now a deprecated option, this ensures it will still
  # work, but its now preferred to set :credential_provider instead.
  # Credential providers don't have to provide a #sign method.
  if signer = options.delete(:signer)
    options[:credential_provider] = signer
  end

  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

#:storage_gateway_endpointString (readonly)

(‘storagegateway.us-east-1.amazonaws.com’) The service endpoint for AWS Storage Gateway.

Returns:

  • (String)

    the current value of :storage_gateway_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def :storage_gateway_endpoint
  @:storage_gateway_endpoint
end

#access_key_idString? (readonly)

(nil) AWS access key id credential.

Returns:

  • (String, nil)

    the current value of access_key_id



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def access_key_id
  @access_key_id
end

#auto_scaling_endpointString (readonly)

(‘autoscaling.us-east-1.amazonaws.com’) The service endpoint for Auto Scaling.

Returns:

  • (String)

    the current value of auto_scaling_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def auto_scaling_endpoint
  @auto_scaling_endpoint
end

#cloud_formation_endpointString (readonly)

(‘cloudformation.us-east-1.amazonaws.com’) The service endpoint for AWS CloudFormation.

Returns:

  • (String)

    the current value of cloud_formation_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def cloud_formation_endpoint
  @cloud_formation_endpoint
end

#cloud_front_endpointString (readonly)

(‘cloudfront.amazonaws.com’) The service endpoint for Amazon CloudFront.

Returns:

  • (String)

    the current value of cloud_front_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def cloud_front_endpoint
  @cloud_front_endpoint
end

#cloud_searchString (readonly)

(‘cloudsearch.us-east-1.amazonaws.com’) The service endpoint for Amazon CloudSearch.

Returns:

  • (String)

    the current value of cloud_search



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def cloud_search
  @cloud_search
end

#cloud_watch_endpointString (readonly)

(‘monitoring.us-east-1.amazonaws.com’) The service endpoint for Amazon CloudWatch.

Returns:

  • (String)

    the current value of cloud_watch_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def cloud_watch_endpoint
  @cloud_watch_endpoint
end

#credential_providerCredentialProvider::Provider (readonly)

Returns the object that is responsible for loading credentials.

Returns:

  • (CredentialProvider::Provider)

    the current value of credential_provider



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def credential_provider
  @credential_provider
end

#dynamo_db_big_decimalsBoolean (readonly)

(true) When true, DynamoDB will convert number values returned by DynamoDB::Client from strings to BigDecimal objects. If you set this to false, they will be converted from strings into floats (with a potential loss of precision).

Returns:

  • (Boolean)

    the current value of dynamo_db_big_decimals



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def dynamo_db_big_decimals
  @dynamo_db_big_decimals
end

#dynamo_db_endpointString (readonly)

(‘dynamodb.us-east-1.amazonaws.com’) The service endpoint for Amazon DynamoDB.

Returns:

  • (String)

    the current value of dynamo_db_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def dynamo_db_endpoint
  @dynamo_db_endpoint
end

#dynamo_db_retry_throughput_errorsString (readonly)

(true) When true, AWS::DynamoDB::Errors::ProvisionedThroughputExceededException errors will be retried.

Returns:

  • (String)

    the current value of dynamo_db_retry_throughput_errors



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def dynamo_db_retry_throughput_errors
  @dynamo_db_retry_throughput_errors
end

#ec2_endpointString (readonly)

(‘ec2.amazonaws.com’) The service endpoint for Amazon EC2.

Returns:

  • (String)

    the current value of ec2_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def ec2_endpoint
  @ec2_endpoint
end

#elastic_beanstalk_endpointString (readonly)

(‘elasticbeanstalk.us-east-1.amazonaws.com’) The service endpoint for AWS Elastic Beanstalk.

Returns:

  • (String)

    the current value of elastic_beanstalk_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def elastic_beanstalk_endpoint
  @elastic_beanstalk_endpoint
end

#elastic_transcoder_endpointString (readonly)

(‘elastictranscoder.us-east-1.amazonaws.com’) The service endpoint for Elastic Transcoder.

Returns:

  • (String)

    the current value of elastic_transcoder_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def elastic_transcoder_endpoint
  @elastic_transcoder_endpoint
end

#elasticache_endpointString (readonly)

(‘elasticache.us-east-1.amazonaws.com’)

Returns:

  • (String)

    the current value of elasticache_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def elasticache_endpoint
  @elasticache_endpoint
end

#elb_endpointString (readonly)

(‘elasticloadbalancing.us-east-1.amazonaws.com’) The service endpoint for Elastic Load Balancing.

Returns:

  • (String)

    the current value of elb_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def elb_endpoint
  @elb_endpoint
end

#glacier_endpointString (readonly)

(‘glacier.us-east-1.amazonaws.com’) The service endpoint for Amazon Glacier.

Returns:

  • (String)

    the current value of glacier_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def glacier_endpoint
  @glacier_endpoint
end

#http_handlerObject (readonly)

The http handler that sends requests to AWS. Defaults to an HTTP handler built on net/http.

Returns:

  • (Object)

    the current value of http_handler



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def http_handler
  @http_handler
end

#http_idle_timeoutInteger (readonly)

The number of seconds a persistent connection is allowed to sit idle before it should no longer be used.

Returns:

  • (Integer)

    the current value of http_idle_timeout



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def http_idle_timeout
  @http_idle_timeout
end

#http_open_timeoutInteger (readonly)

The number of seconds before the http_handler should timeout while trying to open a new HTTP session.

Returns:

  • (Integer)

    the current value of http_open_timeout



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def http_open_timeout
  @http_open_timeout
end

#http_read_timeoutInteger (readonly)

The number of seconds before the http_handler should timeout while waiting for a HTTP response.

Returns:

  • (Integer)

    the current value of http_read_timeout



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def http_read_timeout
  @http_read_timeout
end

#http_wire_traceBoolean (readonly)

When true, the http handler will log all wire traces to the :logger. If a :logger is not configured, then wire traces will be sent to standard out.

Returns:

  • (Boolean)

    the current value of http_wire_trace



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def http_wire_trace
  @http_wire_trace
end

#iam_endpointString (readonly)

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

Returns:

  • (String)

    the current value of iam_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def iam_endpoint
  @iam_endpoint
end

#import_export_endpointString (readonly)

(‘importexport.amazonaws.com’) The service endpoint for AWS Import/Export.

Returns:

  • (String)

    the current value of import_export_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def import_export_endpoint
  @import_export_endpoint
end

#log_formatterLogFormatter (readonly)

The log message formatter.

Returns:



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def log_formatter
  @log_formatter
end

#log_levelSymbol (readonly)

(:info) The log level.

Returns:

  • (Symbol)

    the current value of log_level



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def log_level
  @log_level
end

#loggerLogger? (readonly)

(nil) The logging interface.

Returns:

  • (Logger, nil)

    the current value of logger



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def logger
  @logger
end

#max_retriesInteger (readonly)

(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.

Returns:

  • (Integer)

    the current value of max_retries



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def max_retries
  @max_retries
end

#ops_works_endpointURI? (readonly)

(‘opsworks.us-east-1.amazonaws.com’) The service endpoint for AWS OpsWorks.

Returns:

  • (URI, nil)

    the current value of ops_works_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def ops_works_endpoint
  @ops_works_endpoint
end

#proxy_uriURI? (readonly)

(nil) The URI of the proxy to send service requests through.

Returns:

  • (URI, nil)

    the current value of proxy_uri



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def proxy_uri
  @proxy_uri
end

#rds_endpointURI? (readonly)

(‘rds.us-east-1.amazonaws.com’) The service endpoint for Amazon Relational Database Service (RDS).

Returns:

  • (URI, nil)

    the current value of rds_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def rds_endpoint
  @rds_endpoint
end

#redshift_endpointURI? (readonly)

(‘redshift.us-east-1.amazonaws.com’) The service endpoint for Amazon Redshift.

Returns:

  • (URI, nil)

    the current value of redshift_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def redshift_endpoint
  @redshift_endpoint
end

#route_53_endpointURI? (readonly)

(‘route53.amazonaws.com’) The service endpoint for Amazon Route 53.

Returns:

  • (URI, nil)

    the current value of route_53_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def route_53_endpoint
  @route_53_endpoint
end

#s3_encryption_keyOpenSSL::PKey::RSA, String (readonly)

If this is set, AWS::S3::S3Object #read and #write methods will always perform client-side encryption with this key. The key can be overridden at runtime by using the :encryption_key option. A value of nil means that client-side encryption will not be used.

Returns:

  • (OpenSSL::PKey::RSA, String)

    the current value of s3_encryption_key



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_encryption_key
  @s3_encryption_key
end

#s3_encryption_materials_locationSymbol (readonly)

When set to :instruction_file, AWS::S3::S3Object will store encryption materials in a separate object, instead of the object metadata.

Returns:

  • (Symbol)

    the current value of s3_encryption_materials_location



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_encryption_materials_location
  @s3_encryption_materials_location
end

#s3_endpointString (readonly)

(‘s3.amazonaws.com’) The service endpoint for Amazon S3.

Returns:

  • (String)

    the current value of s3_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_endpoint
  @s3_endpoint
end

#s3_force_path_styleBoolean (readonly)

(false) When true, requests will always use path style. This can be useful for testing environments.

Returns:

  • (Boolean)

    the current value of s3_force_path_style



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_force_path_style
  @s3_force_path_style
end

#s3_multipart_max_partsInteger (readonly)

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

Returns:

  • (Integer)

    the current value of s3_multipart_max_parts



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_multipart_max_parts
  @s3_multipart_max_parts
end

#s3_multipart_min_part_sizeInteger (readonly)

(5242880) 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



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_multipart_min_part_size
  @s3_multipart_min_part_size
end

#s3_multipart_thresholdInteger (readonly)

(16777216) When uploading data to S3, if the number of bytes to send exceeds :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



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_multipart_threshold
  @s3_multipart_threshold
end

#s3_server_side_encryptionSymbol (readonly)

The algorithm to use when encrypting object data on the server side. The only valid value is :aes256, which specifies that the object should be stored using the AES encryption algorithm with 256 bit keys. Defaults to nil, meaning server side encryption is not used unless specified on each individual call to upload an object. This option controls the default behavior for the following method:

You can construct an interface to Amazon S3 which always stores data using server side encryption as follows:

s3 = AWS::S3.new(:s3_server_side_encryption => :aes256)

Returns:

  • (Symbol)

    the current value of s3_server_side_encryption



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def s3_server_side_encryption
  @s3_server_side_encryption
end

#secret_access_keyString? (readonly)

(nil) AWS secret access key credential.

Returns:

  • (String, nil)

    the current value of secret_access_key



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def secret_access_key
  @secret_access_key
end

#session_tokenString? (readonly)

(nil) AWS secret token credential.

Returns:

  • (String, nil)

    the current value of session_token



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def session_token
  @session_token
end

#simple_db_consistent_readsBoolean (readonly)

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

Returns:

  • (Boolean)

    the current value of simple_db_consistent_reads



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def simple_db_consistent_reads
  @simple_db_consistent_reads
end

#simple_db_endpointString (readonly)

(‘sdb.amazonaws.com’) The service endpoint for Amazon SimpleDB.

Returns:

  • (String)

    the current value of simple_db_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def simple_db_endpoint
  @simple_db_endpoint
end

#simple_email_service_endpointString (readonly)

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

Returns:

  • (String)

    the current value of simple_email_service_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def simple_email_service_endpoint
  @simple_email_service_endpoint
end

#simple_workflow_endpointString (readonly)

(‘swf.us-east-1.amazonaws.com’) The service endpoint for Amazon Simple Workflow Service.

Returns:

  • (String)

    the current value of simple_workflow_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def simple_workflow_endpoint
  @simple_workflow_endpoint
end

#sns_endpointString (readonly)

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

Returns:

  • (String)

    the current value of sns_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def sns_endpoint
  @sns_endpoint
end

#sqs_endpointString (readonly)

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

Returns:

  • (String)

    the current value of sqs_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def sqs_endpoint
  @sqs_endpoint
end

#ssl_ca_fileString (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



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def ssl_ca_file
  @ssl_ca_file
end

#ssl_ca_pathString (readonly)

(nil) The path the a CA cert directory.

Returns:

  • (String)

    the current value of ssl_ca_path



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def ssl_ca_path
  @ssl_ca_path
end

#ssl_verify_peerBoolean (readonly)

(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.

Returns:

  • (Boolean)

    the current value of ssl_verify_peer



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def ssl_verify_peer
  @ssl_verify_peer
end

#sts_endpointString (readonly)

(‘sts.amazonaws.com’) The service endpoint for AWS Security Token Service.

Returns:

  • (String)

    the current value of sts_endpoint



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def sts_endpoint
  @sts_endpoint
end

#stub_requestsBoolean (readonly)

(false) When true requests are not sent to AWS, instead empty responses are generated and returned to each service request.

Returns:

  • (Boolean)

    the current value of stub_requests



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def stub_requests
  @stub_requests
end

#use_sslBoolean (readonly)

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

Returns:

  • (Boolean)

    the current value of use_ssl



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def use_ssl
  @use_ssl
end

#user_agent_prefixString (readonly)

(nil) A string prefix to append to all requests against AWS services. This should be set for clients and applications built on top of the aws-sdk gem.

Returns:

  • (String)

    the current value of user_agent_prefix



273
274
275
# File 'lib/aws/core/configuration.rb', line 273

def user_agent_prefix
  @user_agent_prefix
end

Class Method Details

.add_service(name, ruby_name, default_endpoint) ⇒ Object



427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
# File 'lib/aws/core/configuration.rb', line 427

def add_service name, ruby_name, default_endpoint

  add_option :"#{ruby_name}_endpoint", default_endpoint

  add_option(:"#{ruby_name}_port") do |config,value|
    value || (config.use_ssl? ? 443 : 80)
  end

  # users only need to specify service regions when they use
  # a test endpoint with a sigv4 service
  add_option(:"#{ruby_name}_region") do |config,value|
    value || begin
      endpoint = config.send("#{ruby_name}_endpoint")
      if endpoint =~ /us-gov/
        if matches = endpoint.match(/(us-gov-west-\d+)/)
          matches[1]
        else
          'us-gov-west-1' # e.g. iam.us-gov.amazonaws.com
        end
      elsif matches = endpoint.match(/^.+\.(.+)\.amazonaws.com$/)
        matches[1]
      else
        'us-east-1'
      end
    end
  end

  needs = [
    :"#{ruby_name}_endpoint",
    :"#{ruby_name}_port",
    :"#{ruby_name}_region",
    :credential_provider,
    :http_handler,
    :http_read_timeout,
    :log_formatter,
    :log_level,
    :logger,
    :proxy_uri,
    :max_retries,
    :stub_requests?,
    :ssl_verify_peer?,
    :ssl_ca_file,
    :ssl_ca_path,
    :use_ssl?,
    :user_agent_prefix,
  ]

  create_block = lambda do |config,client_options|
    AWS.const_get(name)::Client.new(:config => config)
  end

  add_option_with_needs :"#{ruby_name}_client", needs, &create_block

end

Instance Method Details

#credentialsHash

Returns a hash with your configured credentials.

Returns:

  • (Hash)

    Returns a hash with your configured credentials.



299
300
301
302
303
304
305
306
307
# File 'lib/aws/core/configuration.rb', line 299

def credentials
  credentials = {}
  [:access_key_id, :secret_access_key, :session_token].each do |opt|
    if value = credential_provider.send(opt)
      credentials[opt] = value
    end
  end
  credentials
end

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

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

Returns:

  • (Boolean)

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



354
355
356
# File 'lib/aws/core/configuration.rb', line 354

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

#to_hHash Also known as: to_hash

Returns a hash of all configuration values.

Returns:

  • (Hash)

    Returns a hash of all configuration values.



345
346
347
348
349
# File 'lib/aws/core/configuration.rb', line 345

def to_h
  self.class.accepted_options.inject({}) do |h,k|
    h.merge(k => send(k))
  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)

    AWS access key id credential.

  • :secret_access_key (String)

    AWS secret access key credential.

  • :session_token (String, nil)

    AWS secret token credential.

  • :auto_scaling_endpoint (String) — default: 'autoscaling.us-east-1.amazonaws.com'

    The service endpoint for Auto Scaling.

  • :cloud_formation_endpoint (String) — default: 'cloudformation.us-east-1.amazonaws.com'

    The service endpoint for AWS CloudFormation.

  • :cloud_front_endpoint (String) — default: 'cloudfront.amazonaws.com'

    The service endpoint for Amazon CloudFront.

  • :cloud_search (String) — default: 'cloudsearch.us-east-1.amazonaws.com'

    The service endpoint for Amazon CloudSearch.

  • :cloud_watch_endpoint (String) — default: 'monitoring.us-east-1.amazonaws.com'

    The service endpoint for Amazon CloudWatch.

  • :dynamo_db_big_decimals (Boolean) — default: true

    When true, DynamoDB will convert number values returned by DynamoDB::Client from strings to BigDecimal objects. If you set this to false, they will be converted from strings into floats (with a potential loss of precision).

  • :dynamo_db_endpoint (String) — default: 'dynamodb.amazonaws.com'

    The service endpoint for Amazon DynamoDB.

  • :dynamo_db_retry_throughput_errors (String) — default: true

    When true, AWS::DynamoDB::Errors::ProvisionedThroughputExceededException errors will be retried.

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

    The service endpoint for Amazon EC2.

  • :elasticache_endpoint (String) — default: 'elasticache.us-east-1.amazonaws.com'
  • :elastic_beanstalk_endpoint (String) — default: 'elasticbeanstalk.us-east-1.amazonaws.com'

    The service endpoint for AWS Elastic Beanstalk.

  • :elastic_transcoder_endpoint (String) — default: 'elastictranscoderbeanstalk.us-east-1.amazonaws.com'

    The service endpoint for Elastic Transcoder.

  • :elb_endpoint (String) — default: 'elasticloadbalancing.us-east-1.amazonaws.com'

    The service endpoint for Elastic Load Balancing.

  • :glacier_endpoint (String) — default: 'glacier.us-east-1.amazonaws.com'

    The service endpoint for Amazon Glacier.

  • :http_handler (Object) — default: AWS::Core::Http::NetHttpHandler

    The http handler that sends requests to AWS.

  • :http_idle_timeout (Integer) — default: 60

    The number of seconds a persistent connection is allowed to sit idle before it should no longer be used.

  • :http_open_timeout (Integer) — default: 15

    The number of seconds before the :http_handler should timeout while trying to open a new HTTP session.

  • :http_read_timeout (Integer) — default: 60

    The number of seconds before the :http_handler should timeout while waiting for a HTTP response.

  • :http_wire_trace (Boolean) — default: false

    When true, the http handler will log all wire traces to the :logger. If a :logger is not configured, then wire traces will be sent to standard out.

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

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

  • :import_export_endpoint (String) — default: 'importexport.amazonaws.com'

    The service endpoint for AWS Import/Export.

  • :logger (Logger, nil) — default: nil

    A logger to send log messages to. Here is an example that logs to standard out.

    require 'logger'
    AWS.config(:logger => Logger.new($stdout))
    
  • :log_level (Symbol) — default: :info

    The level log messages are sent to the logger with (e.g. :notice, :info, :warn, :debug, etc).

  • :log_formatter (Object)

    The log formatter is responsible for building log messages from responses. You can quickly change log formats by providing a pre-configured log formatter.

    AWS.config(:log_formatter => AWS::Core::LogFormatter.colored)
    

    Here is a list of pre-configured log formatters:

    • AWS::Core::LogFormatter.default

    • AWS::Core::LogFormatter.short

    • AWS::Core::LogFormatter.debug

    • AWS::Core::LogFormatter.colored

    You can also create an instance of AWS::Core::LogFormatter with a custom log message pattern. See LogFormatter for a complete list of pattern substitutions.

    pattern = "[AWS :operation :duration] :error_message"
    AWS.config(:log_formatter => AWS::Core::LogFormatter.new(pattern))
    

    Lastly you can pass any object that responds to #format accepting and instance of Response and returns a string.

  • :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')
    
  • :ops_works_endpoint (String) — default: 'opsworks.us-east-1.amazonaws.com'

    The service endpoint for AWS OpsWorks.

  • :redshift_endpoint (String) — default: 'redshift.us-east-1.amazonaws.com'

    The service endpoint for Amazon Redshift.

  • :rds_endpoint (String) — default: 'rds.us-east-1.amazonaws.com'

    The service endpoint for Amazon Relational Database Service (RDS).

  • :route_53_endpoint (String) — default: 'route53.amazonaws.com'

    The service endpoint for Amazon Route 53.

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

    The service endpoint for Amazon S3.

  • :s3_force_path_style (Boolean) — default: false

    When true, requests will always use path style. This can be useful for testing environments.

  • :s3_multipart_max_parts (Integer) — default: 10000

    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 exceeds :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).

  • :s3_server_side_encryption (Symbol) — default: nil

    The algorithm to use when encrypting object data on the server side. The only valid value is :aes256, which specifies that the object should be stored using the AES encryption algorithm with 256 bit keys. Defaults to nil, meaning server side encryption is not used unless specified on each individual call to upload an object. This option controls the default behavior for the following methods:

  • :s3_encryption_key (OpenSSL::PKey::RSA, String) — default: nil

    If this is set, AWS::S3::S3Object #read and #write methods will always perform client-side encryption with this key. The key can be overridden at runtime by using the :encryption_key option. A value of nil means that client-side encryption will not be used.

  • :s3_encryption_materials_location (Symbol) — default: :metadata

    When set to :instruction_file, AWS::S3::S3Object will store encryption materials in a separate object, instead of the object metadata.

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

  • :simple_workflow_endpoint (String) — default: 'swf.us-east-1.amazonaws.com'

    The service endpoint for Amazon Simple Workflow Service.

  • :credential_provider (CredentialProviders::Provider) — default: AWS::Core::CredentialProviders::DefaultProvider.new

    Returns the credential provider. The default credential provider attempts to check for statically assigned credentials, ENV credentials and credentials in the metadata service of EC2.

  • :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_ca_path (String) — default: nil

    The path the a CA cert directory.

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

  • :stub_requests (Boolean) — default: false

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

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

  • :storage_gateway_endpoint (String) — default: 'storagegateway.us-east-1.amazonaws.com'

    The service endpoint for AWS Storage Gateway.

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



329
330
331
332
333
334
335
336
337
338
339
340
341
342
# File 'lib/aws/core/configuration.rb', line 329

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