Skip to content

Object Storage

b'nerd object storage is S3-compatible, backed by Ceph RADOS Gateway (RGW). Each project can have one or more RGW users. Each user gets a dedicated AWS-style access-key / secret-key pair and a storage quota, and owns its buckets independently.

Concepts

Concept Description
RGW user An S3 identity scoped to a project. Holds credentials and a quota.
Bucket A named container for objects, owned by one RGW user.
Access key / Secret key AWS-compatible credentials used to authenticate S3 requests.
Quota Maximum total storage (in KB) enforced by the RGW admin API.
Lock Platform-level flag that prevents a user from being deleted or having keys rotated.

Endpoint summary

Method Path Description
GET /rgw/users?project_id=<uuid> List RGW users for a project
POST /rgw/users Create an RGW user
GET /rgw/users/{id} Show an RGW user (with quota and key info)
PATCH /rgw/users/{id} Update quota or lock (admin only)
POST /rgw/users/{id}/renew_key Rotate the secret key
DELETE /rgw/users/{id}?purge_objects=true Delete user (optionally purge all objects first)
GET /rgw/users/{user_id}/buckets List buckets
GET /rgw/users/{user_id}/buckets/{bucket_id} Show bucket
DELETE /rgw/users/{user_id}/buckets/{bucket_id} Delete bucket
GET /rgw/users/{user_id}/buckets/{bucket_id}/acl Get bucket ACL
PUT /rgw/users/{user_id}/buckets/{bucket_id}/acl Set bucket ACL
GET /rgw/users/{user_id}/buckets/{bucket_id}/objects List objects
POST /rgw/users/{user_id}/buckets/{bucket_id}/objects Upload object
GET /rgw/users/{user_id}/buckets/{bucket_id}/objects/download?key=... Download object
GET /rgw/users/{user_id}/buckets/{bucket_id}/objects/metadata?key=... Get object metadata
POST /rgw/users/{user_id}/buckets/{bucket_id}/objects/upload_url Generate presigned upload URL

Authorization

Most operations require a valid membership with the :rgw permission category. Two operations require platform-admin (Admin role with :manage on RgwUser):

  • Setting or modifying quota (PATCH /rgw/users/{id} with quota field)
  • Setting or modifying locked (PATCH /rgw/users/{id} with locked field)

A non-admin member that sends either field in an update request receives 403 Forbidden.

S3 Operator (Kubernetes-native provisioning)

The bnerd-s3-operator is a Kubernetes operator that provisions RGW users and buckets declaratively from within your cluster. Define a S3User custom resource in your namespace and the operator creates the corresponding RGW user, sets the quota, and writes the credentials into a Kubernetes Secret — no manual API calls required.

Typical use case: give each application in your cluster its own isolated S3 identity without sharing credentials.

apiVersion: s3.bnerd.cloud/v1alpha1
kind: S3User
metadata:
  name: my-app-storage
  namespace: my-app
spec:
  projectRef: my-project-uuid
  quota:
    maxSizeKb: 10485760   # 10 GB

Contact support to enable the S3 Operator on your cluster.

  • Buckets — create and manage buckets, ACLs, and objects
  • Keys — rotate credentials and lock/unlock users
  • Quota & Limits — quota configuration and current usage