3.4. Managing S3 Buckets¶
All objects in Amazon S3-like storage are stored in containers called “buckets”. Buckets are addressed by names that are unique in the given object storage, so an S3 user of that object storage cannot create a bucket that has the same name as a different bucket in the same object storage. Buckets are used to:
- group and isolate objects from those in other buckets,
- provide ACL management mechanisms for objects in them,
- set per-bucket access policies, for example, versioning in the bucket.
You can manage buckets with the
ostor-s3-admin tool as well as S3 API third-party S3 browsers like CyberDuck or DragonDisk. To manage buckets via CLI, you will need to know the ID of the volume that the buckets are in. You can obtain it with the
ostor-ctl get-config command. For example:
# ostor-ctl get-config -n 10.94.97.195 VOL_ID TYPE STATE 0100000000000002 OBJ READY ...
ostor-s3-admin commands are assumed to be issued by object storage administrators, they do not include any authentication or authorization checks.
3.4.1. Listing S3 Bucket Contents¶
You can list bucket contents with a web browser. To do this, visit the URL that consists of the external DNS name for the S3 endpoint that you specified when creating the S3 cluster and the bucket name. For example,
mybucket.mys3storage.example.com (depending on DNS configuration).
You can also copy the link to bucket contents by right-clicking it in CyberDuck, and then selecting Copy URL.
3.4.2. Listing S3 Storage Buckets¶
You can list all buckets in the S3 object storage with the
ostor-s3-admin list-all-buckets command. For each bucket, the command shows owner, creation data, versioning status, and total size (the size of all objects stored in the bucket plus the size of all unfinished multipart uploads for this bucket). For example:
# ostor-s3-admin list-all-buckets -V 0100000000000002 Total 3 buckets BUCKET OWNER CREATION_DATE VERSIONING TOTAL SIZE, BYTES bucket1 968d1a79968d1a79 2015-08-18T09:32:35.000Z none 1024 bucket2 968d1a79968d1a79 2015-08-18T09:18:20.000Z enabled 0 bucket3 968d1a79968d1a79 2015-08-18T09:22:15.000Z suspended 1024000
To output the list in XML, use the
-X option. For example:
# ostor-s3-admin list-all-buckets -X <?xml version="1.0" encoding="UTF-8"?><ListBucketsResult><Buckets><Bucket><Name>bucker2</Name><Owner>d7c53fc1f931661f</Owner><CreationDate>2017-04-03T17:11:44.000Z</CreationDate><Versioning>none</Versioning><Notary>off</Notary><TotalSize>0</TotalSize></Bucket><Bucket><Name>bucket1</Name><Owner>d7c53fc1f931661f</Owner><CreationDate>2017-04-03T17:11:33.000Z</CreationDate><Versioning>none</Versioning><Notary>off</Notary><TotalSize>0</TotalSize></Bucket></Buckets></ListBucketsResult>
To filter buckets by user who owns them, use the
-i option. For example:
# ostor-s3-admin list-all-buckets -i d7c53fc1f931661f BUCKET OWNER CREATION_DATE VERSIONING TOTAL_SIZE NOTARY NOTARY_PROVIDER bucker2 d7c53fc1f931661f 2017-04-03T17:11:44.000Z none 0 off 0
3.4.3. Querying S3 Bucket Information¶
You can query bucket metadata information and ACL with the
ostor-s3-admin query-bucket-info command. For example, for
# ostor-s3-admin query-bucket-info -b bucket1 -V 0100000000000002 BUCKET OWNER CREATION_DATE VERSIONING TOTAL_SIZE bucket1 d339edcf885eeafc 2017-12-21T12:42:46.000Z none 0 ACL: d339edcf885eeafc: FULL_CONTROL
3.4.4. Changing S3 Bucket Owners¶
You can pass ownership of a bucket to the specified user with the
ostor-s3-admin change-bucket-owner command. For example, to make user with ID
bf0b3b15eb7c9019 the owner of
# ostor-s3-admin change-bucket-owner -b bucket1 -i bf0b3b15eb7c9019 -V 0100000000000002 Changed owner of the bucket bucket1. New owner bf0b3b15eb7c9019
3.4.5. Deleting S3 Buckets¶
You can delete the specified bucket with the
ostor-s3-admin delete-bucket command. Deleting a bucket will delete all objects in it (including their old versions) as well as all unfinished multipart uploads for this bucket For example:
# ostor-s3-admin delete-bucket -b bucket1 -V 0100000000000002 Deleted bucket bucket1