S3 buckets¶

Buckets on this platform are claimed rather than created directly. You describe the bucket you want, and the storage operator creates it and hands back credentials.

For the same steps in the console, see the console walkthrough.

What a claim produces¶

An ObjectBucketClaim produces two objects in your project, both named after the claim:

Object	Holds
ConfigMap	`BUCKET_NAME`, `BUCKET_HOST`, `BUCKET_PORT`, `BUCKET_REGION`, `BUCKET_SUBREGION`
Secret	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`

BUCKET_REGION and BUCKET_SUBREGION are present but empty on this platform. An S3 client that insists on a region will accept any value.

Applications read both rather than carrying credentials of their own.

Choose a backend¶

The storage class decides where the bytes physically sit. Anything with a bucket-style provisioner can serve a bucket:

oc get storageclass -o custom-columns=NAME:.metadata.name,PROVISIONER:.provisioner \
  | grep -E '/obc|/bucket'

The choice cannot be changed afterwards. Moving a bucket to another backend means creating a second claim and copying the data across.

Create¶

bucket.yaml

apiVersion: objectbucket.io/v1alpha1
kind: ObjectBucketClaim
metadata:
  name: <claim>
  namespace: <project>
spec:
  bucketName: <project>-<claim>
  storageClassName: <storage-class>

oc apply -f bucket.yaml

Bucket names are global to the backend

spec.bucketName is not scoped to your project - it has to be unique across everything on that storage backend. Prefixing it with your project name, as above, is what keeps one project's bucket from colliding with another's. The console does this for you.

metadata.name is the claim, and is scoped to your project. The two are different names and it is worth keeping them distinguishable.

List¶

oc get objectbucketclaims -n <project>

A claim reaches phase Bound once the bucket exists and the credentials have been written:

oc get objectbucketclaims <claim> -n <project> \
  -o jsonpath='{.status.phase}{"\n"}'

A claim that stays Pending means the operator has not finished, or the bucket name is already taken on that backend. Check whether the ConfigMap and Secret appeared - if neither did, the claim never bound.

Change¶

Nothing meaningful on a claim can be changed after it binds. The bucket name and the storage class are both fixed, and editing them does not move or rename anything.

To grow past what a backend offers, or to move to another, create a second claim and copy the objects across with any S3 client.

To rotate credentials, delete and recreate the claim - which, depending on the reclaim policy, may also delete the bucket. Check first.

Delete¶

oc delete objectbucketclaims <claim> -n <project>

Deleting the claim usually deletes the bucket

The claim owns the bucket. What happens to the data depends on the storage class's reclaimPolicy: Delete wipes the bucket, Retain keeps it. Check before you delete:

oc get storageclass <storage-class> \
  -o jsonpath='{.reclaimPolicy}{"\n"}'

Do not force-delete a claim or strip its finalizers. 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.

Use the bucket from a workload¶

envFrom:
  - configMapRef:
      name: <claim>
  - secretRef:
      name: <claim>

That gives the container every key from the table above without any of them appearing in your manifests.

Storage - what the storage offering covers
Volumes - block and file storage for workloads
PostgreSQL - a common source of data to back up into a bucket