From 10ab5fcff7580577d1f28118b5053e182e26e682 Mon Sep 17 00:00:00 2001 From: Casey Bodley Date: Tue, 16 May 2017 23:11:20 -0400 Subject: [PATCH] doc/rgw: clean up multisite config options remove region stuff, radosgw-agent stuff, and zone/pool stuff that is duplicated in the multisite page moved sync log config options into multisite section, added description for rgw_run_sync_thread Signed-off-by: Casey Bodley --- doc/radosgw/config-ref.rst | 462 ++++--------------------------------- 1 file changed, 50 insertions(+), 412 deletions(-) diff --git a/doc/radosgw/config-ref.rst b/doc/radosgw/config-ref.rst index d5770c62877..ac96193cc9d 100644 --- a/doc/radosgw/config-ref.rst +++ b/doc/radosgw/config-ref.rst @@ -306,24 +306,6 @@ instances or all radosgw-admin commands can be put into the ``[global]`` or the :Default: ``0`` -``rgw num zone opstate shards`` - -:Description: The maximum number of shards for keeping inter-region copy - progress information. - -:Type: Integer -:Default: ``128`` - - -``rgw opstate ratelimit sec`` - -:Description: The minimum time between opstate updates on a single upload. - ``0`` disables the ratelimit. - -:Type: Integer -:Default: ``30`` - - ``rgw curl wait timeout ms`` :Description: The timeout in milliseconds for certain ``curl`` calls. @@ -430,389 +412,89 @@ instances or all radosgw-admin commands can be put into the ``[global]`` or the :Default: ``true`` -Regions -======= - -In Ceph v0.67 and beyond, Ceph Object Gateway supports federated deployments and -a global namespace via the notion of regions. A region defines the geographic -location of one or more Ceph Object Gateway instances within one or more zones. - - -Configuring regions differs from typical configuration procedures, because not -all of the settings end up in a Ceph configuration file. In Ceph v0.67 and -beyond, you can list regions, get a region configuration and set a region -configuration. - - -List Regions ------------- - -A Ceph cluster contains a list of regions. To list the regions, execute:: - - sudo radosgw-admin region list - -The ``radosgw-admin`` returns a JSON formatted list of regions. - -.. code-block:: javascript - - { "default_info": { "default_region": "default"}, - "regions": [ - "default"]} - - -Get a Region Map ----------------- - -To list the details of each region, execute:: - - sudo radosgw-admin region-map get - - -.. note:: If you receive a ``failed to read region map`` error, run - ``sudo radosgw-admin region-map update`` first. - - -Get a Region ------------- - -To view the configuration of a region, execute:: - - radosgw-admin region get [--rgw-region=] - -The ``default`` region looks like this: - -.. code-block:: javascript - - {"name": "default", - "api_name": "", - "is_master": "true", - "endpoints": [], - "hostnames": [], - "master_zone": "", - "zones": [ - {"name": "default", - "endpoints": [], - "log_meta": "false", - "log_data": "false"} - ], - "placement_targets": [ - {"name": "default-placement", - "tags": [] }], - "default_placement": "default-placement"} - -Set a Region ------------- - -Defining a region consists of creating a JSON object, specifying at least the -required settings: - -#. ``name``: The name of the region. Required. - -#. ``api_name``: The API name for the region. Optional. - -#. ``is_master``: Determines if the region is the master region. Required. - **note:** You can only have one master region. - -#. ``endpoints``: A list of all the endpoints in the region. For example, - you may use multiple domain names to refer to the same region. Remember to - escape the forward slashes (``\/``). You may also specify a - port (``fqdn:port``) for each endpoint. Optional. - -#. ``hostnames``: A list of all the hostnames in the region. For example, - you may use multiple domain names to refer to the same region. Optional. - The ``rgw dns name`` setting will automatically be included in this list. - You should restart the ``radosgw`` daemon(s) after changing this setting. - -#. ``master_zone``: The master zone for the region. Optional. Uses the default - zone if not specified. **note:** You can only have one master zone per - region. - -#. ``zones``: A list of all zones within the region. Each zone has a - name (required), a list of endpoints (optional), and whether or not the - gateway will log metadata and data operations (false by default). - -#. ``placement_targets``: A list of placement targets (optional). Each - placement target contains a name (required) for the placement target - and a list of tags (optional) so that only users with the tag can use - the placement target (i.e., the user's ``placement_tags`` field in the - user info). - -#. ``default_placement``: The default placement target for the object - index and object data. Set to ``default-placement`` by default. You - may also set a per-user default placement in the user info for each - user. - -To set a region, create a JSON object consisting of the required fields, save -the object to a file (e.g., ``region.json``); then, execute the following -command:: - - sudo radosgw-admin region set --infile region.json - -Where ``region.json`` is the JSON file you created. - - -.. important:: The ``default`` region ``is_master`` setting is ``true`` by - default. If you create a new region and want to make it the master region, - you must either set the ``default`` region ``is_master`` setting to - ``false``, or delete the ``default`` region. - - -Finally, update the map. :: - - sudo radosgw-admin region-map update - - -Set a Region Map ----------------- - -Setting a region map consists of creating a JSON object consisting of one or more -regions, and setting the ``master_region`` for the cluster. Each region in the -region map consists of a key/value pair, where the ``key`` setting is equivalent to -the ``name`` setting for an individual region configuration, and the ``val`` is -a JSON object consisting of an individual region configuration. - -You may only have one region with ``is_master`` equal to ``true``, and it must be -specified as the ``master_region`` at the end of the region map. The following -JSON object is an example of a default region map. - - -.. code-block:: javascript - - { "regions": [ - { "key": "default", - "val": { "name": "default", - "api_name": "", - "is_master": "true", - "endpoints": [], - "hostnames": [], - "master_zone": "", - "zones": [ - { "name": "default", - "endpoints": [], - "log_meta": "false", - "log_data": "false"}], - "placement_targets": [ - { "name": "default-placement", - "tags": []}], - "default_placement": "default-placement" - } - } - ], - "master_region": "default" - } - -To set a region map, execute the following:: - - sudo radosgw-admin region-map set --infile regionmap.json - -Where ``regionmap.json`` is the JSON file you created. Ensure that you have -zones created for the ones specified in the region map. Finally, update the map. -:: - - sudo radosgw-admin regionmap update - - -Zones -===== - -In Ceph v0.67 and beyond, Ceph Object Gateway supports the notion of zones. A -zone defines a logical group consisting of one or more Ceph Object Gateway -instances. - -Configuring zones differs from typical configuration procedures, because not -all of the settings end up in a Ceph configuration file. In Ceph v0.67 and -beyond, you can list zones, get a zone configuration and set a zone -configuration. - - -List Zones ----------- - -To list the zones in a cluster, execute:: - - sudo radosgw-admin zone list - - -Get a Zone ----------- - -To get the configuration of a zone, execute:: - - sudo radosgw-admin zone get [--rgw-zone=] - -The ``default`` zone looks like this: - -.. code-block:: javascript - - { "domain_root": ".rgw", - "control_pool": ".rgw.control", - "gc_pool": ".rgw.gc", - "log_pool": ".log", - "intent_log_pool": ".intent-log", - "usage_log_pool": ".usage", - "user_keys_pool": ".users", - "user_email_pool": ".users.email", - "user_swift_pool": ".users.swift", - "user_uid_pool": ".users.uid", - "system_key": { "access_key": "", "secret_key": ""}, - "placement_pools": [ - { "key": "default-placement", - "val": { "index_pool": ".rgw.buckets.index", - "data_pool": ".rgw.buckets"} - } - ] - } - - -Set a Zone ----------- - -Configuring a zone involves specifying a series of Ceph Object Gateway pools. -For consistency, we recommend using a pool prefix that is -the same as the zone name. See `Pools`_ for details of configuring pools. +Multisite Settings +================== -To set a zone, create a JSON object consisting of the pools, save -the object to a file (e.g., ``zone.json``); then, execute the following -command, replacing ``{zone-name}`` with the name of the zone:: - - sudo radosgw-admin zone set --rgw-zone={zone-name} --infile zone.json - -Where ``zone.json`` is the JSON file you created. - - -Region/Zone Settings -==================== +.. versionadded:: Jewel You may include the following settings in your Ceph configuration file under each ``[client.radosgw.{instance-name}]`` instance. -.. versionadded:: v.67 - ``rgw zone`` -:Description: The name of the zone for the gateway instance. +:Description: The name of the zone for the gateway instance. If no zone is + set, a cluster-wide default can be configured with the command + ``radosgw-admin zone default``. :Type: String :Default: None -.. versionadded:: v.67 +``rgw zonegroup`` + +:Description: The name of the zonegroup for the gateway instance. If no + zonegroup is set, a cluster-wide default can be configured with + the command ``radosgw-admin zonegroup default``. +:Type: String +:Default: None -``rgw region`` -:Description: The name of the region for the gateway instance. +``rgw realm`` + +:Description: The name of the realm for the gateway instance. If no realm is + set, a cluster-wide default can be configured with the command + ``radosgw-admin realm default``. :Type: String :Default: None -.. versionadded:: v.67 +``rgw run sync thread`` -``rgw default region info oid`` +:Description: If there are other zones in the realm to sync from, spawn threads + to handle the sync of data and metadata. +:Type: Boolean +:Default: ``true`` -:Description: The OID for storing the default region. We do not recommend - changing this setting. - -:Type: String -:Default: ``default.region`` - - - -Pools -===== - -Ceph zones map to a series of Ceph Storage Cluster pools. - -.. topic:: Manually Created Pools vs. Generated Pools - - If you provide write capabilities to the user key for your Ceph Object - Gateway, the gateway has the ability to create pools automatically. This - is convenient, but the Ceph Object Storage Cluster uses the default - values for the number of placement groups (which may not be ideal) or the - values you specified in your Ceph configuration file. If you allow the - Ceph Object Gateway to create pools automatically, ensure that you have - reasonable defaults for the number of placement groups. See - `Pool Configuration`_ for details. See `Cluster Pools`_ for details on - creating pools. - -The default pools for the Ceph Object Gateway's default zone include: - -- ``.rgw`` -- ``.rgw.control`` -- ``.rgw.gc`` -- ``.log`` -- ``.intent-log`` -- ``.usage`` -- ``.users`` -- ``.users.email`` -- ``.users.swift`` -- ``.users.uid`` - -You have significant discretion in determining how you want a zone to access -pools. You can create pools on a per zone basis, or use the same pools for -multiple zones. As a best practice, we recommend having a separate set of pools -for your master zone and your secondary zones in each region. When creating -pools for a specific zone, consider prepending the region name and zone name to -the default pool names. For example: - -- ``.region1-zone1.domain.rgw`` -- ``.region1-zone1.rgw.control`` -- ``.region1-zone1.rgw.gc`` -- ``.region1-zone1.log`` -- ``.region1-zone1.intent-log`` -- ``.region1-zone1.usage`` -- ``.region1-zone1.users`` -- ``.region1-zone1.users.email`` -- ``.region1-zone1.users.swift`` -- ``.region1-zone1.users.uid`` - - -Ceph Object Gateways store data for the bucket index (``index_pool``) and bucket -data (``data_pool``) in placement pools. These may overlap--i.e., you may use -the same pool for the index and the data. The index pool for default -placement is ``.rgw.buckets.index`` and for the data pool for default placement -is ``.rgw.buckets``. See `Zones`_ for details on specifying pools in a zone -configuration. - - -.. deprecated:: v.67 - -``rgw cluster root pool`` - -:Description: The Ceph Storage Cluster pool to store ``radosgw`` metadata for - this instance. Not used in Ceph version v.67 and later. Use - ``rgw zone root pool`` instead. -:Type: String -:Required: No -:Default: ``.rgw.root`` -:Replaced By: ``rgw zone root pool`` +``rgw data log window`` +:Description: The data log entries window in seconds. +:Type: Integer +:Default: ``30`` -.. versionadded:: v.67 -``rgw region root pool`` +``rgw data log changes size`` -:Description: The pool for storing all region-specific information. - Not used in Ceph version ``Jewel``. -:Type: String -:Default: ``.rgw.root`` +:Description: The number of in-memory entries to hold for the data changes log. +:Type: Integer +:Default: ``1000`` -.. versionadded:: Jewel -``rgw zonegroup root pool`` +``rgw data log obj prefix`` -:Description: The pool for storing all zonegroup-specific information. +:Description: The object name prefix for the data log. :Type: String -:Default: ``.rgw.root`` +:Default: ``data_log`` -.. versionadded:: v.67 +``rgw data log num shards`` -``rgw zone root pool`` +:Description: The number of shards (objects) on which to keep the + data changes log. -:Description: The pool for storing zone-specific information. -:Type: String -:Default: ``.rgw.root`` +:Type: Integer +:Default: ``128`` + + +``rgw md log max shards`` + +:Description: The maximum number of shards for the metadata log. +:Type: Integer +:Default: ``64`` + +.. important:: The values of ``rgw data log num shards`` and + ``rgw md log max shards`` should not be changed after sync has + started. Swift Settings @@ -1015,50 +697,6 @@ Logging Settings :Default: ``false`` -``rgw data log window`` - -:Description: The data log entries window in seconds. -:Type: Integer -:Default: ``30`` - - -``rgw data log changes size`` - -:Description: The number of in-memory entries to hold for the data changes log. -:Type: Integer -:Default: ``1000`` - - -``rgw data log num shards`` - -:Description: The number of shards (objects) on which to keep the - data changes log. - -:Type: Integer -:Default: ``128`` - - -``rgw data log obj prefix`` - -:Description: The object name prefix for the data log. -:Type: String -:Default: ``data_log`` - - -``rgw replica log obj prefix`` - -:Description: The object name prefix for the replica log. -:Type: String -:Default: ``replica log`` - - -``rgw md log max shards`` - -:Description: The maximum number of shards for the metadata log. -:Type: Integer -:Default: ``64`` - - Keystone Settings ================= -- 2.39.5