doc/rgw: use 'confval' directive to render sts config options

the 'confval' directive reads the config options from
common/options/rgw.yaml and renders them nicely. this keeps
everything consistent between the options and their docs

improve the config option descriptions:

* add existing note about rgw_sts_key length/format
* add example openssl command to generate a conforming sts key
* add notes about sharing sts key between gateways/zones

format the last remaining 'Note' with the 'note' directive

Signed-off-by: Casey Bodley <cbodley@redhat.com>
(cherry picked from commit 6389ff4bcb6562a43b60ccd83e7aa3b150372079)

diff --git a/doc/radosgw/STS.rst b/doc/radosgw/STS.rst
index bc89b89da6096139cb632c9e23cc8b84904e5ad5..5207530f87be44705c9552a83db9c0af00219779 100644 (file)
--- a/doc/radosgw/STS.rst
+++ b/doc/radosgw/STS.rst
@@ -90,17 +90,13 @@ RGW now supports Session tags that can be passed in the web token to AssumeRoleW
 STS Configuration
 =================
 
-The following configurable options have to be added for STS integration::
+The following configurable options have to be added for STS integration:
 
-  [client.{your-rgw-name}]
-  rgw_sts_key = {sts key for encrypting the session token}
-  rgw_s3_auth_use_sts = true
+.. confval:: rgw_sts_key
+.. confval:: rgw_s3_auth_use_sts
 
-Notes: 
-
-* By default, STS and S3 APIs co-exist in the same namespace, and both S3
-  and STS APIs can be accessed via the same endpoint in Ceph Object Gateway.
-* The ``rgw_sts_key`` needs to be a hex-string consisting of exactly 16 characters.
+.. note:: The STS and S3 APIs co-exist in the same namespace, and both S3
+   and STS APIs can be accessed via the same endpoint.
 
 Examples
 ========

diff --git a/src/common/options/rgw.yaml.in b/src/common/options/rgw.yaml.in
index 09461148757d71d5d089a72f90bdce5af49163a6..2313f120178203b481c76cb14afc93e6b2708884 100644 (file)
--- a/src/common/options/rgw.yaml.in
+++ b/src/common/options/rgw.yaml.in
@@ -3264,7 +3264,11 @@ options:
   type: str
   level: advanced
   desc: STS Key
-  long_desc: Key used for encrypting/ decrypting session token.
+  long_desc: Key used for encrypting/ decrypting role session tokens.
+    This key must consist of 16 hexadecimal characters, which can be
+    generated by the command 'openssl rand -hex 16'. All radosgw instances
+    in a zone should use the same key. In multisite configurations, all
+    zones in a realm should use the same key.
   default: sts
   services:
   - rgw