AWS Developer Tools Blog

AWS SDK for Ruby Modularization (Version 3)

Version 3 of the AWS SDK for Ruby is available now as a preview release. This version modularizes the monolithic SDK into service specific gems. Aside from gem packaging differences, version 3 interfaces are backwards compatible with version 2.

You can install individual gems like so:

$ gem install aws-sdk-s3 --version 1.0.0.rc1

You can install everything using the aws-sdk gem:

$ gem install aws-sdk --version 3.0.0.rc1

To see a complete list of gems, checkout the project README for a list of supported services and gems.

Motivation

Modularization allows us to make some long requested changes to the SDK. Some of these changes were not reasonable when we shipped a single monolithic gem with 75+ services. Some of the primary motivating factors for breaking up the monolith include:

  • To provide better versioning information. When 75+ services share a single gem, it is difficult to communicate when a change is meaningful to a user. We can now use strict semantic versioning for each gem.
  • To improve our ability to deliver AWS API updates continuously. The number of new services and updates has been significantly increasing the frequency with which we update. We want to avoid situations where one update is blocked by an unrelated service. We can now continuously deliver updates per service gem.
  • Remove the usage of Ruby `autoload` statements. When you require a service gem, such as aws-sdk-ec2, all of the code is loaded and ready to use. This should eliminate a large number of thread safety issues that users encounter due to the use of autoload.
  • A large amount of the dynamic runtime has been replaced with code generation. This allows users to reason better about what code is doing, receive better stack traces, improve performance, etc.

What Has Changed?

Our intent for the modularization is to keep SDK interfaces backwards compatible. You may need to modify your gem dependency on the AWS SDK for Ruby. The aws-sdk and aws-sdk-core gems have been bumped to version 3.0 to protect users from package level changes.

* Every service has a gem, such as aws-sdk-s3.
* The aws-sdk-core gem now only contains shared utilities.
* The aws-sdk-resources is obsolete. Service gems contain both client and resource interfaces.
* The aws-sdk gem now has a dependency on 75+ service gems.

Here is a diagram showing the dependencies of the aws-sdk gem across its major versions.

gem-diagram

Why Bump to Version 3?

The version 2 aws-sdk-core gem includes code that defines 75+ service modules and shared utilities. It is important to prevent a service specific gem, such as aws-sdk-s3 and the core gem from both defining the same interfaces.

While we have worked hard to ensure full backwards compatibility in the service interfaces, a small number of private internal interfaces have been removed or changed. For users that have relied on these un-documented interfaces, this will prevent unexpected breaks with a gem update. Some of these changes include:

  • Removed the internal runtime methods Aws.add_service and Aws.service_added. These methods were used by the runtime to detect when a service was autoloaded.
  • Removed the internal Aws::Signers module and the various signature classes therein. These classes were marked with @api private. They are now available as separate gems:
    • aws-sigv4
    • aws-sigv2

Migrating Code From Version 2 to Version 3

Migrating should be very simple. If you depend on aws-sdk, then you do not need to change anything. If you depend on aws-sdk-resources or aws-sdk-core, replace these with a dependency on one of the following:

* aws-sdk ~> 3.0
* Service specific gems, such as aws-sdk-s3 ~> 1.0

You will also need to replace your require statements. You should no longer call require "aws-sdk-resources" or require "aws-sdk-core". A follow-up blog post provides detailed instructions on upgrading.

Questions?

Join us in our Gitter channel with your questions and feedback. The modularized released is currently published as a preview gem (rc1). We would love for you to try things out and to share feedback for these are GA.