Skip to main content

Buckets Guide

The buckets module manages RGW buckets at the admin level:

  • list all buckets or per-user
  • get detailed bucket metadata
  • delete buckets
  • transfer/remove bucket ownership
  • verify and repair bucket indexes

API reference: Bucket types and methods

Prerequisites​

import { RadosGWAdminClient } from 'radosgw-admin';

const rgw = new RadosGWAdminClient({
  host: 'https://ceph-rgw.example.com',
  accessKey: process.env.RGW_ADMIN_ACCESS_KEY!,
  secretKey: process.env.RGW_ADMIN_SECRET_KEY!,
});

1) List All Buckets​

const all = await rgw.buckets.list();
console.log(`Cluster has ${all.length} buckets`);

2) List Buckets by User​

const userBuckets = await rgw.buckets.listByUser('alice');
console.log(`alice has ${userBuckets.length} buckets`);

3) Get Bucket Info​

const info = await rgw.buckets.getInfo('my-bucket');
console.log('Owner:', info.owner);
console.log('Objects:', info.usage.rgwMain.numObjects);
console.log('Size:', (info.usage.rgwMain.sizeKb / 1024).toFixed(2), 'MB');

4) Delete a Bucket​

Safe delete (fails if bucket has objects):

await rgw.buckets.delete({ bucket: 'my-bucket' });

Force delete with object purge:

await rgw.buckets.delete({ bucket: 'my-bucket', purgeObjects: true });
warning

purgeObjects: true permanently deletes all objects in the bucket. This cannot be undone.

5) Transfer Ownership​

Move a bucket from one user to another:

const info = await rgw.buckets.getInfo('my-bucket');
await rgw.buckets.transferOwnership({
  bucket: 'my-bucket',
  bucketId: info.id,
  uid: 'bob',
});
info

You need the bucket's internal id (from getInfo()), not just the bucket name.

6) Remove Ownership​

Detach a bucket from its owner without deleting it:

await rgw.buckets.removeOwnership({
  bucket: 'my-bucket',
  uid: 'alice',
});
warning

This leaves the bucket orphaned — it can't be accessed via S3 until ownership is reassigned with transferOwnership().

7) Verify Bucket Index​

Check for index inconsistencies (read-only):

const result = await rgw.buckets.verifyIndex({
  bucket: 'my-bucket',
  checkObjects: true,
  fix: false,
});
console.log('Invalid entries:', result.invalidMultipartEntries);

Repair detected issues:

await rgw.buckets.verifyIndex({
  bucket: 'my-bucket',
  fix: true,
});

Error Handling​

import {
  RGWValidationError,
  RGWNotFoundError,
} from 'radosgw-admin';

try {
  await rgw.buckets.delete({ bucket: 'my-bucket' });
} catch (error) {
  if (error instanceof RGWNotFoundError) {
    // bucket does not exist
  } else if (error instanceof RGWValidationError) {
    // bucket name is empty
  } else {
    throw error;
  }
}

Production Notes​

  1. Always use getInfo() before transferOwnership() to get the correct bucketId.
  2. Avoid purgeObjects: true in automated loops — add a manual confirmation step.
  3. Run verifyIndex({ fix: false }) first to assess damage before repairing.
  4. The list() method fetches up to 100,000 entries. For very large clusters, check that the returned count matches expectations.
  5. Bucket ownership transfers don't move objects — they update metadata only.