doc: rgw: Rewrite the key management

The create/remove key section in the doc is a bit confusing.
Rewrite it and give more examples.

Signed-off-by: hrchu <hrchu@cht.com.tw>

diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst
index 06d0cc608d90af428a4984258add072480d85368..7d83e5197f948a69633859fe7a681430b447d31e 100644 (file)
--- a/doc/radosgw/admin.rst
+++ b/doc/radosgw/admin.rst
@@ -211,61 +211,89 @@ Options include:
   to the UID.
 
 
-Create a Key
-------------
+Add / Remove a Key
+------------------------
+
+Both users and subusers require the key to access the S3 or Swift interface. To
+use S3, the user needs a key pair which is composed of an access key and a 
+secret key. On the other hand, to use Swift, the user typically needs a secret 
+key (password), and use it together with the associated user ID. You may create
+a key and either specify or generate the access key and/or secret key. You may 
+also remove a key. Options include:
+
+- ``--key-type=<type>`` specifies the key type. The options are: s3, swift
+- ``--access-key=<key>`` manually specifies an S3 access key.
+- ``--secret-key=<key>`` manually specifies a S3 secret key or a Swift secret key.
+- ``--gen-access-key`` automatically generates a S3 key.
+- ``--gen-secret`` automatically generates a S3 secret key or a Swift secret key.
 
-To create a key for a user, you must specify ``key create``. For a user, specify
-the user ID and the ``s3`` key type. To create a key for subuser, you must
-specify the subuser ID and the ``swift`` keytype. For example::
+An example how to add a specified S3 key pair for a user. ::
 
-       radosgw-admin key create --subuser=johndoe:swift --key-type=swift --gen-secret
+       radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey
 
 .. code-block:: javascript
 
-  { "user_id": "johndoe",
+  { "user_id": "foo",
     "rados_uid": 0,
-    "display_name": "John Doe",
-    "email": "john@example.com",
+    "display_name": "foo",
+    "email": "foo@example.com",
     "suspended": 0,
-    "subusers": [
-       { "id": "johndoe:swift",
-         "permissions": "full-control"}],
     "keys": [
-      { "user": "johndoe",
-        "access_key": "QFAMEDSJP5DEKJO0DDXY",
-        "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}],
-    "swift_keys": [
-      { "user": "johndoe:swift",
-        "secret_key": "E9T2rUZNu2gxUjcwUBO8n\/Ev4KX6\/GprEuH4qhu1"}]}
+      { "user": "foo",
+        "access_key": "fooAccessKey",
+        "secret_key": "fooSecretKey"}],
+  }
 
+Note that you may create multiple S3 key pairs for a user.
 
+To attach a specified swift secret key for a subuser. ::
 
-Add / Remove Access Keys
-------------------------
+       radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret
+
+.. code-block:: javascript
 
-Users and subusers must have access keys to use the S3 and Swift
-interfaces. When you create a user or subuser and you do not specify 
-an access key and secret, the key and secret get generated automatically. 
-You may create a key and either specify or generate the access key and/or
-secret. You may also remove an access key and secret. Options include:
+  { "user_id": "foo",
+    "rados_uid": 0,
+    "display_name": "foo",
+    "email": "foo@example.com",
+    "suspended": 0,
+    "subusers": [
+       { "id": "foo:bar",
+         "permissions": "full-control"}],
+    "swift_keys": [
+      { "user": "foo:bar",
+        "secret_key": "asfghjghghmgm"}]}
 
+Note that a subuser can have only one swift secret key.
 
-- ``--secret=<key>`` specifies a secret key (e.g,. manually generated).
-- ``--gen-access-key`` generates random access key (for S3 user by default).
-- ``--gen-secret`` generates a random secret key.
-- ``--key-type=<type>`` specifies a key type. The options are: swift, s3
+Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. ::     
 
+       radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey
+       
+.. code-block:: javascript
 
-To add a key, specify the user. ::
+  { "user_id": "foo",
+    "rados_uid": 0,
+    "display_name": "foo",
+    "email": "foo@example.com",
+    "suspended": 0,
+    "subusers": [
+       { "id": "foo:bar",
+         "permissions": "full-control"}],
+    "keys": [
+      { "user": "foo:bar",
+        "access_key": "barAccessKey",
+        "secret_key": "barSecretKey"}],
+  }
 
-       radosgw-admin key create --uid=johndoe --key-type=s3 --gen-access-key --gen-secret
 
-You may also specify a key and a secret.
+To remove a S3 key pair, specify the access key. :: 
 
-To remove an access key, specify the user. :: 
+       radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey 
 
-       radosgw-admin key rm --uid=johndoe
+To remove the swift secret key. ::
 
+       radosgw-admin key rm -subuser=foo:bar --key-type=swift
 
 
 Add / Remove Admin Capabilities