Skip to Content

Use object storage

Create an S3-compatible bucket, make an access key and attach the bucket to an app.

Goal: a bucket for uploads, exports or backups, reachable with any S3 client, and an app that gets its credentials as environment variables.

Before you start

  • An organization with credit on its balance. Storage is billed per GiB.
  • An S3 client, such as the aws CLI or rclone, if you want to test from your machine.

Create a bucket

Open Object storage in the sidebar and select Create bucket.

Enter a Name, such as shop-uploads.

Optional: a Description (what the bucket is for) and a Quota in GiB, to limit how large the bucket can grow.

Select Create bucket.

The bucket opens on its Overview tab. The Connection card shows the S3 API endpoint, the Region and the Bucket URL. S3 clients use the endpoint with path-style addressing.

Make an access key

Go to the Access keys tab. The Create access key dialog opens when you add a key.

Optional: a Name, a Path prefix to limit the key to part of the bucket, and an expiry in days.

Pick the Permission: Read-only to list and read objects, or Read & write to also upload and delete.

Select Create key. The Save your access key dialog shows the Access key ID and the Secret access key. Copy them, then confirm I have saved the secret.

The secret access key is shown only in this dialog. If you lose it, make a new key.

The key only works for this bucket. The dialog also gives ready-made snippets: Env vars, aws CLI, rclone, AWS SDK and boto3.

Attach the bucket to an app

You do not need to copy keys into an app.

Open the app on the project canvas and go to its Env Vars tab.

Select Attach bucket and pick the bucket.

Choose the credentials:

  • Shared key: all pods use one key.
  • Per-pod keys (rotated automatically): each pod gets its own key. These are billed as dynamic leases.

Optional: a Path prefix, so the app only sees part of the bucket.

Deploy the app.

The app gets these variables, with the prefix S3 by default:

VariableValue
S3_ENDPOINTThe S3 API endpoint
S3_REGIONThe region
S3_BUCKETThe bucket name
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEYThe credentials
S3_FORCE_PATH_STYLEtrue; set your client to path-style addressing
S3_URL, S3_PREFIXThe bucket URL and the path prefix

Verify

With the Env vars snippet from the key dialog, list the bucket from your machine. Copy the endpoint from the Connection card:

export S3_ENDPOINT=<S3 API endpoint>
export AWS_ACCESS_KEY_ID=AKEXAMPLE0000000000
export AWS_SECRET_ACCESS_KEY=example-secret-key
aws s3 ls s3://shop-uploads --endpoint-url "$S3_ENDPOINT"

Open the Objects tab to browse what the app wrote. The Used by tab lists the apps the bucket is attached to.

Troubleshooting

  • "The specified bucket does not exist" or wrong-host errors: the client uses virtual-host addressing. Turn on path-style addressing.
  • Access denied: the key is Read-only, has a Path prefix that does not cover the object, has expired, or belongs to another bucket.
  • Uploads fail once the bucket is full: raise the quota on the Settings tab, or delete old objects.

Public files

A bucket is private by default. Make public on the bucket serves its objects to anyone with the URL; Make private turns it off again. The Domains tab serves the bucket on your own host name.

In IaC

A bucket is a file buckets/<name>.yaml. An app reaches it through storage_bindings, with a permission, a key_prefix, an env_prefix and a credential_mode of static or per_pod. See Buckets in IaC and bucket access.

Next steps

On this page