src/common/options: Improve descriptions in rgw.yaml.in

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

Author: anthonyeleven

src/common/options/rgw.yaml.in

@@ -132,8 +132,10 @@ options:
   level: advanced
   desc: The maximum size (in bytes) of regular (non multi-part) object upload.
   long_desc: Plain object upload is capped at this amount of data. In order to upload
-    larger objects, a special upload mechanism is required. The S3 API provides the
-    multi-part upload, and Swift provides DLO and SLO.
+    larger objects, a special composite upload mechanism is required: multi-part upload (MPU) for S3
+    and DLO and SLO for Swift.  Note that this value also limits the size of individual
+    chunks uploaded for MPU and DLO/SLO objects, thus the larget composite object
+    that can be uploaded is of size ``rgw_max_put_size`` * ``rgw_multipart_part_upload_limit``
   default: 5_G
   services:
   - rgw
@@ -248,7 +250,7 @@ options:
   type: bool
   level: advanced
   desc: Enables the lifecycle maintenance thread. This is required on at least one
-    rgw for each zone.
+    RGW daemon for each zone.
   long_desc: The lifecycle maintenance thread is responsible for lifecycle related
     maintenance work. The thread itself can be disabled, but in order for lifecycle
     to work correctly, at least one RGW in each zone needs to have this thread running.
@@ -276,11 +278,11 @@ options:
 - name: rgw_enable_apis
   type: str
   level: advanced
-  desc: A list of set of RESTful APIs that rgw handles.
+  desc: A list of RESTful APIs for RGW to enable
   fmt_desc: |
     Enables the specified APIs.
 
-      .. note:: Enabling the ``s3`` API is a requirement for
+      .. note:: Enabling the ``S3`` API is a requirement for
                 any ``radosgw`` instance that is meant to
                 participate in a `multi-site <../multisite>`_
                 configuration.
@@ -338,7 +340,7 @@ options:
 - name: rgw_numa_node
   type: int
   level: advanced
-  desc: set rgw's cpu affinity to a numa node (-1 for none)
+  desc: set the RGW daemon'ss CPU affinity to a NUMA node (-1 for none)
   default: -1
   services:
   - rgw
@@ -855,7 +857,7 @@ options:
   level: advanced
   desc: RGW Keystone implicit tenants creation
   long_desc: Implicitly create new users in their own tenant with the same name when
-    authenticating via Keystone.  Can be limited to s3 or swift only.
+    authenticating via Keystone.  Can be limited to S3 or SWIFT only.
   default: 'false'
   services:
   - rgw
@@ -889,27 +891,27 @@ options:
 - name: rgw_s3_auth_use_rados
   type: bool
   level: advanced
-  desc: Should S3 authentication use credentials stored in RADOS backend.
+  desc: Specify whether S3 authentication uses credentials stored in RADOS
   default: true
   services:
   - rgw
   with_legacy: true
 - name: rgw_s3_auth_use_keystone
   type: bool
   level: advanced
-  desc: Should S3 authentication use Keystone.
+  desc: Specify whether S3 authentication uses Keystone
   default: false
   services:
   - rgw
   with_legacy: true
 - name: rgw_s3_auth_order
   type: str
   level: advanced
-  desc: Authentication strategy order to use for s3 authentication
-  long_desc: Order of authentication strategies to try for s3 authentication, the
-    allowed options are a comma separated list of engines external, local. The default
-    order is to try all the externally configured engines before attempting local
-    rados based authentication
+  desc: Authentication strategy order to use for S3
+  long_desc: The order of authentication strategies to try for S3 authentication. The
+    value is a comma-separated list of engines, external and local. The default
+    order is to try all configured external engines before attempting local
+    RADOS based authentication
   default: sts, external, local
   services:
   - rgw
@@ -2436,9 +2438,8 @@ options:
   type: bool
   level: basic
   desc: Enable static website APIs
-  long_desc: This configurable controls whether RGW handles the website control APIs.
-    RGW can server static websites if s3website hostnames are configured, and unrelated
-    to this configurable.
+  long_desc: This configurable controls whether RGW enables the website control APIs.
+    RGW can serve static websites if S3 website hostnames are configured.
   default: false
   services:
   - rgw
@@ -2447,7 +2448,7 @@ options:
   type: bool
   level: basic
   desc: Enable elastic metadata search APIs
-  long_desc: This configurable controls whether RGW handles the elastic metadata search APIs.
+  long_desc: This configurable controls whether RGW enables the elastic metadata search APIs.
   default: true
   services:
   - rgw
@@ -2843,7 +2844,7 @@ options:
   services:
   - rgw
   with_legacy: true
-- name: rgw_crypt_s3_kms_backend
+ name: rgw_crypt_s3_kms_backend
   type: str
   level: advanced
   desc: Where the SSE-KMS encryption keys are stored. Supported KMS systems are OpenStack
@@ -3082,7 +3083,7 @@ options:
 - name: rgw_crypt_sse_s3_key_template
   type: str
   level: advanced
-  desc: template for per-bucket sse-s3 keys in vault.
+  desc: template for per-bucket SSE-S3 keys in Vault.
   long_desc: This is the template for per-bucket sse-s3 keys.
     This string may include ``%bucket_id`` which will be expanded out to
     the bucket marker, a unique uuid assigned to that bucket.