AWS SDK for Ruby Rails Plugin

A Ruby on Rails plugin that integrates AWS services with your application using the latest version of AWS SDK For Ruby.

Installation

Add this gem to your Rails project's Gemfile:

gem 'aws-sdk-rails', '~> 5'

This gem also brings in the following AWS gems:

• aws-sdk-core

You will have to ensure that you provide credentials for the SDK to use. See the latest AWS SDK for Ruby Docs for details.

If you're running your Rails application on Amazon EC2, the AWS SDK will check Amazon EC2 instance metadata for credentials to load. Learn more: IAM Roles for Amazon EC2

Features

ActionDispatch DynamoDB Session Storage

See https://github.com/aws/aws-actiondispatch-dynamodb-ruby

ActionMailer delivery with Amazon Simple Email Service

See https://github.com/aws/aws-actionmailer-ses-ruby

ActionMailbox ingress with Amazon Simple Email Service

See https://github.com/aws/aws-actionmailbox-ses-ruby

ActiveJob SQS adapter

See https://github.com/aws/aws-activejob-sqs-ruby

AWS Record Generators

See https://github.com/aws/aws-record-rails

AWS SDK uses the Rails logger

The AWS SDK is configured to use the built-in Rails logger for any SDK log output. The logger is configured to use the :info log level. You can change the log level by setting :log_level in the Aws.config hash.

Aws.config.update(log_level: :debug)

Rails 5.2+ Encrypted Credentials

If you are using Encrypted Credentials, the credentials will be decrypted and loaded under the :aws top level key:

# config/credentials.yml.enc
# viewable with: `bundle exec rails credentials:edit`
aws:
  access_key_id: YOUR_KEY_ID
  secret_access_key: YOUR_ACCESS_KEY
  session_token: YOUR_SESSION_TOKEN
  account_id: YOUR_ACCOUNT_ID

Encrypted Credentials will take precedence over any other AWS Credentials that may exist in your environment (e.g. credentials from profiles set in ~/.aws/credentials).

If you are using ActiveStorage with S3, then you do not need to specify your credentials in your storage.yml configuration because they will be loaded automatically.

AWS SDK eager loading

An initializer will eager load the AWS SDK for you. To enable eager loading, add the following to your config/application.rb:

config.eager_load = true

ActiveSupport Notifications for AWS SDK calls

ActiveSupport::Notifications instrumentation is enabled by default for all AWS SDK calls. Events are published for each client operation call with the following event name: <operation>.<serviceId>.aws. For example, S3's :put_object has an event name of: put_object.S3.aws. The service name will always match the namespace of the service client (e.g. Aws::S3::Client => 'S3'). The payload of the event is the request context.

You can subscribe to these events as you would for other ActiveSupport::Notifications:

ActiveSupport::Notifications.subscribe('put_object.S3.aws') do |name, start, finish, id, payload|
 # process event
end

# Or use a regex to subscribe to all service notifications
ActiveSupport::Notifications.subscribe(/S3[.]aws/) do |name, start, finish, id, payload|
 # process event
end

Elastic Beanstalk ActiveJob processing

Elastic Beanstalk worker environments can be used to run ActiveJob without managing a worker process. To do this, configure the worker to read from the correct SQS queue that you want to process jobs from and set the AWS_PROCESS_BEANSTALK_WORKER_REQUESTS environment variable to true in the worker environment configuration. The SQS Daemon running on the worker sends messages as a POST request to http://localhost/. The aws-sdk-rails middleware will forward each request and parameters to their appropriate jobs. The middleware will only process requests from the SQS daemon and will pass on others and so will not interfere with other routes in your application.

To protect against forgeries, daemon requests will only be processed if they originate from localhost or the Docker host.

Periodic (scheduled) jobs are also supported with this approach. Elastic Beanstalk workers support the addition of a cron.yaml file in the application root to configure this. You can call your jobs from your controller actions or if you name your cron job the same as your job class and set the URL to /, the middleware will automatically call the job.

Example:

version: 1
cron:
 - name: "do some task"
   url: "/scheduled"
   schedule: "0 */12 * * *"
 - name: "SomeJob"
   url: "/"
   schedule: "* * * * *"

and in your controller:

class SomeController < ApplicationController
  def scheduled
    SomeJob.perform_later
  end
end

Will execute cron SomeJob every minute and SomeJob every 12 hours via the /scheduled endpoint.