Buckets

A bucket is S3 compatible storage for your files, such as uploads, images or backups. It belongs to the team, not to one application, and any S3 client reaches it with an access key, so several applications and scripts can share the same files.

Buckets are in beta. Find them under Buckets in the sidebar.

How Buckets Work

A bucket is not mounted into an application the way a volume is. Your code reads and writes files over HTTPS with an S3 client, so a bucket does not limit how many instances an application runs, and the same files are there for every application and script that holds a key.

Every bucket has two names. The name you choose is how the console and the CLI refer to it. The bucket name adds a short random suffix that makes the bucket's address unique, and it is the one your S3 client uses. The console shows it in the Bucket column of the list, and under Bucket on the Overview tab.

A bucket is private unless you make it public, and it has no access key until you create one. Its region shows as Global, and S3 clients sign with the region auto.

Create a Bucket

Access Keys

Open the bucket's Access tab and select Create key. Give the key a name to recognize it by, and choose a permission:

• Read and write can read, upload and delete files.
• Read only can read and list files.

A key works on this bucket only. When it is created, the console shows its access key ID, its secret access key, and the variables with both filled in.

There is no rotation. To replace a key, create a new one, move your applications to it, then delete the old one with the trash icon in the key's row. A deleted key can keep working for up to 15 minutes.

Connect an Application

The Overview tab and the screen of a new key both show the connection as a .env block. The Overview tab has placeholders for the key, and the key's screen fills them in:

AWS_ENDPOINT_URL_S3=https://obj.outplane.dev
AWS_REGION=auto
AWS_ACCESS_KEY_ID=<access-key-id>
AWS_SECRET_ACCESS_KEY=<secret-access-key>
BUCKET_NAME=<bucket-name>

The AWS_ names are the ones S3 clients commonly read, and BUCKET_NAME is for your own code. If your client reads different names, keep the values and rename the keys.

Open the application's Settings → Environment, select Edit as .env, add the block below the existing lines, select Apply, then Save & deploy. If the application already has one of these keys, change that line instead of adding a second one. From a terminal, save the block to a .env file and push it:

outplane env push --app <app-name> --dry-run   # what would be added or changed
outplane env push --app <app-name> --deploy

env push replaces a variable the application already has with the one in the file, so if it uses an AWS_ name for something else, --dry-run shows it before anything changes.

Addressing

Clients must use virtual-hosted addressing, where the bucket name is part of the host: https://<bucket-name>.obj.outplane.dev/<file>. Path-style requests do not work. Some S3 clients switch to path-style when you set a custom endpoint, so set the addressing style explicitly.

• A connection error on the endpoint host, or a 404 on a file you know exists, usually means the client is using path-style.
• A TLS error right after creating a bucket usually means its address is still being set up, so wait a few minutes and try again.
• Use the bucket name with its suffix, not the short name.
• Sign requests with the region auto.

Visibility

Change who can read the files under Settings → Visibility: choose Private or Public and select Save.

Public means anyone with a file's link can read it, and listing stays off. The Overview tab of a public bucket shows its Public address, and a file's link is that address followed by the file's path. Private means only requests signed with an access key can read files.

Changes can take a few minutes to apply. Until then, some requests can see the old setting, and the same file can answer differently from one request to the next. A connection that is already open can keep the old behavior for longer. If a file is sensitive, keep the bucket private from the start.

Delete a Bucket

Open Settings → Delete bucket and type the bucket's name to confirm.

Deleting a bucket removes every file and key, and it cannot be undone. The bucket leaves the list at once. Its files and keys can keep answering for some minutes. Applications holding a key are not updated, so move them off first.

Reference

From the CLI and Agents

Everything here can also be done from a terminal with outplane bucket list, get, create, update and delete, and outplane bucket key list, create and delete. See bucket in the CLI reference. A coding agent working with the CLI can create a bucket, but it hands you the key command to run yourself, because that command prints the secret into whatever ran it. Deleting stops for your confirmation, as every deletion does.

Related