Configure the AWS SDK for Ruby
Learn how to configure the AWS SDK for Ruby. You must establish how your code authenticates with AWS when you develop with AWS services. You must also set the AWS Region you want to use.
The SDK for Ruby includes client classes that provide interfaces to the AWS services. Each
client class supports a particular AWS service and follows the convention
Aws::
. For
example, <service identifier>
::ClientAws::S3::Client
provides an interface to the Amazon Simple Storage Service service, and Aws::SQS::Client
provides an
interface to the Amazon Simple Queue Service service.
All client classes for all AWS services are thread-safe.
When instantiating a client class, AWS credentials must be supplied. Credentials can be
supplied from your code, the environment, or the shared AWS config
file and shared AWS credentials
file. For
the order that the SDK checks for authentication providers, see Credential provider chain.
The Shared config
and
credentials
files can be used for configuration settings. For all
AWS SDK settings, see the Settings
reference in the AWS SDKs and Tools Reference Guide. Different profiles can
be used to store different configurations. The AWS_PROFILE
environment variable
can be used to specify which profile that the SDK loads. The active profile can also be set
using the profile
option of Aws.config
.
Precedence of settings
Global settings configure features, credential providers, and other functionality that are supported by most SDKs and have a broad impact across AWS services. All AWS SDKs have a series of places (or sources) that they check in order to find a value for global settings. Not all settings are available in all sources. The following is the setting lookup precedence:
-
Any explicit setting set in the code or on a service client itself takes precedence over anything else.
-
Any parameters passed directly into a client constructor take highest precedence.
-
Aws.config
is checked for global or service-specific settings.
-
-
The environment variable is checked.
-
The shared AWS
credentials
file is checked. -
The shared AWS
config
file is checked. -
Any default value provided by the AWS SDK for Ruby source code itself is used last.
Aws.config
To provide global configuration within your code for all AWS classes, use Aws.config
aws-sdk-core
gem.
Aws.config
supports two syntaxes for different uses. Global settings can
either be applied for all AWS services or for a specific service. For the complete list
of supported settings, see the Client
Options
in the AWS SDK for Ruby API Reference.
Global settings through Aws.config
To set service-agnostic settings through Aws.config
, use the following
syntax:
Aws.config[:
<global setting name>
] =<value>
These settings are merged into any created service clients.
Example of a global setting:
Aws.config[:
region
] ='us-west-2'
If you try to use a setting name that is not globally supported, an error is raised when you attempt to create an instance of a type of service that doesn't support it. If this happens, use service-specific syntax instead.
Service-specific settings through
Aws.config
To set service-specific settings through Aws.config
, use the following
syntax:
Aws.config[:
<service identifier>
] = {<global setting name>
:<value>
}
These settings are merged into all created service clients of that service type.
Example of a setting that only applies to Amazon S3:
Aws.config[:
s3
] = {force_path_style
:true
}
The
can be
identified by looking at the name of the corresponding AWS SDK for Ruby gem name<service identifier>
aws-sdk-
". For example:
-
For
aws-sdk-s3
, the service identifier string is "s3
". -
For
aws-sdk-ecs
, the service identifer string is "ecs
".
Credential provider chain
All SDKs have a series of places (or sources) that they check in order to get valid credentials to use to make a request to an AWS service. After valid credentials are found, the search is stopped. This systematic search is called the default credential provider chain.
Note
If you followed the recommended approach for new users to get started, you set up AWS IAM Identity Center authentication during SDK authentication with AWS of the Getting started topic. Other authentication methods are useful for different situations. To avoid security risks, we recommend always using short-term credentials. For other authentication method procedures, see Authentication and access in the AWS SDKs and Tools Reference Guide.
For each step in the chain, there are different ways to set the values. Setting values
directly in code always takes precedence, followed by setting as environment variables, and
then in the shared AWS config
file.
The AWS SDKs and Tools Reference Guide has information on SDK configuration
settings used by all AWS SDKs and the AWS CLI. To learn more about how to configure the SDK
through the shared AWS config
file, see Shared
config and credentials files. To learn more about how to configure the SDK
through setting environment variables, see Environment variables
support.
To authenticate with AWS, the AWS SDK for Ruby checks the credential providers in the order listed in the following table.
Credential provider by precedence | AWS SDKs and Tools Reference Guide | AWS SDK for Ruby API Reference |
---|---|---|
AWS access keys (temporary and long-term credentials) | AWS access keys | |
Web identity token from AWS Security Token Service (AWS STS) | Assume
role credential provider Using |
Aws::AssumeRoleWebIdentityCredentials
|
AWS IAM Identity Center. In this guide, see SDK authentication with AWS. | IAM Identity Center credential provider | Aws::SSOCredentials |
Trusted entity provider (such as AWS_ROLE_ARN ). In this guide,
see Creating an AWS STS access
token. |
Assume
role credential provider Using |
Aws::AssumeRoleCredentials |
Process credential provider | Process credential provider | Aws::ProcessCredentials |
Amazon Elastic Container Service (Amazon ECS) credentials | Container credential provider | Aws::ECSCredentials |
Amazon Elastic Compute Cloud (Amazon EC2) instance profile credentials (IMDS credential provider) | IMDS credential provider | Aws::InstanceProfileCredentials |
If the AWS SDK for Ruby environment variable AWS_SDK_CONFIG_OPT_OUT
is set, the
shared AWS config
file, typically at ~/.aws/config
, will not be parsed for
credentials.
Creating an AWS STS access token
Assuming a role involves using a set of temporary security credentials that you can use
to access AWS resources that you might not normally have access to. These temporary
credentials consist of an access key ID, a secret access key, and a security token. You can
use the Aws::AssumeRoleCredentials
method to create an AWS Security Token Service
(AWS STS) access token.
The following example uses an access token to create an Amazon S3 client object, where
linked::account::arn
is the Amazon Resource Name (ARN) of the role to
assume and session-name
is an identifier for the assumed role session.
role_credentials = Aws::AssumeRoleCredentials.new( client: Aws::STS::Client.new, role_arn: "
linked::account::arn
", role_session_name: "session-name
" ) s3 = Aws::S3::Client.new(credentials: role_credentials)
For more information about setting role_arn
or
role_session_name
, or about setting these using the shared AWS config
file
instead, see Assume
role credential provider in the AWS SDKs and Tools Reference Guide.
Setting a Region
You need to set a Region when using most AWS services. The AWS SDK for Ruby searches for a Region in the following order:
For more information on the region
setting, see AWS Region in the
AWS SDKs and Tools Reference Guide. The rest of this section describes how to
set a Region, starting with the most common approach.
Setting the Region using the
shared config
file
Set the region by setting the region
variable in the shared AWS config
file.
For more information about the shared config
file, see Shared config and credentials files
in the AWS SDKs and Tools Reference Guide.
Example of setting this value in the config
file:
[default] region = us-west-2
The shared config
file is not checked if the environment variable
AWS_SDK_CONFIG_OPT_OUT
is set.
Setting the Region using environment variables
Set the Region by setting the AWS_REGION
environment variable.
Use the export
command to set this variable on Unix-based systems, such
as Linux or macOS. The following example sets the Region to
us-west-2
.
export AWS_REGION=us-west-2
To set this variable on Windows, use the set
command. The following
example sets the Region to us-west-2
.
set AWS_REGION=us-west-2
Setting the Region with
Aws.config
Set the Region by adding a region
value to the Aws.config
hash. The following example updates the Aws.config
hash to use the
us-west-1
Region.
Aws.config.update({region: 'us-west-1'})
Any clients or resources that you create later are bound to this Region.
Setting the Region in a client or resource object
Set the Region when you create an AWS client or resource. The following example
creates an Amazon S3 resource object in the us-west-1
Region. Choose the correct
Region for your AWS resources. A service client object is immutable, so you must
create a new client for each service to which you make requests and for making requests
to the same service using a different configuration.
s3 = Aws::S3::Resource.new(region: 'us-west-1')
Setting a nonstandard endpoint
The region is used to construct an SSL endpoint to use for AWS requests. If you need
to use a nonstandard endpoint in the Region you’ve selected, add an endpoint
entry to Aws.config
. Alternatively, set the endpoint:
when
creating a service client or resource object. The following example creates an Amazon S3
resource object in the other_endpoint
endpoint.
s3 = Aws::S3::Resource.new(endpoint: other_endpoint)
To use an endpoint of your choosing for API requests and to have that choice persist, see the Service-specific endpoints configuration option in the AWS SDKs and Tools Reference Guide.