Merge pull request ceph#62871 from cbodley/wip-doc-rgw-user-admin-system

doc/rgw: document Admin and System Users

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

Author: cbodley

doc/radosgw/admin.rst

@@ -364,7 +364,7 @@ To remove a Swift secret key, run a command of the following form:
 Add or Remove Admin Capabilities
 --------------------------------
 
-The Ceph Storage Cluster provides an administrative API that enables users to
+The Ceph Storage Cluster provides an `Admin Ops API`_ that enables users to
 execute administrative functions via the REST API. By default, users do NOT
 have access to this API. To enable a user to exercise administrative
 functionality, provide the user with administrative capabilities.
@@ -397,8 +397,41 @@ following form:
 .. prompt:: bash
 
    radosgw-admin caps rm --uid=johndoe --caps={caps}
-  
 
+Admin and System Users
+----------------------
+
+Users with the ``--admin`` or ``--system`` flag have global read and write
+permissions. These permissions apply to all APIs including S3 and Swift,
+unlike Admin Capabilities, and cannot be denied by IAM policy.
+
+The ``--system`` flag should only be used as documented in `Multisite Configuration`_.
+
+The ``--admin`` flag can be useful for troubleshooting and recovery. For
+example, if a user accidentally removes their permissions to a bucket or
+object, the admin user's credentials can be used to issue the S3/Swift API
+requests necessary to restore them.
+
+.. warning:: When not in use, consider deleting the admin user or disabling
+   its access keys. Do not give admin permissions to untrusted users.
+
+To create an admin user:
+
+.. prompt:: bash
+
+   radosgw-admin user create --uid={username} --display-name="{display-name}" --admin
+
+To add the admin flag to an existing user:
+
+.. prompt:: bash
+
+   radosgw-admin user modify --uid={username} --admin
+
+To remove the admin flag from an existing user:
+
+.. prompt:: bash
+
+   radosgw-admin user modify --uid={username} --admin=0
 
 Quota Management
 ================
@@ -902,3 +935,5 @@ example commands:
 .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/
 .. _Ceph Object Gateway Config Reference: ../config-ref/
 .. _Accounts: ../account/
+.. _Admin Ops API: ../adminops/
+.. _Multisite Configuration: ../multisite/