Buckets
S3-compatible object storage for files an app should not keep on its own disk.
On this page
What it is
A bucket is object storage that speaks the S3 API. Your app writes files to it with any S3 client, and the files live outside the container, outside any single machine, and outside the app's lifecycle.
Buckets sit alongside databases in a project as a second kind of managed state. Where a volume is a disk attached to one app, a bucket is a service several things can read and write.
When you'd use it
- User uploads, generated PDFs, exports: anything a browser will download later.
- Files more than one app needs to see.
- Anything that would make a volume grow without limit.
Object storage is not a filesystem. There are no real directories, no partial writes, and no appending to a file. Code that expects to seek around a file on disk wants a volume.
Create one
- Open the project, go to Buckets, then Add bucket.
- Give it a name and a size.
- Create. It is ready in seconds, since there is no cluster to bring up.
Connecting an app
Open the bucket and go to Access. You get an endpoint, an access key and a secret key: the four values every S3 client asks for. Hand them to the app the same way you would any credential.
The secret key behaves like a secret everywhere else in klickops. It is shown when you ask for it and never returned in a list.
Settings reference
| Setting | Default | What it does |
|---|---|---|
| Name | none | Identifies the bucket. Permanent. |
| Size | from the slider | The storage quota. |
| Versioning | off | Keeps old versions of an overwritten object, so a bad write is recoverable. |
| Lifecycle | off | Deletes objects automatically after a number of days. |
Limits and gotchas
- Versioning is off by default and cannot be applied retroactively. Turn it on before the overwrite you will regret, not after.
- Lifecycle deletes for real. An expiry rule is a scheduled deletion, and it does not ask again.
- Listing a huge bucket is slow. The Objects tab is for looking, not for managing millions of keys. Use an S3 client for bulk work.
- Buckets are not covered by the project's recovery points. They have their own durability from the storage layer underneath.