The Wayback Machine - https://web.archive.org/web/20160610174753/http://docs.aws.amazon.com/sdk-for-ruby/latest/DeveloperGuide/aws-ruby-sdk-getting-started.html
Menu
Sign In to the Console
AWS SDK for Ruby
Developer Guide (Version v2.4)

Getting Started with the AWS SDK for Ruby

If you’re new to the AWS SDK for Ruby, you should start here. This section contains information about installing, setting up, and using the SDK to create a Ruby application to access Amazon S3.

Installing the AWS SDK for Ruby

This section includes prerequisites and installation instructions.

Prerequisites

Before you can install the AWS SDK for Ruby, you will need an AWS account and Ruby version 1.9 or later.

If you do not have an AWS account, use the following procedure to create one.

To sign up for AWS

  1. Open http://aws.amazon.com/ and choose Create an AWS Account.

  2. Follow the online instructions.

If your project uses Bundler, add the following line to your Gemfile to add the AWS SDK for Ruby to your project:

gem aws-sdk

If you do not use Bundler, the easiest way to install the SDK is to use RubyGems. To install the latest version of the SDK, use the following command: 

gem install aws-sdk

If the previous command fails on your Unix-based system, use sudo to install the SDK, as shown in the following command:

sudo gem install aws-sdk

Configuring the AWS SDK for Ruby

This section describes how to configure the AWS SDK for Ruby. To use the SDK, you must set the AWS region and either set AWS credentials or create an AWS STS access token.

Setting AWS Credentials

Before you can use the AWS SDK for Ruby to make a call to an AWS service, you must set the AWS access credentials that will be used by the AWS SDK for Ruby to verify your access to AWS services and resources. You can set credentials in a number of ways.

The AWS SDK for Ruby searches for credentials in the following order.

The following sections describe how to set credentials, starting with the most flexible approach. For more information about AWS credentials and recommended approaches for credential management, see AWS Security Credentials in the AWS General Reference.

Setting Shared Credentials

Set shared credentials in the AWS credentials profile file on your local system.

On Unix-based systems, such as Linux or OS X, this file is located in the following location:

~/.aws/credentials

On Windows, this file is located in the following location:

%HOMEPATH%\.aws\credentials

This file must have the following format, where default is the name of the default configuration profile given to these credentials, your_access_key_id is the value of your access key, and your_secret_access_key is the value of your secret access key.

[default]
aws_access_key_id = your_access_key_id
aws_secret_access_key = your_secret_access_key

Setting Credentials Using Environment Variables

Set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Use the export command to set these variables on a Unix-based systems, such as Linux or OS X. The following example sets the value of your access key to your_access_key_id and the value of your secret access key to your_secret_access_key.

export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key

To set these variables on Windows, use the set command, as shown in the following example.

set AWS_ACCESS_KEY_ID=your_access_key_id
set AWS_SECRET_ACCESS_KEY=your_secret_access_key

Setting Credentials Using Aws.config

Set the credentials in your code by adding values to the Aws.config hash.

The following example sets the value of your access key to your_access_key_id and the value of your secret access key to your_secret_access_key. Any client or resource you create subsequently will use these credentials.

Aws.config({
  :access_key_id => 'your_access_key',
  :secret_access_key => 'your_secret_access_key'
})

Setting Credentials in a Client Object

Set the credentials in your code by specifying them when you create an AWS client.

The following example creates an S3 client using the access key your_access_key_id and the secret access key your_secret_access_key.

s3 = Aws::S3::Client.new(
  access_key_id: creds['your_access_key_id'],
  secret_access_key: creds['your_secret_access_key']
)

Setting Credentials Using IAM

For an Amazon EC2 instance, create an IAM role, and then give your Amazon EC2 instance access to that role. For more information, see IAM Roles for Amazon EC2 in the Amazon EC2 User Guide.

Creating an AWS STS Access Token

Use the Aws::AssumeRoleCredentials method to create an AWS STS access token .

The following example uses an access token to create an 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)

Setting a Region

You need to set a region when using most AWS services. The AWS region can be set in ways similar to setting your AWS credentials. The AWS SDK for Ruby searches for a region in the following order.

The rest of this section describes how to set a region, starting with the most flexible approach.

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 OS X. 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 Using 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 you subsequently create 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 S3 resource object in the us-west-1 region:

s3 = Aws::S3::Resource.new(region: 'us-west-1')

Setting a Non-Standard Endpoint

If you need to use a non-standard endpoint in the region you've selected, add an endpoint entry to Aws.config or set the endpoint: when creating a service client or resource object. The following example creates an S3 resource object in the other_endpoint endpoint:

s3 = Aws::S3::Resource.new(endpoint: other_endpoint)

Using the AWS SDK for Ruby REPL

This section is for developers who want to use aws.rb, the interactive command-line read-evaluate-print loop (REPL) console tool that is part of the aws-sdk-core gem.

Although aws.rb works with the Interactive Ruby Shell (irb), we recommend that you install pry, which provides a more powerful REPL environment.

Use the following command to install pry:

gem install pry

To use aws.rb, invoke it in a console window, as shown in one of the following two command lines. 

aws.rb
aws.rb -v

The second command line invokes the REPL with extensive HTTP wire logging, which provides information about the communication between the AWS SDK for Ruby and AWS. It also adds overhead and thus slows down the running of your code, so use it with caution.

The REPL defines a helper object for every service class. Downcase the service module name to get the name of the helper object. For example, the names of the Amazon S3 and Amazon EC2 helper objects are s3 and ec2, respectively.

Using the SDK with Ruby on Rails

Ruby on Rails provides a web development framework for Ruby that makes it easy to create websites with Ruby.

The AWS SDK for Ruby provides a gem to enable easy integration with Rails. You can use AWS Elastic Beanstalk, AWS OpsWorks, or AWS CodeDeploy to deploy and run your Rails applications on the AWS cloud.

Integrating the AWS SDK for Ruby with Rails

AWS provides a gemfile, aws-sdk-rails, that supports integration of the AWS SDK for Ruby with Rails. You can view its GitHub repository at https://github.com/aws/aws-sdk-rails.

Add the gem to your application’s Gemfile, as shown in the following example.

gem 'aws-sdk-rails'

The gem includes the AWS SDK for Ruby, so adding the gem is all you need to do to add AWS support to your Rails application.

Amazon SES Support for ActionMailer

When you use the aws-sdk-rails gem in a config/environments file of your Rails project (for example, config/environments/production.rb), you can use Amazon Simple Email Service (Amazon SES) as the back end for the ActionMailer class, as shown in the following example. 

config.action_mailer.delivery_method = :aws_sdk

For more information about ActionMailer, see the Action Mailer Basics on the Ruby on Rails website.

Logging

The aws-sdk-rails gem configures the SDK logger to use Rails.logger.

The gem also configures the SDK log messages to use the :info log level. You can change the log level by setting :log_level in the Aws.config hash. The following example sets the log level to :debug.

Aws.config.update({log_level: :debug})