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::<service identifier>::Client. For example, Aws::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:

Aws.config

To provide global configuration within your code for all AWS classes, use Aws.config that is available in the 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 <service identifier> can be identified by looking at the name of the corresponding AWS SDK for Ruby gem name, and using the suffix that follows "aws-sdk-". For example:

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.

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.

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.