AWS SDK for Ruby - Version 3

Links of Interest

• API Documentation
• Developer Guide
• V3 Upgrading Guide
• AWS Developer Blog
• Github Discussions

Installation

The AWS SDK for Ruby is available from RubyGems. With V3 modularization, you should pick the specific AWS service gems to install.

gem 'aws-sdk-s3', '~> 1'
gem 'aws-sdk-ec2', '~> 1'

Alternatively, the aws-sdk gem contains every available AWS service gem. This gem is very large; it is recommended to use it only as a quick way to migrate from V2 or if you depend on many AWS services.

gem 'aws-sdk', '~> 3'

Please use a pessimistic version constraint on the major version when depending on service gems.

Configuration

You will need to configure credentials and a region, either in configuration files or environment variables, to make API calls. It is recommended that you provide these via your environment. This makes it easier to rotate credentials and it keeps your secrets out of source control.

The SDK searches the following locations for credentials:

• ENV['AWS_ACCESS_KEY_ID'] and ENV['AWS_SECRET_ACCESS_KEY']
• The shared credentials ini file at ~/.aws/credentials. The location used can be changed with the AWS_CREDENTIALS_FILE ENV variable.
  • Credential options supported in this file are:
    • Static Credentials (aws_access_key_id, aws_secret_access_key, aws_session_token)
    • Assume Role Web Identity Credentials (web_identity_token_file, role_arn, source_profile)
    • Assume Role Credentials (role_arn, source_profile)
    • Process Credentials (credential_process)
    • SSO Credentials (sso_session, sso_account_id, sso_role_name, sso_region)
  • Unless ENV['AWS_SDK_CONFIG_OPT_OUT'] is set, the shared configuration ini file at ~/.aws/config will also be parsed for credentials.
• From an instance profile when running on EC2 or from the ECS credential provider when running in an ECS container with that feature enabled.

Shared configuration is loaded only a single time, and credentials are provided statically at client creation time. Shared credentials do not refresh.

The SDK searches the following locations for a region:

• ENV['AWS_REGION']
• ENV['AMAZON_REGION']
• ENV['AWS_DEFAULT_REGION']
• Unless ENV['AWS_SDK_CONFIG_OPT_OUT'] is set, the shared configuration files (~/.aws/credentials and ~/.aws/config) will also be checked for a region selection.

The region is used to construct an SSL endpoint. If you need to connect to a non-standard endpoint, you may specify the :endpoint option.

Configuration Options

You can also configure default credentials and the region via the Aws.config hash. The Aws.config hash takes precedence over environment variables.

require 'aws-sdk-core'

Aws.config.update(
  region: 'us-west-2',
  credentials: Aws::Credentials.new('akid', 'secret')
)

Valid region and credentials options are:

• :region - A string like us-west-2. See this page for a list of supported regions by service.
• :credentials - An instance of one of the following classes:
  • Aws::Credentials
  • Aws::AssumeRoleWebIdentityCredentials
  • Aws::AssumeRoleCredentials
  • Aws::SharedCredentials
  • Aws::SSOCredentials
  • Aws::LoginCredentials
  • Aws::ProcessCredentials
  • Aws::InstanceProfileCredentials
  • Aws::ECSCredentials
  • Aws::CognitoIdentityCredentials

You may also pass configuration options directly to Client and Resource constructors. These options take precedence over the environment and Aws.config defaults. A :profile Client option can also be used to choose a specific profile defined in your configuration file.

# using a credentials object
ec2 = Aws::EC2::Client.new(region: 'us-west-2', credentials: credentials)

# using a profile name
ec2 = Aws::EC2::Client.new