ruby

AWS SDK for Ruby

The client under Rails Active Storage and Shrine
verified in CIv1.170+AWS SDK for Ruby documentation ↗

Install

shell
bundle add aws-sdk-s3

Configure

Configure the endpoint, region, credential and bucket in this tool’s vocabulary. Path-style addressing is recommended for dotted bucket names and clients without nested wildcard TLS, but virtual-hosted addressing is also supported.

In AWS SDK for RubySet it to
endpointhttps://s3.canada.popcloud.ca
regioncanada
access_key_idPCAK00EXAMPLEKEYID00
secret_access_key<your secret access key>
force_path_styletrue
Environment
example values
export AWS_ACCESS_KEY_ID=PCAK00EXAMPLEKEYID00
export AWS_SECRET_ACCESS_KEY=<your secret access key>
export AWS_ENDPOINT_URL=https://s3.canada.popcloud.ca
export AWS_REGION=canada
export POPCLOUD_BUCKET=pc-your-org-media

These are example values. Sign in and every snippet on this site fills in with your own endpoint, key and bucket.

Ruby
s3 = Aws::S3::Client.new(
  endpoint: ENV.fetch("AWS_ENDPOINT_URL"),          # https://s3.<region>.popcloud.ca
  region: ENV.fetch("AWS_REGION"),                  # canada
  access_key_id: ENV.fetch("AWS_ACCESS_KEY_ID"),
  secret_access_key: ENV.fetch("AWS_SECRET_ACCESS_KEY"),
  # Recommended for predictable custom-endpoint behavior. Virtual-hosted
  # requests are supported too for ordinary single-label bucket names.
  force_path_style: true
)

Use it

Upload an object

Ruby
s3.put_object(bucket: bucket, key: key, body: body, content_type: "text/plain")

Upload a large object

Ruby
# The resource interface switches to multipart on its own, with retries.
resource = Aws::S3::Resource.new(client: s3)
resource.bucket(bucket).object(key).upload_file(path, multipart_threshold: 8 * 1024 * 1024)

Download an object

Ruby
body = s3.get_object(bucket: bucket, key: key).body.read

List a prefix

Ruby
s3.list_objects_v2(bucket: bucket, prefix: prefix).each do |page|
  page.contents.each { |object| keys << object.key }
end

Presign a URL

Ruby
signer = Aws::S3::Presigner.new(client: s3)
url = signer.presigned_url(:get_object, bucket: bucket, key: key, expires_in: 3600)
# Anyone holding this URL can read the object until it expires, with no
# credentials at all. 7 days is the hard maximum.

Delete an object

Ruby
s3.delete_object(bucket: bucket, key: key)

What to watch for

These apply to AWS SDK for Ruby specifically. The full list covers the platform.

Friction

Buckets are not created over the S3 API

You’ll see
405 MethodNotAllowed from CreateBucket or DeleteBucket — `aws s3 mb`, `mc mb`, or a tool provisioning its own bucket on first run.
Why
Bucket lifecycle belongs to the control plane, which also allocates the storage account, the data-plane key and the CORS rules that come with it. Letting the edge create buckets would create half of one.
Instead
Create buckets in the dashboard, or with `POST /v1/buckets` on the control-plane API. Everything object-level then works normally against that bucket.

How this page is kept true

Every snippet above was extracted from examples/ruby/aws-sdk-ruby, a program that uploads, downloads, compares bytes, lists, presigns and cleans up after itself. It runs in CI against a live sandbox organisation via make docs-verify-ruby. If it stops passing, this page is wrong and we treat that as a bug in the product.

A few snippets on this page are marked not run in CI — they need a browser, a second provider, or a configuration change the sandbox cannot make. Those are reviewed by hand.

Not yet run against the live sandbox — the runner is wired, the first verified run stamps this line.