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(profile: 'my_profile')

Please take care to never commit credentials to source control. We strongly recommended loading credentials from an external source.

require 'aws-sdk'
require 'json'

creds = JSON.load(File.read('secrets.json'))
Aws.config[:credentials] = Aws::Credentials.new(
  creds['AccessKeyId'],
  creds['SecretAccessKey']
)

For more information on how to configure credentials, see the developer guide for configuring AWS SDK for Ruby.

API Clients

Construct a service client to make API calls. Each client provides a 1-to-1 mapping of methods to API operations. Refer to the API documentation for a complete list of available methods.

# list buckets in Amazon S3
s3 = Aws::S3::Client.new
resp = s3.list_buckets
resp.buckets.map(&:name)
#=> ["bucket-1", "bucket-2", ...]

API methods accept a hash of additional request parameters and return structured response data.

# list the first two objects in a bucket
resp = s3.list_objects(bucket: 'aws-sdk', max_keys: 2)
resp.contents.each do |object|
  puts "#{object.key} => #{object.etag}"
end

Paging Responses

Many AWS operations limit the number of results returned with each response. To make it easy to get the next page of results, every AWS response object is enumerable:

# yields one response object per API call made, this will enumerate
# EVERY object in the named bucket
s3.list_objects(bucket:'aws-sdk').each do |response|
  puts response.contents.map(&:key)
end

If you prefer to control paging yourself, response objects have helper methods that control paging:

# make a request that returns a truncated response
resp = s3.list_objects(bucket: 'aws-sdk')

resp.last_page? #=> false
resp.next_page? #=> true
resp = resp.next_page # send a request for the next response page
resp = resp.next_page until resp.last_page?

Waiters

Waiters are utility methods that poll for a particular state. To invoke a waiter, call #wait_until on a client:

begin
  ec2.wait_until(:instance_running, instance_ids:['i-12345678'])
  puts "instance running"
rescue Aws::Waiters::Errors::WaiterFailed => error
  puts "failed waiting for instance running: #{error.message}"
end

Waiters have sensible default polling intervals and maximum attempts. You can configure these per call to #wait_until. You can also register callbacks that are triggered before each polling attempt and before waiting. See the API documentation for more examples and for a list of supported waiters per service.

Resource Interfaces

Resource interfaces are object oriented classes that represent actual resources in AWS. Resource interfaces built on top of API clients and provide additional functionality.

Only a few services implement a resource interface. They are defined by hand in JSON and have limitations. Please use the Client API instead.

s3 = Aws::S3::Resource.new

# reference an existing bucket by name
bucket = s3.bucket('aws-sdk')

# enumerate every object in a bucket
bucket.objects.each do |obj|
  puts "#{obj.key} => #{obj.etag}"
end

# batch operations, delete objects in batches of 1k
bucket.objects(prefix: '/tmp-files/').delete

# single object operations
obj = bucket.object('hello')
obj.put(body:'Hello World!')
obj.etag
obj.delete

REPL - AWS Interactive Console

The aws-sdk gem ships with a REPL that provides a simple way to test the Ruby SDK. You can access the REPL by running aws-v3.rb from the command line.

$ aws-v3.rb
[1] pry(Aws)> ec2.describe_instances.reservations.first.instances.first
[Aws::EC2::Client 200 0.216615 0 retries] describe_instances()
<struct
 instance_id="i-1234567",
 image_id="ami-7654321",
 state=<struct  code=16, name="running">,
 ...>

You can enable HTTP wire logging by setting the verbose flag:

$ aws-v3.rb -v

In the REPL, every service class has a helper that returns a new client object. Simply downcase the service module name for the helper:

• s3 => #<Aws::S3::Client>
• ec2 => #<Aws::EC2::Client>
• etc

Functionality requiring AWS Common Runtime (CRT)

The AWS SDK for Ruby has optional functionality that requires the AWS Common Runtime (CRT) bindings to be included as a dependency with your application. This functionality includes: * CRC-32c support for S3 Additional Checksums

AWS CRT bindings are in developer preview and are available in the the aws-crt gem. You can install them by adding the aws-crt gem to your Gemfile.

Getting Help

Please use any of these resources for getting help:

• Ask a question on Github Discussions.
• Ask a question on StackOverflow and tag it with aws-sdk-ruby.
• Open a support ticket with AWS Support.

Maintenance and support for SDK major versions

For information about maintenance and support for SDK major versions and their underlying dependencies, see the following in the AWS SDKs and Tools Shared Configuration and Credentials Reference Guide:

• AWS SDKs and Tools Maintenance Policy
• AWS SDKs and Tools Version Support Matrix

Opening Issues

If you encounter a bug or have a feature request, we would like to hear about it. Search the existing issues and try to make sure your problem doesn’t already exist before opening a new issue.

The GitHub issues are intended for bug reports and feature requests. For help and questions with using aws-sdk-ruby please make use of the resources listed in the Getting Help section.

Versioning

This project uses semantic versioning. You can safely express a dependency on a major version and expect all minor and patch versions to be backwards compatible.

A CHANGELOG can be found at each gem's root path (i.e. aws-sdk-s3 can be found at gems/aws-sdk-s3/CHANGELOG.md). The CHANGELOG is also accessible via the RubyGems.org page under "LINKS" section.

Supported Services

Service Name	Service Module	gem_name	API Version
ARC - Region switch	Aws::ARCRegionswitch	aws-sdk-arcregionswitch	2022-07-26
AWS AI Ops	Aws::AIOps	aws-sdk-aiops	2018-05-10
AWS ARC - Zonal Shift	Aws::ARCZonalShift	aws-sdk-arczonalshift	2022-10-30
AWS Account	Aws::Account	aws-sdk-account	2021-02-01
AWS Amplify	Aws::Amplify	aws-sdk-amplify	2017-07-25
AWS Amplify UI Builder	Aws::AmplifyUIBuilder	aws-sdk-amplifyuibuilder	2021-08-11
AWS App Mesh	Aws::AppMesh	aws-sdk-appmesh	2019-01-25
AWS App Runner	Aws::AppRunner	aws-sdk-apprunner	2020-05-15
AWS AppConfig Data	Aws::AppConfigData	aws-sdk-appconfigdata	2021-11-11
AWS AppSync	Aws::AppSync	aws-sdk-appsync	2017-07-25
AWS Application Cost Profiler	Aws::ApplicationCostProfiler	aws-sdk-applicationcostprofiler	2020-09-10
AWS Application Discovery Service	Aws::ApplicationDiscoveryService	aws-sdk-applicationdiscoveryservice	2015-11-01
AWS Artifact	Aws::Artifact	aws-sdk-artifact	2018-05-10
AWS Audit Manager	Aws::AuditManager	aws-sdk-auditmanager	2017-07-25
AWS Auto Scaling Plans	Aws::AutoScalingPlans	aws-sdk-autoscalingplans	2018-01-06
AWS B2B Data Interchange	Aws::B2bi	aws-sdk-b2bi	2022-06-23
AWS Backup	Aws::Backup	aws-sdk-backup	2018-11-15
AWS Backup Gateway	Aws::BackupGateway	aws-sdk-backupgateway	2021-01-01
AWS Backup Search	Aws::BackupSearch	aws-sdk-backupsearch	2018-05-10
AWS Batch	Aws::Batch	aws-sdk-batch	2016-08-10
AWS Billing	Aws::Billing	aws-sdk-billing	2023-09-07
AWS Billing and Cost Management Dashboards	Aws::BCMDashboards	aws-sdk-bcmdashboards	2025-08-18
AWS Billing and Cost Management Data Exports	Aws::BCMDataExports	aws-sdk-bcmdataexports	2023-11-26
AWS Billing and Cost Management Pricing Calculator	Aws::BCMPricingCalculator	aws-sdk-bcmpricingcalculator	2024-06-19
AWS Billing and Cost Management Recommended Actions	Aws::BCMRecommendedActions	aws-sdk-bcmrecommendedactions	2024-11-14
AWS Budgets	Aws::Budgets	aws-sdk-budgets	2016-10-20
AWS Certificate Manager	Aws::ACM	aws-sdk-acm	2015-12-08
AWS Certificate Manager Private Certificate Authority	Aws::ACMPCA	aws-sdk-acmpca	2017-08-22
AWS Chatbot	Aws::Chatbot	aws-sdk-chatbot	2017-10-11
AWS Clean Rooms ML	Aws::CleanRoomsML	aws-sdk-cleanroomsml	2023-09-06
AWS Clean Rooms Service	Aws::CleanRooms	aws-sdk-cleanrooms	2022-02-17
AWS Cloud Control API	Aws::CloudControlApi	aws-sdk-cloudcontrolapi	2021-09-30
AWS Cloud Map	Aws::ServiceDiscovery	aws-sdk-servicediscovery	2017-03-14
AWS Cloud9	Aws::Cloud9	aws-sdk-cloud9	2017-09-23
AWS CloudFormation	Aws::CloudFormation	aws-sdk-cloudformation	2010-05-15
AWS CloudHSM V2	Aws::CloudHSMV2	aws-sdk-cloudhsmv2	2017-04-28
AWS CloudTrail	Aws::CloudTrail	aws-sdk-cloudtrail	2013-11-01
AWS CloudTrail Data Service	Aws::CloudTrailData	aws-sdk-cloudtraildata	2021-08-11
AWS CodeBuild	Aws::CodeBuild	aws-sdk-codebuild	2016-10-06
AWS CodeCommit	Aws::CodeCommit	aws-sdk-codecommit	2015-04-13
AWS CodeConnections	Aws::CodeConnections	aws-sdk-codeconnections	2023-12-01
AWS CodeDeploy	Aws::CodeDeploy	aws-sdk-codedeploy	2014-10-06
AWS CodePipeline	Aws::CodePipeline	aws-sdk-codepipeline	2015-07-09
AWS CodeStar Notifications	Aws::CodeStarNotifications	aws-sdk-codestarnotifications	2019-10-15
AWS CodeStar connections	Aws::CodeStarconnections	aws-sdk-codestarconnections	2019-12-01
AWS Comprehend Medical	Aws::ComprehendMedical	aws-sdk-comprehendmedical	2018-10-30
AWS Compute Optimizer	Aws::ComputeOptimizer	aws-sdk-computeoptimizer	2019-11-01
AWS Config	Aws::ConfigService	aws-sdk-configservice