AWS SDK for Ruby - Version 3

Gem Version Build Status Github forks Github stars

Links of Interest

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:

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:

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:

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 2014-11-12
AWS Control Catalog Aws::ControlCatalog aws-sdk-controlcatalog 2018-05-10
AWS Control Tower Aws::ControlTower aws-sdk-controltower 2018-05-10
AWS Cost Explorer Service Aws::CostExplorer aws-sdk-costexplorer 2017-10-25
AWS Cost and Usage Report Service Aws::CostandUsageReportService aws-sdk-costandusagereportservice 2017-01-06
AWS Data Exchange Aws::DataExchange aws-sdk-dataexchange 2017-07-25
AWS Data Pipeline Aws::DataPipeline aws-sdk-datapipeline 2012-10-29
AWS DataSync Aws::DataSync aws-sdk-datasync 2018-11-09
AWS Database Migration Service Aws::DatabaseMigrationService aws-sdk-databasemigrationservice 2016-01-01
AWS DevOps Agent Service Aws::DevOpsAgent aws-sdk-devopsagent 2026-01-01
AWS Device Farm Aws::DeviceFarm aws-sdk-devicefarm 2015-06-23
AWS Direct Connect Aws::DirectConnect aws-sdk-directconnect 2012-10-25
AWS Directory Service Aws::DirectoryService aws-sdk-directoryservice 2015-04-16
AWS Directory Service Data Aws::DirectoryServiceData aws-sdk-directoryservicedata 2023-05-31
AWS EC2 Instance Connect Aws::EC2InstanceConnect aws-sdk-ec2instanceconnect 2018-04-02
AWS Elastic Beanstalk Aws::ElasticBeanstalk aws-sdk-elasticbeanstalk 2010-12-01
AWS Elemental Inference Aws::ElementalInference aws-sdk-elementalinference 2018-11-14
AWS Elemental MediaConvert Aws::MediaConvert aws-sdk-mediaconvert 2017-08-29
AWS Elemental MediaLive Aws::MediaLive aws-sdk-medialive 2017-10-14
AWS Elemental MediaPackage Aws::MediaPackage aws-sdk-mediapackage 2017-10-12
AWS Elemental MediaPackage VOD Aws::MediaPackageVod aws-sdk-mediapackagevod 2018-11-07
AWS Elemental MediaPackage v2 Aws::MediaPackageV2 aws-sdk-mediapackagev2 2022-12-25
AWS Elemental MediaStore Aws::MediaStore aws-sdk-mediastore 2017-09-01
AWS Elemental MediaStore Data Plane Aws::MediaStoreData aws-sdk-mediastoredata 2017-09-01
AWS End User Messaging Social Aws::SocialMessaging aws-sdk-socialmessaging 2024-01-01
AWS EntityResolution Aws::EntityResolution aws-sdk-entityresolution 2018-05-10
AWS Fault Injection Simulator Aws::FIS aws-sdk-fis 2020-12-01
AWS Free Tier Aws::FreeTier aws-sdk-freetier 2023-09-07
AWS Global Accelerator Aws::GlobalAccelerator aws-sdk-globalaccelerator 2018-08-08
AWS Glue Aws::Glue aws-sdk-glue 2017-03-31
AWS Glue DataBrew Aws::GlueDataBrew aws-sdk-gluedatabrew 2017-07-25
AWS Greengrass Aws::Greengrass aws-sdk-greengrass 2017-06-07
AWS Ground Station Aws::GroundStation aws-sdk-groundstation 2019-05-23
AWS Health APIs and Notifications Aws::Health aws-sdk-health 2016-08-04
AWS Health Imaging Aws::MedicalImaging aws-sdk-medicalimaging 2023-07-19
AWS Identity and Access Management Aws::IAM aws-sdk-iam 2010-05-08
AWS Import/Export Aws::ImportExport aws-sdk-importexport 2010-06-01
AWS Invoicing Aws::Invoicing aws-sdk-invoicing 2024-12-01
AWS IoT Aws::IoT aws-sdk-iot 2015-05-28
AWS IoT Core Device Advisor Aws::IoTDeviceAdvisor aws-sdk-iotdeviceadvisor 2020-09-18
AWS IoT Data Plane Aws::IoTDataPlane aws-sdk-iotdataplane 2015-05-28
AWS IoT FleetWise Aws::IoTFleetWise aws-sdk-iotfleetwise 2021-06-17
AWS IoT Greengrass V2 Aws::GreengrassV2 aws-sdk-greengrassv2 2020-11-30
AWS IoT Jobs Data Plane Aws::IoTJobsDataPlane aws-sdk-iotjobsdataplane 2017-09-29
AWS IoT Secure Tunneling Aws::IoTSecureTunneling aws-sdk-iotsecuretunneling 2018-10-05
AWS IoT SiteWise Aws::IoTSiteWise aws-sdk-iotsitewise 2019-12-02
AWS IoT Things Graph Aws::IoTThingsGraph aws-sdk-iotthingsgraph 2018-09-06
AWS IoT TwinMaker Aws::IoTTwinMaker aws-sdk-iottwinmaker 2021-11-29
AWS IoT Wireless Aws::IoTWireless aws-sdk-iotwireless 2020-11-22
AWS Key Management Service Aws::KMS aws-sdk-kms 2014-11-01
AWS Lake Formation Aws::LakeFormation aws-sdk-lakeformation 2017-03-31
AWS Lambda Aws::Lambda aws-sdk-lambda 2015-03-31
AWS Lambda Core Aws::LambdaCore aws-sdk-lambdacore 2026-04-30
AWS Launch Wizard Aws::LaunchWizard aws-sdk-launchwizard 2018-05-10
AWS License Manager Aws::LicenseManager aws-sdk-licensemanager 2018-08-01
AWS License Manager Linux Subscriptions Aws::LicenseManagerLinuxSubscriptions aws-sdk-licensemanagerlinuxsubscriptions 2018-05-10
AWS License Manager User Subscriptions Aws::LicenseManagerUserSubscriptions aws-sdk-licensemanagerusersubscriptions 2018-05-10
AWS Marketplace Agreement Service Aws::MarketplaceAgreement aws-sdk-marketplaceagreement 2020-03-01
AWS Marketplace Catalog Service Aws::MarketplaceCatalog aws-sdk-marketplacecatalog 2018-09-17
AWS Marketplace Commerce Analytics Aws::MarketplaceCommerceAnalytics aws-sdk-marketplacecommerceanalytics 2015-07-01
AWS Marketplace Deployment Service Aws::MarketplaceDeployment aws-sdk-marketplacedeployment 2023-01-25
AWS Marketplace Discovery Aws::MarketplaceDiscovery aws-sdk-marketplacediscovery 2026-02-05
AWS Marketplace Entitlement Service Aws::MarketplaceEntitlementService aws-sdk-marketplaceentitlementservice 2017-01-11
AWS Marketplace Reporting Service Aws::MarketplaceReporting aws-sdk-marketplacereporting 2018-05-10
AWS MediaConnect Aws::MediaConnect aws-sdk-mediaconnect 2018-11-14
AWS MediaTailor Aws::MediaTailor aws-sdk-mediatailor 2018-04-23
AWS Migration Hub Aws::MigrationHub aws-sdk-migrationhub 2017-05-31
AWS Migration Hub Config Aws::MigrationHubConfig aws-sdk-migrationhubconfig 2019-06-30
AWS Migration Hub Orchestrator Aws::MigrationHubOrchestrator aws-sdk-migrationhuborchestrator 2021-08-28
AWS Migration Hub Refactor Spaces Aws::MigrationHubRefactorSpaces aws-sdk-migrationhubrefactorspaces 2021-10-26
AWS Multi-party Approval Aws::MPA aws-sdk-mpa 2022-07-26
AWS Network Firewall Aws::NetworkFirewall aws-sdk-networkfirewall 2020-11-12
AWS Network Manager Aws::NetworkManager aws-sdk-networkmanager 2019-07-05
AWS Organizations Aws::Organizations aws-sdk-organizations 2016-11-28
AWS Outposts Aws::Outposts aws-sdk-outposts 2019-12-03
AWS Parallel Computing Service Aws::PCS aws-sdk-pcs 2023-02-10
AWS Performance Insights Aws::PI aws-sdk-pi 2018-02-27
AWS Price List Service Aws::Pricing aws-sdk-pricing 2017-10-15
AWS Proton Aws::Proton aws-sdk-proton 2020-07-20
AWS RDS DataService Aws::RDSDataService aws-sdk-rdsdataservice 2018-08-01
AWS Resilience Hub Aws::ResilienceHub aws-sdk-resiliencehub 2020-04-30
AWS Resilience Hub V2 Aws::Resiliencehubv2 aws-sdk-resiliencehubv2 2026-02-17
AWS Resource Access Manager Aws::RAM aws-sdk-ram 2018-01-04
AWS Resource Explorer Aws::ResourceExplorer2 aws-sdk-resourceexplorer2 2022-07-28
AWS Resource Groups Aws::ResourceGroups aws-sdk-resourcegroups 2017-11-27
AWS Resource Groups Tagging API Aws::ResourceGroupsTaggingAPI aws-sdk-resourcegroupstaggingapi 2017-01-26
AWS Route53 Recovery Control Config Aws::Route53RecoveryControlConfig aws-sdk-route53recoverycontrolconfig 2020-11-02
AWS Route53 Recovery Readiness Aws::Route53RecoveryReadiness aws-sdk-route53recoveryreadiness 2019-12-02
AWS S3 Control Aws::S3Control aws-sdk-s3control 2018-08-20
AWS SSM-GUIConnect Aws::SSMGuiConnect aws-sdk-ssmguiconnect 2021-05-01
AWS SSO Identity Store Aws::IdentityStore aws-sdk-identitystore 2020-06-15
AWS SSO OIDC Aws::SSOOIDC aws-sdk-core 2019-06-10
AWS Savings Plans Aws::SavingsPlans aws-sdk-savingsplans 2019-06-28
AWS Secrets Manager Aws::SecretsManager aws-sdk-secretsmanager 2017-10-17
AWS Security Agent Aws::SecurityAgent aws-sdk-securityagent 2025-09-06
AWS Security Token Service Aws::STS aws-sdk-core 2011-06-15
AWS SecurityHub Aws::SecurityHub aws-sdk-securityhub 2018-10-26
AWS Service Catalog Aws::ServiceCatalog aws-sdk-servicecatalog 2015-12-10
AWS Service Catalog App Registry Aws::AppRegistry aws-sdk-appregistry 2020-06-24
AWS Shield Aws::Shield aws-sdk-shield 2016-06-02
AWS Sign-In Service Aws::Signin aws-sdk-core 2023-01-01
AWS Signer Aws::Signer aws-sdk-signer 2017-08-25
AWS Signer Data Plane Aws::SignerData aws-sdk-signerdata 2017-08-25
AWS Single Sign-On Aws::SSO