diff options
Diffstat (limited to 'doc/radosgw')
| -rw-r--r-- | doc/radosgw/admin.rst | 697 | ||||
| -rw-r--r-- | doc/radosgw/adminops.rst | 10 | ||||
| -rw-r--r-- | doc/radosgw/compression.rst | 40 | ||||
| -rw-r--r-- | doc/radosgw/index.rst | 10 | ||||
| -rw-r--r-- | doc/radosgw/multisite.rst | 74 | ||||
| -rw-r--r-- | doc/radosgw/notifications.rst | 4 | ||||
| -rw-r--r-- | doc/radosgw/pools.rst | 17 | ||||
| -rw-r--r-- | doc/radosgw/rgw-cache.rst | 3 | ||||
| -rw-r--r-- | doc/radosgw/role.rst | 82 | ||||
| -rw-r--r-- | doc/radosgw/session-tags.rst | 2 |
10 files changed, 593 insertions, 346 deletions
diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst index 8d70252fe..fe29849cb 100644 --- a/doc/radosgw/admin.rst +++ b/doc/radosgw/admin.rst @@ -2,25 +2,23 @@ Admin Guide ============= -Once you have your Ceph Object Storage service up and running, you may -administer the service with user management, access controls, quotas -and usage tracking among other features. - +After the Ceph Object Storage service is up and running, it can be administered +with user management, access controls, quotas, and usage tracking. User Management =============== -Ceph Object Storage user management refers to users of the Ceph Object Storage -service (i.e., not the Ceph Object Gateway as a user of the Ceph Storage -Cluster). You must create a user, access key and secret to enable end users to -interact with Ceph Object Gateway services. +Ceph Object Storage user management refers only to users of the Ceph Object +Storage service and not to the Ceph Object Gateway as a user of the Ceph +Storage Cluster. Create a user, access key, and secret key to enable end users +to interact with Ceph Object Gateway services. -There are two user types: +There are two types of user: -- **User:** The term 'user' reflects a user of the S3 interface. +- **User:** The term "user" refers to user of the S3 interface. -- **Subuser:** The term 'subuser' reflects a user of the Swift interface. A subuser - is associated to a user . +- **Subuser:** The term "subuser" refers to a user of the Swift interface. A + subuser is associated with a user. .. ditaa:: +---------+ @@ -31,24 +29,30 @@ There are two user types: +-----+ Subuser | +-----------+ -You can create, modify, view, suspend and remove users and subusers. In addition -to user and subuser IDs, you may add a display name and an email address for a -user. You can specify a key and secret, or generate a key and secret -automatically. When generating or specifying keys, note that user IDs correspond -to an S3 key type and subuser IDs correspond to a swift key type. Swift keys -also have access levels of ``read``, ``write``, ``readwrite`` and ``full``. +Users and subusers can be created, modified, viewed, suspended and removed. +you may add a Display names and an email addresses can be added to user +profiles. Keys and secrets can either be specified or generated automatically. +When generating or specifying keys, remember that user IDs correspond to S3 key +types and subuser IDs correspond to Swift key types. + +Swift keys have access levels of ``read``, ``write``, ``readwrite`` and +``full``. Create a User ------------- -To create a user (S3 interface), execute the following:: +To create a user (S3 interface), run a command of the following form: + +.. prompt:: bash - radosgw-admin user create --uid={username} --display-name="{display-name}" [--email={email}] + radosgw-admin user create --uid={username} --display-name="{display-name}" [--email={email}] -For example:: +For example: + +.. prompt:: bash - radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com + radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com .. code-block:: javascript @@ -75,32 +79,37 @@ For example:: "max_objects": -1}, "temp_url_keys": []} -Creating a user also creates an ``access_key`` and ``secret_key`` entry for use -with any S3 API-compatible client. +The creation of a user entails the creation of an ``access_key`` and a +``secret_key`` entry, which can be used with any S3 API-compatible client. -.. important:: Check the key output. Sometimes ``radosgw-admin`` - generates a JSON escape (``\``) character, and some clients - do not know how to handle JSON escape characters. Remedies include - removing the JSON escape character (``\``), encapsulating the string - in quotes, regenerating the key and ensuring that it - does not have a JSON escape character or specify the key and secret - manually. +.. important:: Check the key output. Sometimes ``radosgw-admin`` generates a + JSON escape (``\``) character, and some clients do not know how to handle + JSON escape characters. Remedies include removing the JSON escape character + (``\``), encapsulating the string in quotes, regenerating the key and + ensuring that it does not have a JSON escape character, or specifying the + key and secret manually. Create a Subuser ---------------- -To create a subuser (Swift interface) for the user, you must specify the user ID -(``--uid={username}``), a subuser ID and the access level for the subuser. :: +To create a subuser (a user of the Swift interface) for the user, specify the +user ID (``--uid={username}``), a subuser ID, and the subuser's access level: + +.. prompt:: bash - radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ] + radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ] -For example:: +For example: - radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full +.. prompt:: bash + radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full -.. note:: ``full`` is not ``readwrite``, as it also includes the access control policy. + +.. note:: ``full`` is not the same as ``readwrite``. The ``full`` access level + includes ``read`` and ``write``, but it also includes the access control + policy. .. code-block:: javascript @@ -133,102 +142,128 @@ For example:: Get User Info ------------- -To get information about a user, you must specify ``user info`` and the user ID -(``--uid={username}``) . :: +To get information about a user, specify ``user info`` and the user ID +(``--uid={username}``). Use a command of the following form: - radosgw-admin user info --uid=johndoe +.. prompt:: bash + radosgw-admin user info --uid=johndoe Modify User Info ---------------- -To modify information about a user, you must specify the user ID (``--uid={username}``) -and the attributes you want to modify. Typical modifications are to keys and secrets, -email addresses, display names and access levels. For example:: +To modify information about a user, specify the user ID (``--uid={username}``) +and the attributes that you want to modify. Typical modifications are made to +keys and secrets, email addresses, display names, and access levels. Use a +command of the following form: - radosgw-admin user modify --uid=johndoe --display-name="John E. Doe" +.. prompt:: bash -To modify subuser values, specify ``subuser modify``, user ID and the subuser ID. For example:: + radosgw-admin user modify --uid=johndoe --display-name="John E. Doe" - radosgw-admin subuser modify --uid=johndoe --subuser=johndoe:swift --access=full +To modify subuser values, specify ``subuser modify``, user ID and the subuser +ID. Use a command of the following form: +.. prompt:: bash -User Enable/Suspend -------------------- + radosgw-admin subuser modify --uid=johndoe --subuser=johndoe:swift --access=full + + +User Suspend +------------ -When you create a user, the user is enabled by default. However, you may suspend -user privileges and re-enable them at a later time. To suspend a user, specify -``user suspend`` and the user ID. :: +When a user is created, the user is enabled by default. However, it is possible +to suspend user privileges and to re-enable them at a later time. To suspend a +user, specify ``user suspend`` and the user ID in a command of the following +form: - radosgw-admin user suspend --uid=johndoe +.. prompt:: bash -To re-enable a suspended user, specify ``user enable`` and the user ID. :: + radosgw-admin user suspend --uid=johndoe - radosgw-admin user enable --uid=johndoe +User Enable +----------- +To re-enable a suspended user, provide ``user enable`` and specify the user ID +in a command of the following form: + +.. prompt:: bash + + radosgw-admin user enable --uid=johndoe -.. note:: Disabling the user disables the subuser. +.. note:: Disabling the user also disables any subusers. Remove a User ------------- -When you remove a user, the user and subuser are removed from the system. -However, you may remove just the subuser if you wish. To remove a user (and -subuser), specify ``user rm`` and the user ID. :: +When you remove a user, you also remove any subusers associated with the user. - radosgw-admin user rm --uid=johndoe +It is possible to remove a subuser without removing its associated user. This +is covered in the section called :ref:`Remove a Subuser <radosgw-admin-remove-a-subuser>`. -To remove the subuser only, specify ``subuser rm`` and the subuser ID. :: +To remove a user and any subusers associated with it, use the ``user rm`` +command and provide the user ID of the user to be removed. Use a command of the +following form: - radosgw-admin subuser rm --subuser=johndoe:swift +.. prompt:: bash + radosgw-admin user rm --uid=johndoe Options include: - **Purge Data:** The ``--purge-data`` option purges all data associated - to the UID. + with the UID. - **Purge Keys:** The ``--purge-keys`` option purges all keys associated - to the UID. + with the UID. +.. _radosgw-admin-remove-a-subuser: Remove a Subuser ---------------- -When you remove a sub user, you are removing access to the Swift interface. -The user will remain in the system. To remove the subuser, specify -``subuser rm`` and the subuser ID. :: +Removing a subuser removes access to the Swift interface or to S3. The user +associated with the removed subuser remains in the system after the subuser's +removal. - radosgw-admin subuser rm --subuser=johndoe:swift +To remove the subuser, use the command ``subuser rm`` and provide the subuser +ID of the subuser to be removed. Use a command of the following form: +.. prompt:: bash + radosgw-admin subuser rm --subuser=johndoe:swift Options include: - **Purge Keys:** The ``--purge-keys`` option purges all keys associated - to the UID. + with the UID. -Add / Remove a Key ------------------------- +Add or 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: +Both users and subusers require a 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. To use Swift, the user needs a secret key (password), which is used +together with its associated user ID. You can create a key and either specify +or generate the access key or secret key. You can also remove a key. Options +include: -- ``--key-type=<type>`` specifies the key type. The options are: s3, swift +- ``--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 random S3 access key. - ``--gen-secret`` automatically generates a random S3 secret key or a random Swift secret key. -An example how to add a specified S3 key pair for a user. :: +Adding S3 keys +~~~~~~~~~~~~~~ + +To add a specific S3 key pair for a user, run a command of the following form: - radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey +.. prompt:: bash + + radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey .. code-block:: javascript @@ -243,11 +278,17 @@ An example how to add a specified S3 key pair for a user. :: "secret_key": "fooSecretKey"}], } -Note that you may create multiple S3 key pairs for a user. +.. note:: You can create multiple S3 key pairs for a user. + +Adding Swift secret keys +~~~~~~~~~~~~~~~~~~~~~~~~ -To attach a specified swift secret key for a subuser. :: +To attach a specific Swift secret key for a subuser, run a command of the +following form: - radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret +.. prompt:: bash + + radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret .. code-block:: javascript @@ -263,11 +304,18 @@ To attach a specified swift secret key for a subuser. :: { "user": "foo:bar", "secret_key": "asfghjghghmgm"}]} -Note that a subuser can have only one swift secret key. +.. note:: A subuser can have only one Swift secret key. + +Associating subusers with S3 key pairs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. :: +Subusers can also be used with S3 APIs if the subuser is associated with a S3 +key pair. To associate a subuser with an S3 key pair, run a command of the +following form: - radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey +.. prompt:: bash + + radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey .. code-block:: javascript @@ -286,49 +334,70 @@ Subusers can also be used with S3 APIs if the subuser is associated with a S3 ke } -To remove a S3 key pair, specify the access key. :: +Removing S3 key pairs +~~~~~~~~~~~~~~~~~~~~~ - radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey +To remove a S3 key pair, specify the access key to be removed. Run a command of the following form: -To remove the swift secret key. :: +.. prompt:: bash - radosgw-admin key rm --subuser=foo:bar --key-type=swift + radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey +Removing Swift secret keys +~~~~~~~~~~~~~~~~~~~~~~~~~~ -Add / Remove Admin Capabilities -------------------------------- +To remove a Swift secret key, run a command of the following form: + +.. prompt:: bash + + radosgw-admin key rm --subuser=foo:bar --key-type=swift + + +Add or Remove Admin Capabilities +-------------------------------- + +The Ceph Storage Cluster provides an administrative 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. + +To add administrative capabilities to a user, run a command of the following +form: -The Ceph Storage Cluster provides an administrative 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. +.. prompt:: bash -To add administrative capabilities to a user, execute the following:: + radosgw-admin caps add --uid={uid} --caps={caps} - radosgw-admin caps add --uid={uid} --caps={caps} +You can add read, write or all capabilities to users, buckets, metadata and +usage (utilization). To do this, use a command-line option of the following +form: -You can add read, write or all capabilities to users, buckets, metadata and -usage (utilization). For example:: +.. prompt:: bash - --caps="[users|buckets|metadata|usage|zone|amz-cache|info|bilog|mdlog|datalog|user-policy|oidc-provider|roles|ratelimit]=[*|read|write|read, write]" + --caps="[users|buckets|metadata|usage|zone|amz-cache|info|bilog|mdlog|datalog|user-policy|oidc-provider|roles|ratelimit]=[\*|read|write|read, write]" -For example:: +For example: + +.. prompt:: bash radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*" +To remove administrative capabilities from a user, run a command of the +following form: -To remove administrative capabilities from a user, execute the following:: +.. prompt:: bash - radosgw-admin caps rm --uid=johndoe --caps={caps} + radosgw-admin caps rm --uid=johndoe --caps={caps} + Quota Management ================ -The Ceph Object Gateway enables you to set quotas on users and buckets owned by -users. Quotas include the maximum number of objects in a bucket and the maximum -storage size a bucket can hold. +The Ceph Object Gateway makes it possible for you to set quotas on users and +buckets owned by users. Quotas include the maximum number of objects in a +bucket and the maximum storage size a bucket can hold. - **Bucket:** The ``--bucket`` option allows you to specify a quota for buckets the user owns. @@ -337,159 +406,202 @@ storage size a bucket can hold. the maximum number of objects. A negative value disables this setting. - **Maximum Size:** The ``--max-size`` option allows you to specify a quota - size in B/K/M/G/T, where B is the default. A negative value disables this setting. + size in B/K/M/G/T, where B is the default. A negative value disables this + setting. - **Quota Scope:** The ``--quota-scope`` option sets the scope for the quota. - The options are ``bucket`` and ``user``. Bucket quotas apply to buckets a - user owns. User quotas apply to a user. + The options are ``bucket`` and ``user``. Bucket quotas apply to each bucket + owned by the user. User Quotas are summed across all buckets owned by the + user. Set User Quota -------------- Before you enable a quota, you must first set the quota parameters. -For example:: +To set quota parameters, run a command of the following form: + +.. prompt:: bash + + radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>] - radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>] +For example: -For example:: +.. prompt:: bash - radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B + radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B +Passing a negative value as an argument of ``--max-objects`` or ``--max-size`` +disables the given quota attribute. -A negative value for num objects and / or max size means that the -specific quota attribute check is disabled. +Enabling and Disabling User Quota +--------------------------------- -Enable/Disable User Quota -------------------------- +After a user quota is set, it must be enabled in order to take effect. To enable a user quota, run a command of the following form: -Once you set a user quota, you may enable it. For example:: +.. prompt:: bash - radosgw-admin quota enable --quota-scope=user --uid=<uid> + radosgw-admin quota enable --quota-scope=user --uid=<uid> -You may disable an enabled user quota. For example:: +To disable an enabled user quota, run a command of the following form: - radosgw-admin quota disable --quota-scope=user --uid=<uid> +.. prompt:: bash + + radosgw-admin quota disable --quota-scope=user --uid=<uid> Set Bucket Quota ---------------- Bucket quotas apply to the buckets owned by the specified ``uid``. They are -independent of the user. :: +independent of the user. To set a bucket quota, run a command of the following +form: + +.. prompt:: bash + + radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size] + +A negative value for ``--max-objects`` or ``--max-size`` means that the +specific quota attribute is disabled. - radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size] -A negative value for num objects and / or max size means that the -specific quota attribute check is disabled. +Enable and Disabling Bucket Quota +--------------------------------- +After a bucket quota has been set, it must be enabled in order to take effect. +To enable a bucket quota, run a command of the following form: -Enable/Disable Bucket Quota ---------------------------- +.. prompt:: bash -Once you set a bucket quota, you may enable it. For example:: + radosgw-admin quota enable --quota-scope=bucket --uid=<uid> - radosgw-admin quota enable --quota-scope=bucket --uid=<uid> +To disable an enabled bucket quota, run a command of the following form: -You may disable an enabled bucket quota. For example:: +.. prompt:: bash - radosgw-admin quota disable --quota-scope=bucket --uid=<uid> + radosgw-admin quota disable --quota-scope=bucket --uid=<uid> Get Quota Settings ------------------ -You may access each user's quota settings via the user information +You can access each user's quota settings via the user information API. To read user quota setting information with the CLI interface, -execute the following:: +run a command of the following form: - radosgw-admin user info --uid=<uid> +.. prompt:: bash + + radosgw-admin user info --uid=<uid> Update Quota Stats ------------------ -Quota stats get updated asynchronously. You can update quota -statistics for all users and all buckets manually to retrieve -the latest quota stats. :: +Quota stats are updated asynchronously. You can update quota statistics for all +users and all buckets manually to force an update of the latest quota stats. To +update quota statistics for all users and all buckets in order to retrieve the +latest quota statistics, run a command of the following form: + +.. prompt:: bash - radosgw-admin user stats --uid=<uid> --sync-stats + radosgw-admin user stats --uid=<uid> --sync-stats .. _rgw_user_usage_stats: Get User Usage Stats -------------------- -To see how much of the quota a user has consumed, execute the following:: +To see how much of a quota a user has consumed, run a command of the following +form: + +.. prompt:: bash - radosgw-admin user stats --uid=<uid> + radosgw-admin user stats --uid=<uid> -.. note:: You should execute ``radosgw-admin user stats`` with the - ``--sync-stats`` option to receive the latest data. +.. note:: Run ``radosgw-admin user stats`` with the ``--sync-stats`` option to + receive the latest data. Default Quotas -------------- -You can set default quotas in the config. These defaults are used when -creating a new user and have no effect on existing users. If the -relevant default quota is set in config, then that quota is set on the -new user, and that quota is enabled. See ``rgw bucket default quota max objects``, -``rgw bucket default quota max size``, ``rgw user default quota max objects``, and -``rgw user default quota max size`` in `Ceph Object Gateway Config Reference`_ +You can set default quotas in the Ceph Object Gateway config. **These defaults +will be used only when creating new users and will have no effect on existing +users.** If a default quota is set in the Ceph Object Gateway Config, then that +quota is set for all subsequently-created users, and that quota is enabled. See +``rgw_bucket_default_quota_max_objects``, +``rgw_bucket_default_quota_max_size``, ``rgw_user_default_quota_max_objects``, +and ``rgw_user_default_quota_max_size`` in `Ceph Object Gateway Config +Reference`_ Quota Cache ----------- -Quota statistics are cached on each RGW instance. If there are multiple -instances, then the cache can keep quotas from being perfectly enforced, as -each instance will have a different view of quotas. The options that control -this are ``rgw bucket quota ttl``, ``rgw user quota bucket sync interval`` and -``rgw user quota sync interval``. The higher these values are, the more -efficient quota operations are, but the more out-of-sync multiple instances -will be. The lower these values are, the closer to perfect enforcement -multiple instances will achieve. If all three are 0, then quota caching is -effectively disabled, and multiple instances will have perfect quota -enforcement. See `Ceph Object Gateway Config Reference`_ +Quota statistics are cached by each RGW instance. If multiple RGW instances are +deployed, then this cache may prevent quotas from being perfectly enforced, +because each instance may have a different set of quota settings. + +Here are the options that control this behavior: + +:confval:`rgw_bucket_quota_ttl` +:confval:`rgw_user_quota_bucket_sync_interval` +:confval:`rgw_user_quota_sync_interval` + +Increasing these values will make quota operations more efficient at the cost +of increasing the likelihood that the multiple RGW instances may not +consistently have the latest quota settings. Decreasing these values brings +the multiple RGW instances closer to perfect quota synchronization. + +If all three values are set to ``0`` , then quota caching is effectively +disabled, and multiple instances will have perfect quota enforcement. See +`Ceph Object Gateway Config Reference`_. Reading / Writing Global Quotas ------------------------------- You can read and write global quota settings in the period configuration. To -view the global quota settings:: +view the global quota settings, run the following command: - radosgw-admin global quota get +.. prompt:: bash -The global quota settings can be manipulated with the ``global quota`` + radosgw-admin global quota get + +Global quota settings can be manipulated with the ``global quota`` counterparts of the ``quota set``, ``quota enable``, and ``quota disable`` -commands. :: +commands, as in the following examples: + +.. prompt:: bash radosgw-admin global quota set --quota-scope bucket --max-objects 1024 radosgw-admin global quota enable --quota-scope bucket -.. note:: In a multisite configuration, where there is a realm and period +.. note:: In a multisite configuration where there is a realm and period present, changes to the global quotas must be committed using ``period - update --commit``. If there is no period present, the rados gateway(s) must + update --commit``. If no period is present, the RGW instances must be restarted for the changes to take effect. Rate Limit Management ===================== -The Ceph Object Gateway makes it possible to set rate limits on users and -buckets. "Rate limit" includes the maximum number of read operations (read -ops) and write operations (write ops) per minute and the number of bytes per -minute that can be written or read per user or per bucket. +Quotas can be set for The Ceph Object Gateway on users and buckets. The "rate +limit" includes the maximum number of read operations (read ops) and write +operations (write ops) per minute as well as the number of bytes per minute +that can be written or read per user or per bucket. +Read Requests and Write Requests +-------------------------------- Operations that use the ``GET`` method or the ``HEAD`` method in their REST requests are "read requests". All other requests are "write requests". +How Metrics Work +---------------- Each object gateway tracks per-user metrics separately from bucket metrics. These metrics are not shared with other gateways. The configured limits should be divided by the number of active object gateways. For example, if "user A" is to be be limited to 10 ops per minute and there are two object gateways in the cluster, then the limit on "user A" should be ``5`` (10 ops per minute / 2 -RGWs). If the requests are **not** balanced between RGWs, the rate limit might +RGWs). If the requests are **not** balanced between RGWs, the rate limit might be underutilized. For example: if the ops limit is ``5`` and there are two RGWs, **but** the Load Balancer sends load to only one of those RGWs, the effective limit is 5 ops, because this limit is enforced per RGW. If the rate @@ -518,196 +630,263 @@ time has elapsed, "user A" will be able to send ``GET`` requests again. - **User:** The ``--uid`` option allows you to specify a rate limit for a user. -- **Maximum Read Ops:** The ``--max-read-ops`` setting allows you to specify - the maximum number of read ops per minute per RGW. A 0 value disables this setting (which means unlimited access). +- **Maximum Read Ops:** The ``--max-read-ops`` setting allows you to limit read + bytes per minute per RGW instance. A ``0`` value disables throttling. -- **Maximum Read Bytes:** The ``--max-read-bytes`` setting allows you to specify - the maximum number of read bytes per minute per RGW. A 0 value disables this setting (which means unlimited access). +- **Maximum Read Bytes:** The ``--max-read-bytes`` setting allows you to limit + read bytes per minute per RGW instance. A ``0`` value disables throttling. - **Maximum Write Ops:** The ``--max-write-ops`` setting allows you to specify - the maximum number of write ops per minute per RGW. A 0 value disables this setting (which means unlimited access). + the maximum number of write ops per minute per RGW instance. A ``0`` value + disables throttling. -- **Maximum Write Bytes:** The ``--max-write-bytes`` setting allows you to specify - the maximum number of write bytes per minute per RGW. A 0 value disables this setting (which means unlimited access). +- **Maximum Write Bytes:** The ``--max-write-bytes`` setting allows you to + specify the maximum number of write bytes per minute per RGW instance. A + ``0`` value disables throttling. -- **Rate Limit Scope:** The ``--ratelimit-scope`` option sets the scope for the rate limit. - The options are ``bucket`` , ``user`` and ``anonymous``. Bucket rate limit apply to buckets. - The user rate limit applies to a user. Anonymous applies to an unauthenticated user. - Anonymous scope is only available for global rate limit. +- **Rate Limit Scope:** The ``--ratelimit-scope`` option sets the scope for the + rate limit. The options are ``bucket`` , ``user`` and ``anonymous``. Bucket + rate limit apply to buckets. The user rate limit applies to a user. The + ``anonymous`` option applies to an unauthenticated user. Anonymous scope is + available only for global rate limit. Set User Rate Limit ------------------- -Before you enable a rate limit, you must first set the rate limit parameters. -For example:: +Before you can enable a rate limit, you must first set the rate limit +parameters. The following is the general form of commands that set rate limit +parameters: - radosgw-admin ratelimit set --ratelimit-scope=user --uid=<uid> <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] - [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>]> +.. prompt:: bash + + radosgw-admin ratelimit set --ratelimit-scope=user --uid=<uid> + <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] + [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>]> -For example:: +An example of using ``radosgw-admin ratelimit set`` to set a rate limit might +look like this: - radosgw-admin ratelimit set --ratelimit-scope=user --uid=johndoe --max-read-ops=1024 --max-write-bytes=10240 +.. prompt:: bash + radosgw-admin ratelimit set --ratelimit-scope=user --uid=johndoe --max-read-ops=1024 --max-write-bytes=10240 -A 0 value for num ops and / or num bytes means that the -specific rate limit attribute check is disabled. + +A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``, +``--max-write-ops``, or ``--max-write-bytes`` disables the specified rate +limit. Get User Rate Limit ------------------- -Get the current configured rate limit parameters -For example:: +The ``radosgw-admin ratelimit get`` command returns the currently configured +rate limit parameters. + +The following is the general form of the command that returns the current +configured limit parameters: + +.. prompt:: bash + + radosgw-admin ratelimit get --ratelimit-scope=user --uid=<uid> - radosgw-admin ratelimit get --ratelimit-scope=user --uid=<uid> +An example of using ``radosgw-admin ratelimit get`` to return the rate limit +parameters might look like this: -For example:: +.. prompt:: bash - radosgw-admin ratelimit get --ratelimit-scope=user --uid=johndoe + radosgw-admin ratelimit get --ratelimit-scope=user --uid=johndoe +A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``, +``--max-write-ops``, or ``--max-write-bytes`` disables the specified rate +limit. -A 0 value for num ops and / or num bytes means that the -specific rate limit attribute check is disabled. +Enable and Disable User Rate Limit +---------------------------------- -Enable/Disable User Rate Limit ------------------------------- +After you have set a user rate limit, you must enable it in order for it to +take effect. Run a command of the following form to enable a user rate limit: -Once you set a user rate limit, you may enable it. For example:: +.. prompt:: bash - radosgw-admin ratelimit enable --ratelimit-scope=user --uid=<uid> + radosgw-admin ratelimit enable --ratelimit-scope=user --uid=<uid> -You may disable an enabled user rate limit. For example:: +To disable an enabled user rate limit, run a command of the following form: - radosgw-admin ratelimit disable --ratelimit-scope=user --uid=johndoe +.. prompt:: bash + + radosgw-admin ratelimit disable --ratelimit-scope=user --uid=johndoe Set Bucket Rate Limit --------------------- Before you enable a rate limit, you must first set the rate limit parameters. -For example:: +The following is the general form of commands that set rate limit parameters: + +.. prompt:: bash - radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] + radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>]> -For example:: +An example of using ``radosgw-admin ratelimit set`` to set a rate limit for a +bucket might look like this: + +.. prompt:: bash - radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=mybucket --max-read-ops=1024 --max-write-bytes=10240 + radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=mybucket --max-read-ops=1024 --max-write-bytes=10240 -A 0 value for num ops and / or num bytes means that the -specific rate limit attribute check is disabled. +A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``, +``--max-write-ops``, or ``-max-write-bytes`` disables the specified bucket rate +limit. Get Bucket Rate Limit --------------------- -Get the current configured rate limit parameters -For example:: +The ``radosgw-admin ratelimit get`` command returns the current configured rate +limit parameters. - radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> +The following is the general form of the command that returns the current +configured limit parameters: -For example:: +.. prompt:: bash - radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=mybucket + radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=<bucket> +An example of using ``radosgw-admin ratelimit get`` to return the rate limit +parameters for a bucket might look like this: -A 0 value for num ops and / or num bytes means that the -specific rate limit attribute check is disabled. +.. prompt:: bash + radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=mybucket + +A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``, +``--max-write-ops``, or ``--max-write-bytes`` disables the specified rate +limit. -Enable/Disable Bucket Rate Limit --------------------------------- -Once you set a bucket rate limit, you may enable it. For example:: +Enable and Disable Bucket Rate Limit +------------------------------------ - radosgw-admin ratelimit enable --ratelimit-scope=bucket --bucket=<bucket> +After you set a bucket rate limit, you can enable it. The following is the +general form of the ``radosgw-admin ratelimit enable`` command that enables +bucket rate limits: -You may disable an enabled bucket rate limit. For example:: +.. prompt:: bash - radosgw-admin ratelimit disable --ratelimit-scope=bucket --uid=mybucket + radosgw-admin ratelimit enable --ratelimit-scope=bucket --bucket=<bucket> +An enabled bucket rate limit can be disabled by running a command of the following form: -Reading / Writing Global Rate Limit Configuration -------------------------------------------------- +.. prompt:: bash -You can read and write global rate limit settings in the period configuration. To -view the global rate limit settings:: + radosgw-admin ratelimit disable --ratelimit-scope=bucket --uid=mybucket - radosgw-admin global ratelimit get +Reading and Writing Global Rate Limit Configuration +--------------------------------------------------- + +You can read and write global rate limit settings in the period's configuration. +To view the global rate limit settings, run the following command: + +.. prompt:: bash + + radosgw-admin global ratelimit get The global rate limit settings can be manipulated with the ``global ratelimit`` -counterparts of the ``ratelimit set``, ``ratelimit enable``, and ``ratelimit disable`` -commands. Per user and per bucket ratelimit configuration is overriding the global configuration:: +counterparts of the ``ratelimit set``, ``ratelimit enable``, and ``ratelimit +disable`` commands. Per-user and per-bucket ratelimit configurations override +the global configuration: + +.. prompt:: bash - radosgw-admin global ratelimit set --ratelimit-scope bucket --max-read-ops=1024 - radosgw-admin global ratelimit enable --ratelimit-scope bucket + radosgw-admin global ratelimit set --ratelimit-scope bucket --max-read-ops=1024 + radosgw-admin global ratelimit enable --ratelimit-scope bucket -The global rate limit can configure rate limit scope for all authenticated users:: +The global rate limit can be used to configure the scope of the rate limit for +all authenticated users: - radosgw-admin global ratelimit set --ratelimit-scope user --max-read-ops=1024 - radosgw-admin global ratelimit enable --ratelimit-scope user +.. prompt:: bash -The global rate limit can configure rate limit scope for all unauthenticated users:: + radosgw-admin global ratelimit set --ratelimit-scope user --max-read-ops=1024 + radosgw-admin global ratelimit enable --ratelimit-scope user + +The global rate limit can be used to configure the scope of the rate limit for +all unauthenticated users: + +.. prompt:: bash - radosgw-admin global ratelimit set --ratelimit-scope=anonymous --max-read-ops=1024 - radosgw-admin global ratelimit enable --ratelimit-scope=anonymous + radosgw-admin global ratelimit set --ratelimit-scope=anonymous --max-read-ops=1024 + radosgw-admin global ratelimit enable --ratelimit-scope=anonymous -.. note:: In a multisite configuration, where there is a realm and period - present, changes to the global rate limit must be committed using ``period - update --commit``. If there is no period present, the rados gateway(s) must - be restarted for the changes to take effect. +.. note:: In a multisite configuration where a realm and a period are present, + any changes to the global rate limit must be committed using ``period update + --commit``. If no period is present, the rados gateway(s) must be restarted + for the changes to take effect. Usage ===== -The Ceph Object Gateway logs usage for each user. You can track -user usage within date ranges too. +The Ceph Object Gateway logs the usage of each user. You can track the usage of +each user within a specified date range. + +- Add ``rgw_enable_usage_log = true`` in the ``[client.rgw]`` section of + ``ceph.conf`` and restart the ``radosgw`` service. + + .. note:: Until Ceph has a linkable macro that handles all the many ways that options can be set, we advise that you set ``rgw_enable_usage_log = true`` in central config or in ``ceph.conf`` and restart all RGWs. -- Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service. Options include: - **Start Date:** The ``--start-date`` option allows you to filter usage - stats from a particular start date and an optional start time + stats from a specified start date and an optional start time (**format:** ``yyyy-mm-dd [HH:MM:SS]``). - **End Date:** The ``--end-date`` option allows you to filter usage up - to a particular date and an optional end time + to a particular end date and an optional end time (**format:** ``yyyy-mm-dd [HH:MM:SS]``). - **Log Entries:** The ``--show-log-entries`` option allows you to specify - whether or not to include log entries with the usage stats + whether to include log entries with the usage stats (options: ``true`` | ``false``). -.. note:: You may specify time with minutes and seconds, but it is stored - with 1 hour resolution. +.. note:: You can specify time to a precision of minutes and seconds, but the + specified time is stored only with a one-hour resolution. Show Usage ---------- -To show usage statistics, specify the ``usage show``. To show usage for a -particular user, you must specify a user ID. You may also specify a start date, -end date, and whether or not to show log entries.:: +To show usage statistics, use the ``radosgw-admin usage show`` command. To show +usage for a particular user, you must specify a user ID. You can also specify a +start date, end date, and whether to show log entries. The following is an example +of such a command: + +.. prompt:: bash $ - radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01 + radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01 -You may also show a summary of usage information for all users by omitting a user ID. :: +You can show a summary of usage information for all users by omitting the user +ID, as in the following example command: - radosgw-admin usage show --show-log-entries=false +.. prompt:: bash $ + + radosgw-admin usage show --show-log-entries=false Trim Usage ---------- -With heavy use, usage logs can begin to take up storage space. You can trim -usage logs for all users and for specific users. You may also specify date -ranges for trim operations. :: +Usage logs can consume significant storage space, especially over time and with +heavy use. You can trim the usage logs for all users and for specific users. +You can also specify date ranges for trim operations, as in the following +example commands: + +.. prompt:: bash $ - radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31 - radosgw-admin usage trim --uid=johndoe - radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31 + radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31 + radosgw-admin usage trim --uid=johndoe + radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31 .. _radosgw-admin: ../../man/8/radosgw-admin/ diff --git a/doc/radosgw/adminops.rst b/doc/radosgw/adminops.rst index 0974b95c5..f1faac6b1 100644 --- a/doc/radosgw/adminops.rst +++ b/doc/radosgw/adminops.rst @@ -275,6 +275,9 @@ Get User Info Get user information. +Either a ``uid`` or ``access-key`` must be supplied as a request parameter. We recommend supplying uid. +If both are provided but correspond to different users, the info for the user specified with ``uid`` will be returned. + :caps: users=read @@ -297,6 +300,13 @@ Request Parameters :Example: ``foo_user`` :Required: Yes +``access-key`` + +:Description: The S3 access key of the user for which the information is requested. +:Type: String +:Example: ``ABCD0EF12GHIJ2K34LMN`` +:Required: No + Response Entities ~~~~~~~~~~~~~~~~~ diff --git a/doc/radosgw/compression.rst b/doc/radosgw/compression.rst index fba0681da..429dde91c 100644 --- a/doc/radosgw/compression.rst +++ b/doc/radosgw/compression.rst @@ -4,12 +4,18 @@ Compression .. versionadded:: Kraken -The Ceph Object Gateway supports server-side compression of uploaded objects, -using any of Ceph's existing compression plugins. +The Ceph Object Gateway supports server-side compression of uploaded objects. +using any of the existing compression plugins. .. note:: The Reef release added a :ref:`feature_compress_encrypted` zonegroup feature to enable compression with `Server-Side Encryption`_. +Supported compression plugins include the following: + +* lz4 +* snappy +* zlib +* zstd Configuration ============= @@ -18,14 +24,15 @@ Compression can be enabled on a storage class in the Zone's placement target by providing the ``--compression=<type>`` option to the command ``radosgw-admin zone placement modify``. -The compression ``type`` refers to the name of the compression plugin to use -when writing new object data. Each compressed object remembers which plugin -was used, so changing this setting does not hinder the ability to decompress -existing objects, nor does it force existing objects to be recompressed. +The compression ``type`` refers to the name of the compression plugin that will +be used when writing new object data. Each compressed object remembers which +plugin was used, so any change to this setting will neither affect Ceph's +ability to decompress existing objects nor require existing objects to be +recompressed. -This compression setting applies to all new objects uploaded to buckets using -this placement target. Compression can be disabled by setting the ``type`` to -an empty string or ``none``. +Compression settings apply to all new objects uploaded to buckets using this +placement target. Compression can be disabled by setting the ``type`` to an +empty string or ``none``. For example:: @@ -62,11 +69,15 @@ For example:: Statistics ========== -While all existing commands and APIs continue to report object and bucket -sizes based their uncompressed data, compression statistics for a given bucket -are included in its ``bucket stats``:: +Run the ``radosgw-admin bucket stats`` command to see compression statistics +for a given bucket: + +.. prompt:: bash + + radosgw-admin bucket stats --bucket=<name> + +:: - $ radosgw-admin bucket stats --bucket=<name> { ... "usage": { @@ -83,6 +94,9 @@ are included in its ``bucket stats``:: ... } +Other commands and APIs will report object and bucket sizes based on their +uncompressed data. + The ``size_utilized`` and ``size_kb_utilized`` fields represent the total size of compressed data, in bytes and kilobytes respectively. diff --git a/doc/radosgw/index.rst b/doc/radosgw/index.rst index 704436202..536bfbb55 100644 --- a/doc/radosgw/index.rst +++ b/doc/radosgw/index.rst @@ -15,13 +15,13 @@ Storage Clusters. :term:`Ceph Object Storage` supports two interfaces: that is compatible with a large subset of the OpenStack Swift API. Ceph Object Storage uses the Ceph Object Gateway daemon (``radosgw``), an HTTP -server designed for interacting with a Ceph Storage Cluster. The Ceph Object +server designed to interact with a Ceph Storage Cluster. The Ceph Object Gateway provides interfaces that are compatible with both Amazon S3 and OpenStack Swift, and it has its own user management. Ceph Object Gateway can -store data in the same Ceph Storage Cluster in which data from Ceph File System -clients and Ceph Block Device clients is stored. The S3 API and the Swift API -share a common namespace, which makes it possible to write data to a Ceph -Storage Cluster with one API and then retrieve that data with the other API. +use a single Ceph Storage cluster to store data from Ceph File System and from +Ceph Block device clients. The S3 API and the Swift API share a common +namespace, which means that it is possible to write data to a Ceph Storage +Cluster with one API and then retrieve that data with the other API. .. ditaa:: diff --git a/doc/radosgw/multisite.rst b/doc/radosgw/multisite.rst index c7627371d..7c03a4d14 100644 --- a/doc/radosgw/multisite.rst +++ b/doc/radosgw/multisite.rst @@ -24,49 +24,48 @@ Varieties of Multi-site Configuration .. versionadded:: Jewel -Beginning with the Kraken release, Ceph supports several multi-site -configurations for the Ceph Object Gateway: +Since the Kraken release, Ceph has supported several multi-site configurations +for the Ceph Object Gateway: -- **Multi-zone:** A more advanced topology, the "multi-zone" configuration, is - possible. A multi-zone configuration consists of one zonegroup and - multiple zones, with each zone consisting of one or more `ceph-radosgw` - instances. **Each zone is backed by its own Ceph Storage Cluster.** +- **Multi-zone:** The "multi-zone" configuration has a complex topology. A + multi-zone configuration consists of one zonegroup and multiple zones. Each + zone consists of one or more `ceph-radosgw` instances. **Each zone is backed + by its own Ceph Storage Cluster.** The presence of multiple zones in a given zonegroup provides disaster recovery for that zonegroup in the event that one of the zones experiences a - significant failure. Beginning with the Kraken release, each zone is active - and can receive write operations. A multi-zone configuration that contains - multiple active zones enhances disaster recovery and can also be used as a - foundation for content delivery networks. + significant failure. Each zone is active and can receive write operations. A + multi-zone configuration that contains multiple active zones enhances + disaster recovery and can be used as a foundation for content-delivery + networks. - **Multi-zonegroups:** Ceph Object Gateway supports multiple zonegroups (which were formerly called "regions"). Each zonegroup contains one or more zones. - If two zones are in the same zonegroup, and if that zonegroup is in the same - realm as a second zonegroup, then the objects stored in the two zones share - a global object namespace. This global object namespace ensures unique - object IDs across zonegroups and zones. + If two zones are in the same zonegroup and that zonegroup is in the same + realm as a second zonegroup, then the objects stored in the two zones share a + global object namespace. This global object namespace ensures unique object + IDs across zonegroups and zones. Each bucket is owned by the zonegroup where it was created (except where overridden by the :ref:`LocationConstraint<s3_bucket_placement>` on - bucket creation), and its object data will only replicate to other zones in - that zonegroup. Any request for data in that bucket that are sent to other + bucket creation), and its object data will replicate only to other zones in + that zonegroup. Any request for data in that bucket that is sent to other zonegroups will redirect to the zonegroup where the bucket resides. It can be useful to create multiple zonegroups when you want to share a - namespace of users and buckets across many zones, but isolate the object data - to a subset of those zones. It might be that you have several connected sites - that share storage, but only require a single backup for purposes of disaster - recovery. In such a case, it could make sense to create several zonegroups - with only two zones each to avoid replicating all objects to all zones. - - In other cases, it might make more sense to isolate things in separate - realms, with each realm having a single zonegroup. Zonegroups provide - flexibility by making it possible to control the isolation of data and - metadata separately. - -- **Multiple Realms:** Beginning with the Kraken release, the Ceph Object - Gateway supports "realms", which are containers for zonegroups. Realms make - it possible to set policies that apply to multiple zonegroups. Realms have a + namespace of users and buckets across many zones and isolate the object data + to a subset of those zones. Maybe you have several connected sites that share + storage but require only a single backup for purposes of disaster recovery. + In such a case, you could create several zonegroups with only two zones each + to avoid replicating all objects to all zones. + + In other cases, you might isolate data in separate realms, with each realm + having a single zonegroup. Zonegroups provide flexibility by making it + possible to control the isolation of data and metadata separately. + +- **Multiple Realms:** Since the Kraken release, the Ceph Object Gateway + supports "realms", which are containers for zonegroups. Realms make it + possible to set policies that apply to multiple zonegroups. Realms have a globally unique namespace and can contain either a single zonegroup or multiple zonegroups. If you choose to make use of multiple realms, you can define multiple namespaces and multiple configurations (this means that each @@ -464,8 +463,8 @@ For example: .. important:: The following steps assume a multi-site configuration that uses newly installed systems that have not yet begun storing data. **DO NOT - DELETE the ``default`` zone or its pools** if you are already using it to - store data, or the data will be irretrievably lost. + DELETE the** ``default`` **zone or its pools** if you are already using it + to store data, or the data will be irretrievably lost. Delete the default zone if needed: @@ -528,6 +527,17 @@ running the following commands on the object gateway host: systemctl start ceph-radosgw@rgw.`hostname -s` systemctl enable ceph-radosgw@rgw.`hostname -s` +If the ``cephadm`` command was used to deploy the cluster, you will not be able +to use ``systemctl`` to start the gateway because no services will exist on +which ``systemctl`` could operate. This is due to the containerized nature of +the ``cephadm``-deployed Ceph cluster. If you have used the ``cephadm`` command +and you have a containerized cluster, you must run a command of the following +form to start the gateway: + +.. prompt:: bash # + + ceph orch apply rgw <name> --realm=<realm> --zone=<zone> --placement --port + Checking Synchronization Status ------------------------------- diff --git a/doc/radosgw/notifications.rst b/doc/radosgw/notifications.rst index 1d18772b2..c93f34b3f 100644 --- a/doc/radosgw/notifications.rst +++ b/doc/radosgw/notifications.rst @@ -154,6 +154,10 @@ updating, use the name of an existing topic and different endpoint values). [&Attributes.entry.9.key=persistent&Attributes.entry.9.value=true|false] [&Attributes.entry.10.key=cloudevents&Attributes.entry.10.value=true|false] [&Attributes.entry.11.key=mechanism&Attributes.entry.11.value=<mechanism>] + [&Attributes.entry.12.key=time_to_live&Attributes.entry.12.value=<seconds to live>] + [&Attributes.entry.13.key=max_retries&Attributes.entry.13.value=<retries number>] + [&Attributes.entry.14.key=retry_sleep_duration&Attributes.entry.14.value=<sleep seconds>] + [&Attributes.entry.15.key=Policy&Attributes.entry.15.value=<policy-JSON-string>] Request parameters: diff --git a/doc/radosgw/pools.rst b/doc/radosgw/pools.rst index bb1246c1f..acd6a6321 100644 --- a/doc/radosgw/pools.rst +++ b/doc/radosgw/pools.rst @@ -11,16 +11,13 @@ multiple zones. Tuning ====== -When ``radosgw`` first tries to operate on a zone pool that does not -exist, it will create that pool with the default values from -``osd pool default pg num`` and ``osd pool default pgp num``. These defaults -are sufficient for some pools, but others (especially those listed in -``placement_pools`` for the bucket index and data) will require additional -tuning. We recommend using the `Ceph Placement Group’s per Pool -Calculator <https://old.ceph.com/pgcalc/>`__ to calculate a suitable number of -placement groups for these pools. See -`Pools <http://docs.ceph.com/en/latest/rados/operations/pools/#pools>`__ -for details on pool creation. +When ``radosgw`` first tries to operate on a zone pool that does not exist, it +will create that pool with the default values from ``osd pool default pg num`` +and ``osd pool default pgp num``. These defaults are sufficient for some pools, +but others (especially those listed in ``placement_pools`` for the bucket index +and data) will require additional tuning. See `Pools +<http://docs.ceph.com/en/latest/rados/operations/pools/#pools>`__ for details +on pool creation. .. _radosgw-pool-namespaces: diff --git a/doc/radosgw/rgw-cache.rst b/doc/radosgw/rgw-cache.rst index 116db8ed4..fb6486405 100644 --- a/doc/radosgw/rgw-cache.rst +++ b/doc/radosgw/rgw-cache.rst @@ -90,7 +90,8 @@ $ sudo ln -sf /usr/local/openresty/bin/openresty /usr/bin/nginx Put in-place your Nginx configuration files and edit them according to your environment: -All Nginx conf files are under: https://github.com/ceph/ceph/tree/main/examples/rgw/rgw-cache +All Nginx conf files are under: +https://github.com/ceph/ceph/tree/main/examples/rgw/rgw-cache `nginx.conf` should go to `/etc/nginx/nginx.conf` diff --git a/doc/radosgw/role.rst b/doc/radosgw/role.rst index e97449872..514f17d5c 100644 --- a/doc/radosgw/role.rst +++ b/doc/radosgw/role.rst @@ -2,14 +2,20 @@ Role ====== -A role is similar to a user and has permission policies attached to it, that determine what a role can or can not do. A role can be assumed by any identity that needs it. If a user assumes a role, a set of dynamically created temporary credentials are returned to the user. A role can be used to delegate access to users, applications, services that do not have permissions to access some s3 resources. +A role is similar to a user. It has permission policies attached to it that +determine what it can do and what it cannot do. A role can be assumed by any +identity that needs it. When a user assumes a role, a set of +dynamically-created temporary credentials are provided to the user. A role can +be used to delegate access to users, to applications, and to services that do +not have permissions to access certain S3 resources. -The following radosgw-admin commands can be used to create/ delete/ update a role and permissions associated with a role. +The following ``radosgw-admin`` commands can be used to create or delete or +update a role and the permissions associated with it. Create a Role ------------- -To create a role, execute the following:: +To create a role, run a command of the following form:: radosgw-admin role create --role-name={role-name} [--path=="{path to the role}"] [--assume-role-policy-doc={trust-policy-document}] @@ -23,15 +29,16 @@ Request Parameters ``path`` -:Description: Path to the role. The default value is a slash(/). +:Description: Path to the role. The default value is a slash(``/``). :Type: String ``assume-role-policy-doc`` -:Description: The trust relationship policy document that grants an entity permission to assume the role. +:Description: The trust relationship policy document that grants an entity + permission to assume the role. :Type: String -For example:: +For example:: radosgw-admin role create --role-name=S3Access1 --path=/application_abc/component_xyz/ --assume-role-policy-doc=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Principal\":\{\"AWS\":\[\"arn:aws:iam:::user/TESTER\"\]\},\"Action\":\[\"sts:AssumeRole\"\]\}\]\} @@ -51,9 +58,11 @@ For example:: Delete a Role ------------- -To delete a role, execute the following:: +To delete a role, run a command of the following form: - radosgw-admin role delete --role-name={role-name} +.. prompt:: bash + + radosgw-admin role delete --role-name={role-name} Request Parameters ~~~~~~~~~~~~~~~~~~ @@ -63,18 +72,23 @@ Request Parameters :Description: Name of the role. :Type: String -For example:: +For example: + +.. prompt:: bash - radosgw-admin role delete --role-name=S3Access1 + radosgw-admin role delete --role-name=S3Access1 -Note: A role can be deleted only when it doesn't have any permission policy attached to it. +Note: A role can be deleted only when it has no permission policy attached to +it. Get a Role ---------- -To get information about a role, execute the following:: +To get information about a role, run a command of the following form: - radosgw-admin role get --role-name={role-name} +.. prompt:: bash + + radosgw-admin role get --role-name={role-name} Request Parameters ~~~~~~~~~~~~~~~~~~ @@ -84,9 +98,11 @@ Request Parameters :Description: Name of the role. :Type: String -For example:: +For example: + +.. prompt:: bash - radosgw-admin role get --role-name=S3Access1 + radosgw-admin role get --role-name=S3Access1 .. code-block:: javascript @@ -104,21 +120,26 @@ For example:: List Roles ---------- -To list roles with a specified path prefix, execute the following:: +To list roles with a specified path prefix, run a command of the following form: + +.. prompt:: bash - radosgw-admin role list [--path-prefix ={path prefix}] + radosgw-admin role list [--path-prefix ={path prefix}] Request Parameters ~~~~~~~~~~~~~~~~~~ ``path-prefix`` -:Description: Path prefix for filtering roles. If this is not specified, all roles are listed. +:Description: Path prefix for filtering roles. If this is not specified, all + roles are listed. :Type: String -For example:: +For example: + +.. prompt:: bash - radosgw-admin role list --path-prefix="/application" + radosgw-admin role list --path-prefix="/application" .. code-block:: javascript @@ -134,7 +155,6 @@ For example:: } ] - Update Assume Role Policy Document of a role -------------------------------------------- @@ -334,6 +354,7 @@ Create a Role ------------- Example:: + POST "<hostname>?Action=CreateRole&RoleName=S3Access&Path=/application_abc/component_xyz/&AssumeRolePolicyDocument=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Principal\":\{\"AWS\":\[\"arn:aws:iam:::user/TESTER\"\]\},\"Action\":\[\"sts:AssumeRole\"\]\}\]\}" .. code-block:: XML @@ -353,14 +374,18 @@ Delete a Role ------------- Example:: + POST "<hostname>?Action=DeleteRole&RoleName=S3Access" -Note: A role can be deleted only when it doesn't have any permission policy attached to it. +Note: A role can be deleted only when it doesn't have any permission policy +attached to it. If you intend to delete a role, you must first delete any +policies attached to it. Get a Role ---------- Example:: + POST "<hostname>?Action=GetRole&RoleName=S3Access" .. code-block:: XML @@ -380,6 +405,7 @@ List Roles ---------- Example:: + POST "<hostname>?Action=ListRoles&RoleName=S3Access&PathPrefix=/application" .. code-block:: XML @@ -399,18 +425,21 @@ Update Assume Role Policy Document ---------------------------------- Example:: + POST "<hostname>?Action=UpdateAssumeRolePolicy&RoleName=S3Access&PolicyDocument=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Principal\":\{\"AWS\":\[\"arn:aws:iam:::user/TESTER2\"\]\},\"Action\":\[\"sts:AssumeRole\"\]\}\]\}" Add/ Update a Policy attached to a Role --------------------------------------- Example:: + POST "<hostname>?Action=PutRolePolicy&RoleName=S3Access&PolicyName=Policy1&PolicyDocument=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Action\":\[\"s3:CreateBucket\"\],\"Resource\":\"arn:aws:s3:::example_bucket\"\}\]\}" List Permission Policy Names attached to a Role ----------------------------------------------- Example:: + POST "<hostname>?Action=ListRolePolicies&RoleName=S3Access" .. code-block:: XML @@ -424,6 +453,7 @@ Get Permission Policy attached to a Role ---------------------------------------- Example:: + POST "<hostname>?Action=GetRolePolicy&RoleName=S3Access&PolicyName=Policy1" .. code-block:: XML @@ -439,6 +469,7 @@ Delete Policy attached to a Role -------------------------------- Example:: + POST "<hostname>?Action=DeleteRolePolicy&RoleName=S3Access&PolicyName=Policy1" Tag a role @@ -447,6 +478,7 @@ A role can have multivalued tags attached to it. These tags can be passed in as AWS does not support multi-valued role tags. Example:: + POST "<hostname>?Action=TagRole&RoleName=S3Access&Tags.member.1.Key=Department&Tags.member.1.Value=Engineering" .. code-block:: XML @@ -463,6 +495,7 @@ List role tags Lists the tags attached to a role. Example:: + POST "<hostname>?Action=ListRoleTags&RoleName=S3Access" .. code-block:: XML @@ -486,6 +519,7 @@ Delete role tags Delete a tag/ tags attached to a role. Example:: + POST "<hostname>?Action=UntagRoles&RoleName=S3Access&TagKeys.member.1=Department" .. code-block:: XML @@ -500,6 +534,7 @@ Update Role ----------- Example:: + POST "<hostname>?Action=UpdateRole&RoleName=S3Access&MaxSessionDuration=43200" .. code-block:: XML @@ -565,6 +600,3 @@ The following is sample code for adding tags to role, listing tags and untagging 'Department', ] ) - - - diff --git a/doc/radosgw/session-tags.rst b/doc/radosgw/session-tags.rst index 46722c382..67a853895 100644 --- a/doc/radosgw/session-tags.rst +++ b/doc/radosgw/session-tags.rst @@ -104,7 +104,7 @@ An example of a role permission policy that uses aws:PrincipalTag is as follows: { "Effect":"Allow", "Action":["s3:*"], - "Resource":["arn:aws:s3::t1tenant:my-test-bucket","arn:aws:s3::t1tenant:my-test-bucket/*],"+ + "Resource":["arn:aws:s3::t1tenant:my-test-bucket","arn:aws:s3::t1tenant:my-test-bucket/*"], "Condition":{"StringEquals":{"aws:PrincipalTag/Department":"Engineering"}} }] } |