From: Ville Ojamo <14869000+bluikko@users.noreply.github.com> Date: Tue, 29 Apr 2025 06:52:51 +0000 (+0700) Subject: doc/radosgw: Promptify cmds and improve formatting in placement.rst X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=0e190b84a135294aad607845108880af81abf097;p=ceph.git doc/radosgw: Promptify cmds and improve formatting in placement.rst Use preformatted blocks with a privileged bash prompt instead of hardcoding prompts in the beginning of each line for CLI commands. Indent continuation lines of multi-line CLI example commands the same way they are indented elsewhere. Use inline code formatting consistently, add double-backticks for inside text references to CLI commands, configuration data, etc. Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com> --- diff --git a/doc/radosgw/placement.rst b/doc/radosgw/placement.rst index bf38798dd5731..37ff168667d2c 100644 --- a/doc/radosgw/placement.rst +++ b/doc/radosgw/placement.rst @@ -44,9 +44,12 @@ the zonegroups and zones. The zonegroup placement configuration can be queried with: +.. prompt:: bash # + + radosgw-admin zonegroup get + :: - $ radosgw-admin zonegroup get { "id": "ab01123f-e0df-4f29-9d71-b44888d67cd5", "name": "default", @@ -67,9 +70,12 @@ The zonegroup placement configuration can be queried with: The zone placement configuration can be queried with: +.. prompt:: bash # + + radosgw-admin zone get + :: - $ radosgw-admin zone get { "id": "557cdcee-3aae-4e9e-85c7-2f86f5eddb1f", "name": "default", @@ -107,26 +113,24 @@ Adding a Placement Target To create a new placement target named ``temporary``, add it to the zonegroup: -:: +.. prompt:: bash # - $ radosgw-admin zonegroup placement add \ - --rgw-zonegroup default \ - --placement-id temporary + radosgw-admin zonegroup placement add --rgw-zonegroup default \ + --placement-id temporary Then provide the zone placement info for that target: -:: +.. prompt:: bash # - $ radosgw-admin zone placement add \ - --rgw-zone default \ - --placement-id temporary \ - --data-pool default.rgw.temporary.data \ - --index-pool default.rgw.temporary.index \ - --data-extra-pool default.rgw.temporary.non-ec + radosgw-admin zone placement add --rgw-zone default \ + --placement-id temporary \ + --data-pool default.rgw.temporary.data \ + --index-pool default.rgw.temporary.index \ + --data-extra-pool default.rgw.temporary.non-ec -.. note:: With default placement target settings, RGW stores an object's first data chunk in the RADOS `HEAD` object along - with XATTR metadata. The `--placement-inline-data=false` flag may be passed with the `zone placement add` or - `zone placement modify` commands to change this behavior for new objects stored on the target. +.. note:: With default placement target settings, RGW stores an object's first data chunk in the RADOS ``HEAD`` object along + with XATTR metadata. The ``--placement-inline-data=false`` flag may be passed with the ``zone placement add`` or + ``zone placement modify`` commands to change this behavior for new objects stored on the target. When data is stored inline (default), it may provide an advantage for read/write workloads since the first chunk of an object's data can be retrieved/stored in a single librados call along with object metadata. On the other hand, a target that does not store data inline can provide a performance benefit for RGW client delete requests when @@ -134,7 +138,7 @@ Then provide the zone placement info for that target: slower devices synchronously while processing the client request. In that case, data associated with the deleted objects is removed asynchronously in the background by garbage collection. Note that inlining is only ever performed when writing to the default storage class. Inlining is *never* performed when writing to a non-default - storage class. + storage class. .. _adding_a_storage_class: @@ -144,23 +148,21 @@ Adding a Storage Class To add a new storage class named ``STANDARD_IA`` to the ``default-placement`` target, start by adding it to the zonegroup: -:: +.. prompt:: bash # - $ radosgw-admin zonegroup placement add \ - --rgw-zonegroup default \ - --placement-id default-placement \ - --storage-class STANDARD_IA + radosgw-admin zonegroup placement add --rgw-zonegroup default \ + --placement-id default-placement \ + --storage-class STANDARD_IA Then provide the zone placement info for that storage class: -:: +.. prompt:: bash # - $ radosgw-admin zone placement add \ - --rgw-zone default \ - --placement-id default-placement \ - --storage-class STANDARD_IA \ - --data-pool default.rgw.glacier.data \ - --compression lz4 + radosgw-admin zone placement add --rgw-zone default \ + --placement-id default-placement \ + --storage-class STANDARD_IA \ + --data-pool default.rgw.glacier.data \ + --compression lz4 Customizing Placement ===================== @@ -171,11 +173,10 @@ Default Placement By default, new buckets will use the zonegroup's ``default_placement`` target. This zonegroup setting can be changed with: -:: +.. prompt:: bash # - $ radosgw-admin zonegroup placement default \ - --rgw-zonegroup default \ - --placement-id new-placement + radosgw-admin zonegroup placement default --rgw-zonegroup default \ + --placement-id new-placement User Placement -------------- @@ -185,9 +186,12 @@ target by setting a non-empty ``default_placement`` field in the user info. Similarly, the ``default_storage_class`` can override the ``STANDARD`` storage class applied to objects by default. +.. prompt:: bash # + + radosgw-admin user info --uid testid + :: - $ radosgw-admin user info --uid testid { ... "default_placement": "", @@ -203,13 +207,12 @@ to restrict access to certain types of storage. The ``radosgw-admin`` command can modify these fields directly with: -:: +.. prompt:: bash # - $ radosgw-admin user modify \ - --uid \ - --placement-id \ - --storage-class \ - --tags + radosgw-admin user modify --uid \ + --placement-id \ + --storage-class \ + --tags .. _s3_bucket_placement: @@ -217,10 +220,10 @@ S3 Bucket Placement ------------------- When creating a bucket with the S3 protocol, a placement target can be -provided as part of the LocationConstraint to override the default placement +provided as part of the ``LocationConstraint`` to override the default placement targets from the user and zonegroup. -Normally, the LocationConstraint must match the zonegroup's ``api_name``: +Normally, the ``LocationConstraint`` must match the zonegroup's ``api_name``: ::