From c038c70f695158d16407d7604ce3f252e8fdebf5 Mon Sep 17 00:00:00 2001 From: Ville Ojamo <14869000+bluikko@users.noreply.github.com> Date: Mon, 28 Apr 2025 16:19:22 +0700 Subject: [PATCH] doc/radosgw: Promptify CLI commands and fix formatting in layout.rst Move two example CLI command blocks to use a bash prompt block with the correct privileged prompt instead of hardcoded unprivileged prompt. Don't use the directory "bin/" in command "bin/radosgw-admin" especially when the next commands also don't use it. Fix 2 instances of double-backtick missing the second backtick that caused the rendered doc to be jumbled. Do not use _emphasis_ that renders as underscores, instead use RST syntax for italic for the word. Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com> (cherry picked from commit 6783245e98be4bd83be754fa39353d268e25b896) --- doc/radosgw/layout.rst | 51 ++++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 19 deletions(-) diff --git a/doc/radosgw/layout.rst b/doc/radosgw/layout.rst index 934d3d4a36782..8fea58eec67a6 100644 --- a/doc/radosgw/layout.rst +++ b/doc/radosgw/layout.rst @@ -25,9 +25,14 @@ Metadata ^^^^^^^^ RGW stores multiple types of metadata. The list of types can be shown -with the below command. The types as of 2025 April are shown below:: +with the below command. The types as of 2025 April are shown below: + +.. prompt:: bash # + + radosgw-admin metadata list + +:: - $ bin/radosgw-admin metadata list [ "account", "bucket", @@ -39,16 +44,17 @@ with the below command. The types as of 2025 April are shown below:: "user" ] -Use commands of the following forms to inspect metadata entries: :: +Use commands of the following forms to inspect metadata entries: - $ radosgw-admin metadata list - $ radosgw-admin metadata list bucket - $ radosgw-admin metadata list bucket.instance - $ radosgw-admin metadata list user +.. prompt:: bash # - $ radosgw-admin metadata get bucket: - $ radosgw-admin metadata get bucket.instance:: - $ radosgw-admin metadata get user: # get or set + radosgw-admin metadata list + radosgw-admin metadata list bucket + radosgw-admin metadata list bucket.instance + radosgw-admin metadata list user + radosgw-admin metadata get bucket: + radosgw-admin metadata get bucket.instance:: + radosgw-admin metadata get user: # get or set Variables are used in above command examples; when issuing commands you must substitute your specific values: @@ -115,11 +121,18 @@ different users\` buckets will be created in different RADOS pools by default, thus providing the necessary scaling. The layout and naming of these pools is controlled by a 'policy' setting.[3] -An RGW object may consist of several RADOS objects, the first of which -is the head that contains the metadata, such as manifest, ACLs, content type, -ETag, and user-defined metadata. The metadata is stored in xattrs. -The head may also contain up to :confval:`rgw_max_chunk_size` of object data, for efficiency -and atomicity. The manifest describes how each object is laid out in RADOS +An RGW object may consist of several RADOS objects, the first of which is the +head that contains the metadata, such as manifest, ACLs, content type, ETag, +and user-defined metadata. The metadata is stored in xattrs. The ``HEAD`` +object may also inline up to :confval:`rgw_max_chunk_size` of object data, for +efficiency and atomicity. This enables a convenenient tiering strategy: index +pools are necessarily replicated (cannot be EC) and should be placed on fast +SSD OSDs. With a mix of small/hot RGW objects and larger, warm/cold RGW +objects like video files, the larger objects will automatically be placed in +the ``buckets.data`` pool, which may be EC and/or slower storage like HDDs or +QLC SSDs. + +The manifest describes how each RGW object is laid out across RADOS objects. Bucket and Object Listing @@ -185,8 +198,8 @@ Known pools: prodtx/test%25star testcont - namespace: users.uid - Contains _both_ per-user information (RGWUserInfo) in "" objects + namespace: ``users.uid`` + Contains *both* per-user information (RGWUserInfo) in "" objects and per-user lists of buckets in omaps of ".buckets" objects. The "" may contain the tenant if non-empty, for example:: @@ -215,7 +228,7 @@ Known pools: default.7593.4__shadow_.488urDFerTYXavx4yAd-Op8mxehnvTI_1 _ -An example of a marker would be "default.16004.1" or "default.7593.4". -The current format is "..". But once +An example of a marker would be ``default.16004.1`` or ``default.7593.4``. +The current format is ``..``. But once generated, a marker is not parsed again, so its format may change freely in the future. -- 2.39.5