Skip to content

S3 buckets

You want object storage for uploads, backups or artefacts. On AWS you would create an S3 bucket and an IAM user for it. Here you do not create the bucket directly - you claim one, and the storage operator creates it and hands back credentials.

The claim is the thing you own. Delete it and, depending on the backend, the bucket goes with it.

Prerequisites

  • A project you can create resources in
  • A view on whether the data should sit on-site or offsite

The step-by-step guide and the console walkthrough cover the operations. The rest of this page explains how it fits together.

How it fits together

flowchart LR
    OBC["ObjectBucketClaim<br/>you create this"]
    OP["storage operator"]
    CM["ConfigMap<br/>BUCKET_NAME<br/>BUCKET_HOST<br/>BUCKET_PORT"]
    SEC["Secret<br/>AWS_ACCESS_KEY_ID<br/>AWS_SECRET_ACCESS_KEY"]
    BUCK["the bucket<br/>on the backend"]
    APP["your workload"]
    OBC --> OP
    OP --> BUCK
    OP --> CM
    OP --> SEC
    APP -->|envFrom| CM
    APP -->|envFrom| SEC
    APP -->|S3 API| BUCK

One claim produces three things: the bucket, a ConfigMap with the endpoint, and a Secret with the credentials. Both are named after the claim, so your workload reads them with two envFrom entries and never carries a credential of its own.

The claim reaches phase Bound once all of that exists.

Not reachable from a subnet

The endpoint in the ConfigMap is a service of this cluster. A workload in a subnet cannot open it, even though the claim binds. See what a workload in a subnet can reach.

Two names, and only one of them is yours alone

This trips people up, so it is worth separating.

Scope What it names
metadata.name your project the claim, and with it the ConfigMap and Secret
spec.bucketName the whole backend the bucket itself

Bucket names are global to the storage backend

Not scoped to your project. Two projects asking for backups collide. The console fills this in as <project>-<claim>, and that prefix is the only thing keeping your bucket apart from someone else's. If you change it, keep a prefix that is yours.

Choosing a backend is a one-way decision

The storage class decides where the bytes physically sit - on-site for data an application reads constantly, offsite for data you want held away from this cluster.

It cannot be changed afterwards. Moving a bucket to another backend means creating a second claim and copying the objects across with any S3 client.

What deleting does

The claim owns the bucket

Whether the data survives depends on the storage class's reclaimPolicy. On this platform the object backends are set to Delete, so the bucket and its contents go with the claim. Check before you delete - see Delete.

Do not force-delete a claim or strip its finalizer. The finalizer is what lets the operator release the bucket cleanly; removing it orphans the bucket on the backend, where nothing will ever clean it up.