diff --git a/source/adminguide/storage.rst b/source/adminguide/storage.rst index d0283b234c..6dea6ad130 100644 --- a/source/adminguide/storage.rst +++ b/source/adminguide/storage.rst @@ -1610,8 +1610,11 @@ Under `Browser` tab, clicking a directory on the browser tab will list the objec For a file, clicking it list the properties of that file with links to access the file. |object-store-file-properties.png| -.. note:: - To access the bucket, UI uses the URL, access key and secret key from the bucket's details. +.. note:: + To access the bucket, the UI uses the object store URL and the bucket's access key and + secret key. For a bucket with its own credential, the keys are shown on the bucket's + ``Keys`` tab. For a bucket that uses its account's credential, they are shown on the + bucket's ``Details`` tab. See :ref:`per-bucket-credentials`. Uploading an object to a bucket @@ -1633,6 +1636,117 @@ Deleting objects from a bucket 2. Click on the |delete-button.png| button to delete the selected files from the bucket. +.. _per-bucket-credentials: + +Per-bucket credentials +~~~~~~~~~~~~~~~~~~~~~~ + +Since Apache CloudStack 24.0, each bucket can have its own credential for accessing the +object store. A bucket's credential gives access to that bucket only, so it can be given to +an application, rotated or revoked without affecting the account's other buckets. + +Each credential has two key slots. Both slots can hold an active key at the same time, so an +application can be moved to a new key before the old key is revoked. + +Per-bucket credentials are available on Ceph object storage running Ceph Squid (v19) or +later, with the admin user permissions described in :ref:`add-object-storage`. On other +object storage platforms, all of an account's buckets use one credential. + +The **Credential Scope** of a bucket shows which kind of credential it uses: + +- **Per-Bucket**: the bucket has its own credential. + +- **Account**: the bucket uses its account's credential. + +The **Credential Scope** column appears in the bucket list once at least one bucket has its +own credential, and the bucket list can be filtered by it. + +The global setting ``object.storage.per.bucket.credentials`` (default ``true``) determines +how an account is set up the first time it uses an object store. When ``true``, every bucket +the account creates gets its own credential. When ``false``, the account's buckets share one +credential, and an administrator can migrate the account later. The setting has no effect on +an account that has already been migrated. + + +Managing a bucket's keys +^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Log in to the CloudStack UI as a user or administrator. + +#. In the left navigation bar, click Storage. + +#. In Select View, choose Buckets. + +#. Click the bucket name, then open the ``Keys`` tab. + +The ``Keys`` tab lists both key slots, with each slot's state, access key, secret key and +creation time. For each slot: + +- **Create Key**: creates a key in an empty slot. + +- **Rotate Key**: replaces the key in a slot with a new key. The replaced key stops working + immediately. + +- **Revoke Key**: revokes the key in a slot. The key stops working immediately. The last + active key of a bucket cannot be revoked; create a key in the other slot first. + +To replace a key without interrupting an application: + +#. Create a key in the empty slot, or rotate the slot the application does not use. + +#. Update the application to use the new key. + +#. Revoke the old key. + +The same operations are available through the ``rotateBucketKey`` and ``revokeBucketKey`` +APIs. + + +Migrating an account to per-bucket credentials +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An account that used an object store before per-bucket credentials were available keeps +one credential for all of its buckets until an administrator migrates it. Migration is done +separately for each object store the account uses, by a root administrator or a domain +administrator. + +.. warning:: + Migrating an account cannot be undone. On Ceph, the account's existing object storage + user becomes the root user of a new RGW account, which takes ownership of all of the + account's buckets on that object store. Existing keys continue to work. + +#. Log in to the CloudStack UI as a root administrator or domain administrator. + +#. In the left navigation bar, click Accounts, then click the account name. + +#. Open the ``Object Storage`` tab. The tab lists each object store the account can use, + with the account's migration stage on it. + +#. Click **Migrate Account to Per-Bucket Credentials** for the object store, and confirm. + The account's existing buckets continue to use the account credential. + +#. Click **Show Buckets** to list the account's buckets that still use the account + credential. For each bucket, choose **Migrate to Per-Bucket Credential**. The bucket gets + its own credential, which can also access objects written before the migration. + +#. When no bucket on the object store uses the account credential, click + **Rotate Account Key** and confirm. CloudStack replaces the account credential it holds + for that object store, and the previous account key stops working. Any application still + using the previous account key loses access. + +When all stages are done, the tab shows **Per-Bucket Credentials In Use** for that object +store. Buckets the account creates on it from then on get their own credential. + +If an object store does not support per-bucket credentials, the tab says so. Root +administrators can see the reason on the object store's ``Details`` tab: in the left +navigation bar, click Infrastructure, then Object Storage, then the object store. The +**Per-Bucket Credentials** field shows **Ready** or **Not ready**, and +**To Resolve Before Migration** names what needs to change. + +The same operations are available through the ``migrateObjectStoreAccount``, +``migrateBucketCredential`` and ``rotateObjectStoreAccountKey`` APIs. + + Configuring resource limits on buckets and object storage usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Administrators can enforce limits on the maximum number of buckets they can be created and diff --git a/source/installguide/configuration.rst b/source/installguide/configuration.rst index c6c3ee512b..a78148c70c 100644 --- a/source/installguide/configuration.rst +++ b/source/installguide/configuration.rst @@ -1797,6 +1797,8 @@ zone: - Path. The path to the zone's Secondary Staging Store. +.. _add-object-storage: + Add Object Storage ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1830,7 +1832,19 @@ You can add object storage pools at any time to add more capacity or providers - Secret key: Credentials with access to admin API of the object storage server - In case of ceph make sure the user is a system user and has the necessary permissions to access the ceph pool specified in the url field. + In case of ceph make sure the user is a system user and has the necessary permissions to access the ceph pool specified in the url field. + + .. note:: + Per-bucket credentials on Ceph require Ceph Squid (v19) or later, and the admin + user must also hold the ``info`` and ``accounts`` capabilities: + + .. code:: bash + + radosgw-admin caps add --uid= --caps="info=*;accounts=*" + + Without both capabilities, the object store works as before, with one credential + per account. Root administrators can check whether an object store is ready on its + ``Details`` tab. See :ref:`per-bucket-credentials`. |AddObjectStore.png: Add Object Storage|