Merge pull request ceph#62763 from bluikko/doc-prompts-radosgw

doc/radosgw: Promptify CLI, cosmetic fixes

Reviewed-by: Anthony D'Atri <[email protected]>

Author: zdover23

doc/radosgw/archive-sync-module.rst

@@ -30,11 +30,13 @@ See `Multisite Configuration`_ for multisite configuration instructions. The
 archive sync module requires the creation of a new zone. The zone tier type needs
 to be defined as ``archive``:
 
-::
+.. prompt:: bash #
+
+   radosgw-admin zone create --rgw-zonegroup={zone-group-name} \
+                               --rgw-zone={zone-name} \
+                               --endpoints={http://fqdn}[,{http://fqdn}] \
+                               --tier-type=archive
+
 
-    # radosgw-admin zone create --rgw-zonegroup={zone-group-name} \
-                                --rgw-zone={zone-name} \
-                                --endpoints={http://fqdn}[,{http://fqdn}]
-                                --tier-type=archive
 
 .. _Multisite Configuration: ../multisite

doc/radosgw/cloud-restore.rst

@@ -1,6 +1,6 @@
-===============
- Cloud Restore 
-===============
+=============
+Cloud Restore
+=============
 
 The :doc:`cloud-transition>` feature makes it possible to transition objects to a remote
 cloud service. The ``cloud-restore`` feature described below enables restoration
@@ -12,23 +12,22 @@ S3-compatible cloud services. In order to faciliate this,
 the ``retain_head_object`` option should be set to ``true``
 in the ``tier-config`` when configuring the storage class.
 
-Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`
-PI . The restored copies will be retained within RGW only for the number
+Objects can be restored using the `S3 RestoreObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html>`_
+API. The restored copies will be retained within RGW only for the number
 of ``days`` specified. However if ``days`` is not provided, the restored copies
 are considered permanent and will be treated as regular objects.
 In addition, by enabling the ``allow_read_through`` option,
-the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`
+the `S3 GetObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html>`_
 API can be used to restore the object temporarily.
 
 
 Cloud Storage Class Tier Configuration
 --------------------------------------
 
-The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`
+The `tier configuration <https://docs.ceph.com/en/latest/radosgw/cloud-transition/#cloud-storage-class-configuration>`_
 of the cloud storage class configured for data transition is used to restore
-objects as well:
+objects as well::
 
-```
     {
       "access_key": <access>,
       "secret": <secret>,`
@@ -44,7 +43,6 @@ objects as well:
       "multipart_min_part_size": {part_size},
       "retain_head_object": <true | false>
     }
-```
 
 The below options have been added to the tier configuration to facilitate object restoration.
 
@@ -53,7 +51,7 @@ The below options have been added to the tier configuration to facilitate object
 The storage class to which object data is to be restored. Default value is ``STANDARD``.
 
 
-read-through specific Configurables:
+Read-through Specific Configurables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ``allow_read_through`` (``true`` | ``false``)
@@ -67,20 +65,21 @@ Default value is 1 day.
 
 For example:
 
-```
-    # radosgw-admin zonegroup placement modify --rgw-zonegroup default \
-                                               --placement-id default-placement \
-                                               --storage-class CLOUDTIER \
-                                               --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
-                                               access_key=<access_key>,secret=<secret>, \
-                                               retain_head_object=true, \
-                                               restore_storage_class=COLDTIER, \
-                                               allow_read_through=true, \
-                                               read_through_restore_days=10
-```
+.. prompt:: bash #
 
+   radosgw-admin zonegroup placement modify --rgw-zonegroup default \
+                                              --placement-id default-placement \
+                                              --storage-class CLOUDTIER \
+                                              --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
+                                              access_key=<access_key>,secret=<secret>, \
+                                              retain_head_object=true, \
+                                              restore_storage_class=COLDTIER, \
+                                              allow_read_through=true, \
+                                              read_through_restore_days=10
 
-S3 Glacier specific Configurables:
+
+
+S3 Glacier Specific Configurables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To restore objects archived in an S3 Glacier or Tape cloud storage class, the
@@ -101,26 +100,27 @@ pricing. Supported options are ``Standard`` and ``Expedited``.
 
 For example:
 
-```
-    # radosgw-admin zonegroup placement add --rgw-zonegroup=default \
-                                            --placement-id=default-placement \
-                                            --storage-class=CLOUDTIER-GLACIER --tier-type=cloud-s3-glacier
-
-    # radosgw-admin zonegroup placement modify --rgw-zonegroup default \
-                                               --placement-id default-placement \
-                                               --storage-class CLOUDTIER \
-                                               --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
-                                               access_key=XXXXX,secret=YYYYY, \
-                                               retain_head_object=true, \
-                                               target_storage_class=Glacier, \
-                                               ............
-                                               ............
-                                               restore_storage_class=COLDTIER, \
-                                               glacier_restore_days=2, \
-                                               glacier_restore_tier_type=Expedited
-
-
-     [
+.. prompt:: bash #
+
+   radosgw-admin zonegroup placement add --rgw-zonegroup=default \
+                                           --placement-id=default-placement \
+                                           --storage-class=CLOUDTIER-GLACIER --tier-type=cloud-s3-glacier
+   radosgw-admin zonegroup placement modify --rgw-zonegroup default \
+                                              --placement-id default-placement \
+                                              --storage-class CLOUDTIER \
+                                              --tier-config=endpoint=http://XX.XX.XX.XX:YY,\
+                                              access_key=XXXXX,secret=YYYYY, \
+                                              retain_head_object=true, \
+                                              target_storage_class=Glacier, \
+                                              ............ \
+                                              ............ \
+                                              restore_storage_class=COLDTIER, \
+                                              glacier_restore_days=2, \
+                                              glacier_restore_tier_type=Expedited
+
+::
+
+    [
         {
             "key": "default-placement",
             "val": {
@@ -159,47 +159,47 @@ For example:
             }
         }
     ]
-```
 
 
-Examples of Restore Objects:
-----------------------------
+Examples of Restore Objects
+---------------------------
 
 Using the S3 RestoreObject CLI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Th `S3 restore-object <https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`
+Th `S3 restore-object <https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`_
 CLI supports these options:
 
-```
-  $ aws s3api restore-object 
-            --bucket <value>
-            --key <value>
-            [--version-id <value>]
-            --restore-request (structure) {
-              Days=<integer>
-            }
-```
+.. prompt:: bash $
+
+   aws s3api restore-object --bucket <value> \
+                              --key <value> \
+                              [--version-id <value>] \
+                              --restore-request (structure) { \
+                                Days=<integer> \
+                              }
+
 
 Note: ``Days`` is optional and if not provided, the object is restored permanently.
 
 Example 1:
 
-```
-  $ aws s3api restore-object  --bucket bucket1 --key doc1.rtf 
-                              [--version-id 3sL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo]
-                              --restore-request Days=10 
+.. prompt:: bash $
+
+   aws s3api restore-object --bucket bucket1 --key doc1.rtf \
+                              [--version-id 3sL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo] \
+                              --restore-request Days=10 \
                               ....
-```
+
 
 This will restore the object ``doc1.rtf`` at an optional version,
 for the duration of 10 days.
 
 Example 2:
 
-```
-  $ aws s3api restore-object  --bucket bucket1 --key doc2.rtf --restore-request {} ....
-```
+.. prompt:: bash $
+
+   aws s3api restore-object --bucket bucket1 --key doc2.rtf --restore-request {} ....
 
 
 This will restore the object ``doc2.rtf`` permanently and it will be treated as regular object.
@@ -212,59 +212,62 @@ Ensure that the ``allow_read_through`` tier-config option is enabled.
 
 Example 3:
 
-```
-  $ aws s3api get-object  --bucket bucket1 --key doc3.rtf ....
-```
+.. prompt:: bash $
+
+   aws s3api get-object --bucket bucket1 --key doc3.rtf ....
+
 
 This will restore the object `doc3.rtf`` for ``read_through_restore_days`` days.
 
 Note: The above CLI command may time out if object restoration takes too long.
 You can verify the restore status before reissuing the command.
 
 
-Verifying the restoration status
+Verifying the Restoration Status
 --------------------------------
 Verify the status of the restoration by issuing
-an `S3 HeadObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html#API_HeadObject_ResponseSyntax>`
+an `S3 HeadObject <https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html#API_HeadObject_ResponseSyntax>`_
 request. The response includes the ``x-amz-restore`` header if object restoration
 is in progress or a copy of it is already restored.
 
 Example:
 
-```
-  $ aws s3api head-object --key doc1.rtf --bucket bucket1 ....
-```
+.. prompt:: bash $
+
+   aws s3api head-object --key doc1.rtf --bucket bucket1 ....
+
 
 The ``radosgw-admin`` CLI can be used to check restoration status and other
 details.
 
 Example:
 
-```  
- $ radosgw-admin object stat --bucket bucket1 --object doc1.rtf
-```
+.. prompt:: bash $
+
+   radosgw-admin object stat --bucket bucket1 --object doc1.rtf
+
 
 
 Restored Object Properties
 --------------------------
 
 Storage
-~~~~~~
+~~~~~~~
 Objects are restored to the storage class configured via ``restore_storage_class``
 in the tier-config. However, as
-per `<https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`
+per `<https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html>`_
 the storage class of restored objects should remain unchanged. Therefore, for
-temporary copies, the ```x-amz-storage-class``` will continue to reflect the
+temporary copies, the ``x-amz-storage-class`` will continue to reflect the
 original cloud-tier storage class.
 
 
 mtime
-~~~~
+~~~~~
 The ``mtime`` of the transitioned and restored objects should remain unchanged.
 
 
 Lifecycle
-~~~~~~~~
+~~~~~~~~~
 ``Temporary`` copies are not subject to transition to the cloud. However, as is the
 case with cloud-transitioned objects, they can be deleted via regular LC (Life Cycle)
 expiration rules or an external S3 ``delete`` request.
@@ -274,15 +277,15 @@ policies.
 
 
 Replication
-~~~~~~~~~~
+~~~~~~~~~~~
 ``Temporary`` copies are not replicated and will be retained only by the zone
 on which the restore request is initiated.
 
 ``Permanent`` copies are replicated like other regular objects.
 
 
 Versioned Objects
-~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 For versioned objects, if an object has been cloud-transitioned, it is in a
 non-current state. After a restore, the same non-current object will be
 updated with the downloaded data, and its ``HEAD`` object will be modified accordingly.