How to manage storage buckets

Storage buckets store object-based data using non-local cephobject storage pools. When used in LXD or MicroCloud clusters, they are available from any cluster member.

Unlike custom storage volumes, storage buckets cannot be attached to instances. Instead, applications access them directly via a URL using the S3 protocol. A Ceph RADOS Gateway endpoint provides the S3-compatible URL.

View storage buckets

To list all available storage buckets in a storage pool, run:

lxc storage bucket list <pool-name>

To show detailed information about a specific bucket, run:

lxc storage bucket show <pool-name> <bucket-name>

Requirements

To use storage buckets, your LXD server must have access to a storage pool that uses the Ceph Object driver. You can confirm this by viewing your available storage pools.

If no listed pool uses the cephobject storage driver, you must create one. This requires a Ceph cluster with a RADOS Gateway (radosgw) enabled. Refer to our how-to guide for storage pools: Requirements for Ceph-based storage pools.

Create a storage bucket

To create a storage bucket, run:

lxc storage bucket create <pool-name> <bucket-name> [configuration_options...]

Refer to the Ceph Object documentation for a list of available storage bucket configuration options for the driver.

Configure storage bucket settings

Use the following command to set configuration options for a storage bucket:

lxc storage bucket set <pool-name> <bucket-name> <key> <value>

For example, to set the size (quota) of a bucket, use the following command:

lxc storage bucket set my-pool my-bucket size 1MiB

You can also edit the storage bucket configuration by using the following command:

lxc storage bucket edit <pool-name> <bucket-name>

Use the following command to delete a storage bucket and its keys:

lxc storage bucket delete <pool-name> <bucket-name>

Refer to the Ceph Object documentation for a list of available storage bucket configuration options for the driver.

Resize a storage bucket

By default, storage buckets do not have a quota applied.

To set or change a quota for a storage bucket, set its size configuration:

lxc storage bucket set <pool-name> <bucket-name> size <new-size>

Resizing considerations

  • Growing a storage bucket usually works (if the storage pool has sufficient storage).

  • You cannot shrink a storage bucket below its current used size.

Manage storage bucket keys

To access a storage bucket, applications must use a set of S3 credentials made up of an access key and a secret key. You can create multiple sets of credentials for a specific bucket.

Each set of credentials is given a key name. The key name is used only for reference and does not need to be provided to the application that uses the credentials.

Each set of credentials has a role that specifies what operations they can perform on the bucket. The available roles are:

admin

Provides full access to the bucket.

read-only

Default. Provides read-only (view) access to the bucket.

View storage bucket keys

Use the following command to list the keys defined for an existing bucket:

lxc storage bucket key list <pool-name> <bucket-name>

Use the following command to show a specific bucket key:

lxc storage bucket key show <pool-name> <bucket-name> <key-name>

Create keys

Use the following command to generate and display a set of keys for a storage bucket. The default role is read-only. To create credentials with the admin role, include the --role=admin flag:

lxc storage bucket key create <pool-name> <bucket-name> <key-name> [--role=admin] [configuration_options...]

Refer to lxc storage bucket key create for configuration options.

Edit or delete storage bucket keys

To edit an existing bucket key, run:

lxc storage bucket key edit <pool-name> <bucket-name> <key-name>

To delete an existing bucket key, run:

lxc storage bucket key delete <pool-name> <bucket-name> <key-name>