You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.
Class: AWS::Core::Configuration
- Inherits:
-
Object
- Object
- AWS::Core::Configuration
- 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_retries => 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
-
#access_key_id ⇒ String?
readonly
(nil) AWS access key id credential.
-
#credential_provider ⇒ CredentialProvider::Provider
readonly
Returns the object that is responsible for loading credentials.
-
#dynamo_db_big_decimals ⇒ Boolean
readonly
(true) When
true
, DynamoDB will convert number values returned by DynamoDB::Client from strings to BigDecimal objects. -
#dynamo_db_retry_throughput_errors ⇒ Boolean
readonly
(true) When true, AWS::DynamoDB::Errors::ProvisionedThroughputExceededException errors will be retried.
-
#http_handler ⇒ Object
readonly
The http handler that sends requests to AWS.
-
#http_idle_timeout ⇒ Integer
readonly
The number of seconds a persistent connection is allowed to sit idle before it should no longer be used.
-
#http_open_timeout ⇒ Integer
readonly
The number of seconds before the
http_handler
should timeout while trying to open a new HTTP session. -
#http_read_timeout ⇒ Integer
readonly
The number of seconds before the
http_handler
should timeout while waiting for a HTTP response. -
#http_wire_trace ⇒ Boolean
readonly
When
true
, the http handler will log all wire traces to the:logger
. -
#log_formatter ⇒ LogFormatter
readonly
The log message formatter.
-
#log_level ⇒ Symbol
readonly
(:info) The log level to use when logging every API call.
-
#logger ⇒ Logger?
readonly
(nil) The logging interface.
-
#max_retries ⇒ Integer
readonly
(3) The maximum number of times service errors (500) and throttling errors should be retried.
-
#proxy_uri ⇒ URI?
readonly
(nil) The URI of the proxy to send service requests through.
-
#region ⇒ String
readonly
The AWS region used for requests.
-
#s3_encryption_key ⇒ OpenSSL::PKey::RSA, String
readonly
If this is set, AWS::S3::S3Object #read and #write methods will always perform client-side encryption with this key.
-
#s3_encryption_materials_location ⇒ Symbol
readonly
When set to
:instruction_file
, AWS::S3::S3Object will store encryption materials in a separate object, instead of the object metadata. -
#s3_force_path_style ⇒ Boolean
readonly
(false) When
true
, requests will always use path style. -
#s3_multipart_max_parts ⇒ Integer
readonly
(10000) The maximum number of parts to split a file into when uploading in parts to S3.
-
#s3_multipart_min_part_size ⇒ Integer
readonly
(5242880) The absolute minimum size (in bytes) each S3 multipart segment should be defaults to 5242880 (5MB).
-
#s3_multipart_threshold ⇒ Integer
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. -
#s3_server_side_encryption ⇒ Symbol
readonly
The algorithm to use when encrypting object data on the server side.
-
#secret_access_key ⇒ String?
readonly
(nil) AWS secret access key credential.
-
#session_token ⇒ String?
readonly
(nil) AWS secret token credential.
-
#simple_db_consistent_reads ⇒ Boolean
readonly
(false) Determines if all SimpleDB read requests should be done consistently.
-
#sqs_verify_checksums ⇒ Boolean
readonly
(true) When
true
all SQS operations will check body content against MD5 checksums, raising an exception if there is a mismatch. -
#ssl_ca_file ⇒ String
readonly
The path to a CA cert bundle in PEM format.
-
#ssl_ca_path ⇒ String
readonly
(nil) The path the a CA cert directory.
-
#ssl_cert_store ⇒ String
readonly
(nil).
-
#ssl_verify_peer ⇒ Boolean
readonly
(true) When
true
the HTTP handler validate server certificates for HTTPS requests. -
#stub_requests ⇒ Boolean
readonly
(false) When
true
requests are not sent to AWS, instead empty responses are generated and returned to each service request. -
#use_ssl ⇒ Boolean
readonly
(true) When
true
, all requests to AWS are sent using HTTPS instead vanilla HTTP. -
#user_agent_prefix ⇒ String
readonly
(nil) A string prefix to append to all requests against AWS services.
-
#verify_response_body_content_length ⇒ Boolean
readonly
(true) When
true
all HTTP handlers will perform a check to ensure that response bodies match the content-length specified in the response header, if present.
Class Method Summary collapse
Instance Method Summary collapse
-
#credentials ⇒ Hash
Returns a hash with your configured credentials.
-
#eql?(other) ⇒ Boolean
(also: #==)
Returns true if the two configuration objects have the same values.
-
#initialize(options = {}) ⇒ Configuration
constructor
Creates a new Configuration object.
-
#to_h ⇒ Hash
(also: #to_hash)
Returns a hash of all configuration values.
-
#with(options = {}) ⇒ Configuration
Used to create a new Configuration object with the given modifications.
Constructor Details
#initialize(options = {}) ⇒ Configuration
Creates a new Configuration object.
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 |
# File 'lib/aws/core/configuration.rb', line 217 def initialize = {} @created = .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 = .delete(:signer) [:credential_provider] = signer end .each_pair do |opt_name, value| opt_name = opt_name.to_sym if self.class..include?(opt_name) #if opt_name.to_s =~ /_endpoint$/ # warning = ":#{opt_name} is a deprecated AWS configuration option, " # warning << "use :region instead" # warn(warning) #end supplied[opt_name] = value end end end |
Instance Attribute Details
#access_key_id ⇒ String? (readonly)
(nil) AWS access key id credential.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def access_key_id @access_key_id end |
#credential_provider ⇒ CredentialProvider::Provider (readonly)
Returns the object that is responsible for loading credentials.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def credential_provider @credential_provider end |
#dynamo_db_big_decimals ⇒ Boolean (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).
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def dynamo_db_big_decimals @dynamo_db_big_decimals end |
#dynamo_db_retry_throughput_errors ⇒ Boolean (readonly)
(true) When true, AWS::DynamoDB::Errors::ProvisionedThroughputExceededException errors will be retried.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def dynamo_db_retry_throughput_errors @dynamo_db_retry_throughput_errors end |
#http_handler ⇒ Object (readonly)
The http handler that sends requests to AWS. Defaults to an HTTP handler built on net/http.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def http_handler @http_handler end |
#http_idle_timeout ⇒ Integer (readonly)
The number of seconds a persistent connection is allowed to sit idle before it should no longer be used.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def http_idle_timeout @http_idle_timeout end |
#http_open_timeout ⇒ Integer (readonly)
The number of seconds before
the http_handler
should timeout while trying to open a new HTTP
session.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def http_open_timeout @http_open_timeout end |
#http_read_timeout ⇒ Integer (readonly)
The number of seconds before
the http_handler
should timeout while waiting for a HTTP
response.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def http_read_timeout @http_read_timeout end |
#http_wire_trace ⇒ Boolean (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.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def http_wire_trace @http_wire_trace end |
#log_formatter ⇒ LogFormatter (readonly)
The log message formatter.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def log_formatter @log_formatter end |
#log_level ⇒ Symbol (readonly)
(:info) The log level to use when
logging every API call. Does not set the :logger
's log_level.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def log_level @log_level end |
#logger ⇒ Logger? (readonly)
(nil) The logging interface.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def logger @logger end |
#max_retries ⇒ Integer (readonly)
(3) The maximum number of times service errors (500) and throttling errors should be retried. There is an exponential backoff in between retries, so the more retries the longer it can take to fail.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def max_retries @max_retries end |
#proxy_uri ⇒ URI? (readonly)
(nil) The URI of the proxy to send service requests through.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def proxy_uri @proxy_uri end |
#region ⇒ String (readonly)
The AWS region used for requests. The default is us-east-1
.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def region @region end |
#s3_encryption_key ⇒ OpenSSL::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.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def s3_encryption_key @s3_encryption_key end |
#s3_encryption_materials_location ⇒ Symbol (readonly)
When set to :instruction_file
, AWS::S3::S3Object will store
encryption materials in a separate object, instead of the object
metadata.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def s3_encryption_materials_location @s3_encryption_materials_location end |
#s3_force_path_style ⇒ Boolean (readonly)
(false) When
true
, requests will always use path style. This can be useful
for testing environments.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def s3_force_path_style @s3_force_path_style end |
#s3_multipart_max_parts ⇒ Integer (readonly)
(10000) The maximum number of parts to split a file into when uploading in parts to S3.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def s3_multipart_max_parts @s3_multipart_max_parts end |
#s3_multipart_min_part_size ⇒ Integer (readonly)
(5242880) The absolute minimum size (in bytes) each S3 multipart segment should be defaults to 5242880 (5MB).
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 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 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).
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def s3_multipart_threshold @s3_multipart_threshold end |
#s3_server_side_encryption ⇒ Symbol (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:
- S3::S3Object#write
- S3::S3Object#multipart_upload
- S3::S3Object#copy_from and S3::S3Object#copy_to
- S3::S3Object#presigned_post
- S3::Bucket#presigned_post
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)
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def s3_server_side_encryption @s3_server_side_encryption end |
#secret_access_key ⇒ String? (readonly)
(nil) AWS secret access key credential.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def secret_access_key @secret_access_key end |
#session_token ⇒ String? (readonly)
(nil) AWS secret token credential.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def session_token @session_token end |
#simple_db_consistent_reads ⇒ Boolean (readonly)
(false) Determines if all SimpleDB read requests should be done consistently. Consistent reads are slower, but reflect all changes to SDB.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def simple_db_consistent_reads @simple_db_consistent_reads end |
#sqs_verify_checksums ⇒ Boolean (readonly)
(true)
When true
all SQS operations will check body content against
MD5 checksums, raising an exception if there is a mismatch.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def sqs_verify_checksums @sqs_verify_checksums 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.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def ssl_ca_file @ssl_ca_file end |
#ssl_ca_path ⇒ String (readonly)
(nil) The path the a CA cert directory.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def ssl_ca_path @ssl_ca_path end |
#ssl_cert_store ⇒ String (readonly)
(nil)
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def ssl_cert_store @ssl_cert_store end |
#ssl_verify_peer ⇒ Boolean (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.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def ssl_verify_peer @ssl_verify_peer end |
#stub_requests ⇒ Boolean (readonly)
(false) When true
requests are not
sent to AWS, instead empty responses are generated and returned to
each service request.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def stub_requests @stub_requests end |
#use_ssl ⇒ Boolean (readonly)
(true) When true
, all requests
to AWS are sent using HTTPS instead vanilla HTTP.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def use_ssl @use_ssl end |
#user_agent_prefix ⇒ String (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.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def user_agent_prefix @user_agent_prefix end |
#verify_response_body_content_length ⇒ Boolean (readonly)
(true)
When true
all HTTP handlers will perform a check to ensure
that response bodies match the content-length specified in the
response header, if present. Note that some HTTP handlers will
always do this whether or not this value is true.
212 213 214 |
# File 'lib/aws/core/configuration.rb', line 212 def verify_response_body_content_length @verify_response_body_content_length end |
Class Method Details
.add_service(name, ruby_name, endpoint_prefix) ⇒ Object
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 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 |
# File 'lib/aws/core/configuration.rb', line 379 def add_service name, ruby_name, endpoint_prefix svc = SERVICES[name] svc_opt = svc.method_name ruby_name = svc.old_name add_option(svc_opt, {}) add_option :#{ruby_name}_endpoint" do |config,value| region = config.endpoint_region(svc) endpoint = value endpoint ||= config.send(svc_opt)[:endpoint] endpoint ||= Endpoints.hostname(region, endpoint_prefix) endpoint ||= "#{endpoint_prefix}.#{region}.amazonaws.com" endpoint end add_option(:#{ruby_name}_port") do |config,value| if value value elsif port = config.send(svc_opt)[:port] port else config.use_ssl? ? 443 : 80 end 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| if value value elsif region = config.send(svc_opt)[:region] region else 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 AWS.const_get(name).global_endpoint? ? 'us-east-1' : config.region end end end needs = [ :#{svc_opt}", :#{ruby_name}_endpoint", :#{ruby_name}_port", :#{ruby_name}_region", :credential_provider, :http_handler, :http_read_timeout, :http_continue_timeout, :http_continue_threshold, :log_formatter, :log_level, :logger, :proxy_uri, :max_retries, :stub_requests?, :ssl_verify_peer?, :ssl_ca_file, :ssl_ca_path, :ssl_cert_store, :use_ssl?, :user_agent_prefix, ] create_block = lambda do |config,| = [:#{svc_opt}"] AWS.const_get(name)::Client.new(.merge(:config => config)) end add_option_with_needs :#{ruby_name}_client", needs, &create_block end |
Instance Method Details
#credentials ⇒ Hash
Returns a hash with your configured credentials.
243 244 245 246 247 248 249 250 251 |
# File 'lib/aws/core/configuration.rb', line 243 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.
298 299 300 |
# File 'lib/aws/core/configuration.rb', line 298 def eql? other other.is_a?(self.class) and self.supplied == other.supplied end |
#to_h ⇒ Hash Also known as: to_hash
Returns a hash of all configuration values.
289 290 291 292 293 |
# File 'lib/aws/core/configuration.rb', line 289 def to_h self.class..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)
273 274 275 276 277 278 279 280 281 282 283 284 285 286 |
# File 'lib/aws/core/configuration.rb', line 273 def with = {} # symbolize option keys = .inject({}) {|h,kv| h[kv.first.to_sym] = kv.last; h } values = supplied.merge() if supplied == values self # nothing changed else self.class.new(values.merge(:__created__ => @created.dup)) end end |