# aws-sdk-ruby: the modular AWS SDK for Ruby, and when to install the whole thing

> aws/aws-sdk-ruby is the official AWS SDK for Ruby, split into per-service gems under version 3. This review covers how credential resolution and client construction actually work, how to install a single service gem, and the cases where the monolithic aws-sdk gem is the wrong choice.

**aws/aws-sdk-ruby** — The official AWS SDK for Ruby

- Repository: https://github.com/aws/aws-sdk-ruby
- Website: https://aws.amazon.com/sdk-for-ruby/
- Stars: 3,657 · Forks: 1,235
- Language: Ruby
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/aws-aws-sdk-ruby

## The problem aws-sdk-ruby solves, and who ends up depending on it

Every AWS API call is an HTTP request with SigV4 signing, retry behaviour, error parsing and pagination. aws-sdk-ruby exists so Ruby code does not reimplement that per service. The README describes the client as providing a "1-to-1 mapping of methods to API operations", which is the contract: Aws::S3::Client#list_buckets corresponds to the S3 ListBuckets operation, and the response comes back as structured data rather than a raw body.

The intended audience is Ruby application and tooling developers. The version 3 line is built around modularization: you install the service gems you use rather than one package containing every AWS service. That matters for load time and for dependency resolution, because a Rails app that only touches S3 and SQS should not pull in the client for every other service. The README is explicit that the all-in-one gem is "very large" and recommends it "only as a quick way to migrate from V2 or if you depend on many AWS services".

One detail in the repository layout is worth noting: there is a gems/ directory alongside apis/ and services.json. The service gems are generated and versioned from a shared model rather than hand-written one by one, which is why the release history shows a steady stream of dated patch releases such as v2.11.630 through v2.11.632 in November 2020.

## How credential resolution and client construction actually work

The SDK resolves configuration in a defined order, and the README states the precedence plainly: values passed directly to a Client or Resource constructor win, then the Aws.config hash, then environment variables. The README says the Aws.config hash "takes precedence over environment variables", so a stray Aws.config.update call in an initializer silently overrides what you exported in the shell.

Credential lookup walks a fixed list. It checks ENV['AWS_ACCESS_KEY_ID'] and ENV['AWS_SECRET_ACCESS_KEY'] first, then the shared credentials ini file at ~/.aws/credentials, whose location can be moved with the AWS_CREDENTIALS_FILE environment variable. Unless ENV['AWS_SDK_CONFIG_OPT_OUT'] is set, ~/.aws/config is also parsed for credentials. On EC2 the instance profile is used, and in ECS the container credential provider is used when that feature is enabled. The ini file supports static credentials, assume role, assume role with web identity, process credentials and SSO entries, with keys such as role_arn, source_profile, credential_process, sso_session, sso_account_id, sso_role_name and sso_region.

Region resolution is a separate list: ENV['AWS_REGION'], then ENV['AMAZON_REGION'], then ENV['AWS_DEFAULT_REGION'], then the shared files. The README explains why this is not cosmetic: "The region is used to construct an SSL endpoint." A missing or wrong region produces a request to the wrong host, not a clean configuration error. For non-standard endpoints, the :endpoint client option is the documented escape hatch.

The sharpest constraint in the README is about lifetime. It states that shared configuration is loaded only a single time and that credentials are provided statically at client creation time, and then: "Shared credentials do not refresh." If your process outlives your session token, you have to build a new client. That is a design decision, not a bug, but it shapes how you structure long-running workers.

## Installing aws-sdk-ruby v3 and making a first S3 call

The SDK is distributed through RubyGems. For version 3 the README says to pick the specific service gems you need, and to use a pessimistic constraint on the major version. A Gemfile entry for S3 looks like this:

```ruby
gem 'aws-sdk-s3', '~> 1'
gem 'aws-sdk-ec2', '~> 1'
```

The alternative is the aggregate gem, which the README warns is very large and suggests using mainly as a migration path from version 2:

```ruby
gem 'aws-sdk', '~> 3'
```

After bundle install, construct a client. The README's own example lists buckets and maps the names:

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

If your credentials and region are already in the environment or in ~/.aws/credentials, that constructor needs no arguments. To list a bounded number of objects and read the fields back, the README gives this shape:

```ruby
resp = s3.list_objects(bucket: 'aws-sdk', max_keys: 2)
resp.contents.each do |object|
  puts "#{object.key} => #{object.etag}"
end
```

You should see one line per returned object with its key and ETag. If the call fails, check the region before anything else, because the endpoint is derived from it. For a profile-based setup, the README shows passing the profile name directly to the constructor:

```ruby
ec2 = Aws::EC2::Client.new(profile: 'my_profile')
```

Finally, the README is emphatic about not committing secrets, and shows loading them from a file outside source control:

```ruby
require 'aws-sdk'
require 'json'

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

## Where aws-sdk-ruby v3 gets in your way

The static credential lifetime is the limitation most likely to bite. The README does not document an automatic refresh path for shared credentials once a client exists, so a worker that assumes a role for an hour and then keeps running will start failing with expired-token errors. The workaround is to construct clients per unit of work or to use one of the credential classes that performs its own retrieval, but you have to design for that up front. The README does not document rollback or credential-refresh semantics beyond the single statement about static provisioning.

The aggregate gem is a second trap. It is convenient during a version 2 migration and expensive afterwards. Because the README recommends it only for migration or for projects that depend on many services, a codebase that adds aws-sdk for one call and never revisits the decision carries that weight indefinitely.

Configuration precedence is a third source of confusion in real applications. Environment variables, ~/.aws/credentials, ~/.aws/config and Aws.config can all supply a region or credentials, and the README documents that Aws.config wins over the environment. A test suite that sets Aws.config globally can mask a missing AWS_REGION in production, and the failure appears as a request to an unexpected endpoint rather than as a missing-configuration error.

This is also the wrong tool if you are not on Ruby. The README and repository are entirely Ruby-specific, and other language SDKs are separate projects. If you need a thin HTTP layer over a handful of AWS endpoints, or you are targeting a service the SDK does not cover, a hand-rolled signed request may be less machinery than pulling in a client and its credential chain.

## aws-sdk-ruby compared with aws-sdk-core alone

The repository publishes aws-sdk-core as a separate gem, and the badge in the README tracks aws-sdk-core rather than the aggregate. That split is the real alternative within this project: depend on aws-sdk-core and the individual service gems, or depend on the aggregate aws-sdk gem that bundles them.

The difference is in what gets resolved at install time and what gets loaded at require time. With aws-sdk-core plus aws-sdk-s3, the dependency graph contains the shared runtime and one service client. With the aggregate gem, every service gem in services.json is part of the graph, and the README's own description is that it is "very large" and best used as a migration shortcut. The API surface you call is the same either way, since the service gems are the same code.

A second comparison is between client-level and class-level configuration. Calling Aws.config.update sets process-wide defaults, while passing options to Aws::S3::Client.new scopes them to that instance. The README gives both, and it notes that constructor options take precedence over environment and Aws.config. For anything with more than one credential context, such as a multi-tenant job runner, the constructor form is the one that keeps contexts from bleeding into each other.

## Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-23. The default branch is version-3, and the README leads with "AWS SDK for Ruby - Version 3", so version 3 is where current work lands. The release list shows version 2 patch releases from November 2020, which is a signal about where attention sits rather than a statement about support policy; the README does not describe an end-of-life schedule for version 2, and the V3_UPGRADING_GUIDE.md is the documented path between the two lines.

Upgrade cost is mostly mechanical for application code, because the client API shape described in the README (construct a client, call a method, read structured response fields) is the same in both lines. The larger cost is dependency hygiene: moving from the aggregate gem to per-service gems changes your Gemfile and your lockfile, and the README's advice to pin service gems with a pessimistic constraint means each service gem moves on its own schedule. Expect frequent patch-level releases, as the November 2020 sequence of dated versions suggests.

The project is licensed under Apache-2.0, with LICENSE.txt and NOTICE.txt at the repository root. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, but it also carries notice and attribution obligations, and the NOTICE.txt file is part of that. This is a description of the licence text, not legal advice; if you redistribute the SDK or a derivative, have your own counsel read the terms rather than relying on a summary.

## Conclusion

Adopt aws-sdk-ruby v3 if you are writing Ruby that talks to AWS and want per-service gems with a pessimistic version constraint. Do not adopt it if you need credentials that rotate during a long-running process without recreating clients, because the README states shared configuration is loaded once and credentials are provided statically at client creation time. Before you commit, verify which service gems your code actually requires, confirm your region is set through AWS_REGION or a shared config file, and check the V3_UPGRADING_GUIDE.md if you are moving from version 2.

## FAQ

### Is the AWS SDK for Ruby deprecated?

The repository is not archived and the last push was on 2026-09-23, with version-3 as the default branch. The README presents version 3 as the current line and points to a V3 upgrading guide for moving off version 2.

### What is the AWS SDK for Ruby and what does it do?

It is the official AWS SDK for Ruby. Each service client provides a 1-to-1 mapping of methods to AWS API operations, so a call like list_buckets returns structured response data instead of a raw HTTP body.

### How do I install aws-sdk-ruby v3?

Install it from RubyGems, choosing the specific service gems you need with a pessimistic version constraint, such as aws-sdk-s3 with '~> 1'. The aggregate aws-sdk gem with '~> 3' contains every service gem and the README recommends it mainly as a migration shortcut.

### Where does aws-sdk-ruby look for credentials and a region?

Credentials come from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, then ~/.aws/credentials, then ~/.aws/config unless AWS_SDK_CONFIG_OPT_OUT is set, and from the instance profile on EC2 or the ECS credential provider in a container. The region is read from AWS_REGION, AMAZON_REGION, AWS_DEFAULT_REGION and the shared config files, and it is used to construct the SSL endpoint.

### Do credentials refresh automatically in aws-sdk-ruby?

No. The README states that shared configuration is loaded only a single time, credentials are provided statically at client creation time, and shared credentials do not refresh. A process that outlives its session token needs a newly constructed client.

## Sources

- [aws/aws-sdk-ruby on GitHub](https://github.com/aws/aws-sdk-ruby)
- [License: Apache-2.0](https://github.com/aws/aws-sdk-ruby/blob/version-3/LICENSE)
- [Project website](https://aws.amazon.com/sdk-for-ruby/)
- [README](https://github.com/aws/aws-sdk-ruby/blob/version-3/README.md)
- [Releases](https://github.com/aws/aws-sdk-ruby/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aws-aws-sdk-ruby