Sharding config (#4155)

Author: andreyaksenov

doc/book/admin/vshard_admin.rst

@@ -1,14 +1,16 @@
-box.schema.create_space('bands', {
-    format = {
-        { name = 'id', type = 'unsigned' },
-        { name = 'bucket_id', type = 'unsigned' },
-        { name = 'band_name', type = 'string' },
-        { name = 'year', type = 'unsigned' }
-    },
-    if_not_exists = true
-})
-box.space.bands:create_index('id', { parts = { 'id' }, if_not_exists = true })
-box.space.bands:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false, if_not_exists = true })
+box.once('bands', function()
+    box.schema.create_space('bands', {
+        format = {
+            { name = 'id', type = 'unsigned' },
+            { name = 'bucket_id', type = 'unsigned' },
+            { name = 'band_name', type = 'string' },
+            { name = 'year', type = 'unsigned' }
+        },
+        if_not_exists = true
+    })
+    box.space.bands:create_index('id', { parts = { 'id' }, if_not_exists = true })
+    box.space.bands:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false, if_not_exists = true })
+end)
 
 function insert_band(id, bucket_id, band_name, year)
     box.space.bands:insert({ id, bucket_id, band_name, year })

doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua

@@ -70,18 +70,10 @@ buckets.
 Each replica set stores a unique subset of buckets. One bucket cannot belong to
 multiple replica sets at a time.
 
-The total number of buckets is determined by the administrator who sets up the
-initial cluster configuration.
+The total :ref:`number of buckets <vshard_config_bucket_count>` is determined by the administrator who sets up the initial cluster configuration.
 
 Every space you plan to shard must have a numeric field containing bucket id-s.
-This field must comply with the following requirements:
-
-*   The field's data type can be: unsigned, number or integer.
-*   The field must be not nullable.
-*   The field must be indexed by the :ref:`shard_index <cfg_basic-shard_index>`.
-    The default name for this index is ``bucket_id``.
-
-See the :ref:`configuration example <vshard-define-spaces>`.
+You can learn more from :ref:`vshard-define-spaces`.
 
 ..  _vshard-structure:
 
@@ -90,9 +82,16 @@ Structure
 
 A sharded cluster in Tarantool consists of:
 
-*   storages,
-*   routers,
-*   and a rebalancer.
+*   One or more replica sets.
+
+    Each replica set should contain at least two storage instances.
+    For redundancy, it is recommended to have 3 or more storage instances in a replica set.
+
+*   One or more router instances.
+
+    The number of router instances is not limited and should be increased if the existing router instances become CPU or I/O bound.
+
+*   Rebalancer.
 
 ..  image:: schema.svg
     :align: center
@@ -231,8 +230,7 @@ While a bucket is being migrated, it can have different states:
 *   RECEIVING – the bucket is currently being filled; all requests to it are rejected.
 *   SENT – the bucket was migrated to the destination replica set. The `router`
     uses the SENT state to calculate the new location of the bucket. A bucket in
-    the SENT state goes to the GARBAGE state automatically after BUCKET_SENT_GARBAGE_DELAY
-    seconds, which by default is :ref:`0.5 seconds <cfg_basic-collect_bucket_garbage_interval>`.
+    the SENT state goes to the GARBAGE state automatically after 0.5 seconds.
 *   GARBAGE – the bucket was already migrated to the destination replica set during
     rebalancing; or the bucket was initially in the RECEIVING state, but some error
     occurred during the migration.

doc/concepts/sharding/vshard_architecture.rst

@@ -217,34 +217,28 @@ The resulting ``config.yaml`` file should look as follows:
 Adding storage code
 ~~~~~~~~~~~~~~~~~~~
 
-1.  Open the ``storage.lua`` file and create a space using the :ref:`box.schema.space.create() <box_schema-space_create>` function:
+1.  Open the ``storage.lua`` file and define a space and indexes inside :ref:`box.once() <box-once>`:
 
     ..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua
         :language: lua
-        :start-at: box.schema.create_space
-        :end-before: box.space.bands:create_index('id'
+        :start-at: box.once
+        :end-before: function insert_band
         :dedent:
 
-    Note that the created ``bands`` spaces includes the ``bucket_id`` field.
-    This field represents a sharding key used to partition a dataset across different storage instances.
+    *   The :ref:`box.schema.create_space() <box_schema-space_create>` function is used to create a space.
+        Note that the created ``bands`` spaces includes the ``bucket_id`` field.
+        This field represents a sharding key used to partition a dataset across different storage instances.
+    *   :ref:`space_object:create_index() <box_space-create_index>` is used to create two indexes based on the ``id`` and ``bucket_id`` fields.
 
-2.  Create two indexes based on the ``id`` and ``bucket_id`` fields:
-
-    ..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua
-        :language: lua
-        :start-at: box.space.bands:create_index('id'
-        :end-at: box.space.bands:create_index('bucket_id'
-        :dedent:
-
-3.  Define the ``insert_band`` function that inserts a tuple into the created space:
+2.  Define the ``insert_band`` function that inserts a tuple into the created space:
 
     ..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua
         :language: lua
         :start-at: function insert_band
         :end-before: function get_band
         :dedent:
 
-4.  Define the ``get_band`` function that returns data without the ``bucket_id`` value:
+3.  Define the ``get_band`` function that returns data without the ``bucket_id`` value:
 
     ..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster/storage.lua
         :language: lua

doc/how-to/vshard_quick.rst

@@ -3140,11 +3140,13 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
 -   :ref:`sharding.rebalancer_disbalance_threshold <configuration_reference_sharding_rebalancer_disbalance_threshold>`
 -   :ref:`sharding.rebalancer_max_receiving <configuration_reference_sharding_rebalancer_max_receiving>`
 -   :ref:`sharding.rebalancer_max_sending <configuration_reference_sharding_rebalancer_max_sending>`
+-   :ref:`sharding.rebalancer_mode <configuration_reference_sharding_rebalancer_mode>`
 -   :ref:`sharding.roles <configuration_reference_sharding_roles>`
 -   :ref:`sharding.sched_move_quota <configuration_reference_sharding_sched_move_quota>`
 -   :ref:`sharding.sched_ref_quota <configuration_reference_sharding_sched_ref_quota>`
 -   :ref:`sharding.shard_index <configuration_reference_sharding_shard_index>`
 -   :ref:`sharding.sync_timeout <configuration_reference_sharding_sync_timeout>`
+-   :ref:`sharding.weight <configuration_reference_sharding_weight>`
 -   :ref:`sharding.zone <configuration_reference_sharding_zone>`
 
 
@@ -3154,14 +3156,7 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
 ..  confval:: sharding.bucket_count
 
     The total number of buckets in a cluster.
-
-    ``sharding.bucket_count`` should be several orders of magnitude larger than the potential number of cluster nodes, considering potential scaling out in the future.
-
-    If the estimated number of nodes in a cluster is M, then the data set should be divided into 100M or even 1000M buckets, depending on the planned scaling out.
-    This number is greater than the potential number of cluster nodes in the system being designed.
-
-    Keep in mind that too many buckets can cause a need to allocate more memory to store routing information.
-    On the other hand, an insufficient number of buckets can lead to decreased granularity when :ref:`rebalancing <vshard-rebalancing>`.
+    Learn more in :ref:`vshard_config_bucket_count`.
 
     ..  NOTE::
 
@@ -3180,22 +3175,6 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
     | Default: 3000
     | Environment variable: TT_SHARDING_BUCKET_COUNT
 
-.. TODO: Remove - for internal use
-    ..  _configuration_reference_sharding_connection_outdate_delay:
-
-    ..  confval:: sharding.connection_outdate_delay
-
-        The delay (in seconds) to outdate old replica set and replica objects after reconfiguration.
-
-        ..  NOTE::
-
-            This option should be defined at the :ref:`global level <configuration_scopes>`.
-
-        |
-        | Type: number
-        | Default: nil
-        | Environment variable: TT_SHARDING_CONNECTION_OUTDATE_DELAY
-
 
 ..  _configuration_reference_sharding_discovery_mode:
 
@@ -3312,25 +3291,27 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
     | Maximum: 15
     | Environment variable: TT_SHARDING_REBALANCER_MAX_SENDING
 
-.. TODO: https://github.com/tarantool/doc/issues/3865
-    ..  _configuration_reference_sharding_rebalancer_mode:
 
-    ..  confval:: sharding.rebalancer_mode
+..  _configuration_reference_sharding_rebalancer_mode:
 
-        [TODO] A rebalancer mode:
+..  confval:: sharding.rebalancer_mode
 
-        *   ``manual``
-        *   ``auto``
-        *   ``off``
+    **Since:** :doc:`3.1.0 </release/3.1.0>`.
 
-        ..  NOTE::
+    Configure how a rebalancer is selected:
 
-            This option should be defined at the :ref:`global level <configuration_scopes>`.
+    *   ``auto`` (default): if there are no replica sets with the ``rebalancer`` sharding role (:ref:`sharding.roles <configuration_reference_sharding_roles>`), a replica set with the rebalancer is selected automatically among all replica sets.
+    *   ``manual``: one of the replica sets should have the ``rebalancer`` sharding role. The rebalancer is in this replica set.
+    *   ``off``: rebalancing is turned off regardless of whether a replica set with the ``rebalancer`` sharding role  exists or not.
 
-        |
-        | Type: string
-        | Default: 'auto'
-        | Environment variable: TT_SHARDING_REBALANCER_MODE
+    ..  NOTE::
+
+        This option should be defined at the :ref:`global level <configuration_scopes>`.
+
+    |
+    | Type: string
+    | Default: 'auto'
+    | Environment variable: TT_SHARDING_REBALANCER_MODE
 
 
 ..  _configuration_reference_sharding_roles:
@@ -3345,7 +3326,7 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
     *   ``rebalancer``: a replica set acts as a :ref:`rebalancer <vshard-rebalancer>`.
 
     The ``rebalancer`` role is optional.
-    If it is not specified, a rebalancer is selected automatically from master instances of replica sets.
+    If it is not specified, a rebalancer is selected automatically from the master instances of replica sets.
 
     There can be at most one replica set with the ``rebalancer`` role.
     Additionally, this replica set should have a ``storage`` role.
@@ -3359,6 +3340,8 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
             sharding:
               roles: [storage, rebalancer]
 
+    See also: :ref:`vshard_config_sharding_roles`
+
     ..  NOTE::
 
         ``sharding.roles`` can be specified at the :ref:`replica set level <configuration_scopes>` or higher.
@@ -3425,6 +3408,8 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
 
         This option should be defined at the :ref:`global level <configuration_scopes>`.
 
+    See also: :ref:`vshard-define-spaces`
+
     |
     | Type: string
     | Default: 'bucket_id'
@@ -3448,11 +3433,30 @@ The ``sharding`` section defines configuration parameters related to :ref:`shard
     | Environment variable: TT_SHARDING_SYNC_TIMEOUT
 
 
+..  _configuration_reference_sharding_weight:
+
+..  confval:: sharding.weight
+
+    **Since:** :doc:`3.1.0 </release/3.1.0>`.
+
+    The relative amount of data that a replica set can store.
+    Learn more at :ref:`vshard-replica-set-weights`.
+
+    ..  NOTE::
+
+        ``sharding.weight`` can be specified at the :ref:`replica set level <configuration_scopes>`.
+
+    |
+    | Type: number
+    | Default: 1
+    | Environment variable: TT_SHARDING_WEIGHT
+
+
 ..  _configuration_reference_sharding_zone:
 
 ..  confval:: sharding.zone
 
-    A :ref:`zone <vshard-replica-weights>` that can be set for routers and replicas.
+    A zone that can be set for routers and replicas.
     This allows sending read-only requests not only to a master instance but to any available replica that is the nearest to the router.
 
     ..  NOTE::

doc/reference/configuration/configuration_reference.rst

@@ -11,8 +11,7 @@
     been executed before, nothing happens. If it has not been executed before,
     the function is invoked.
 
-    See an example of using ``box.once()`` while
-    :ref:`bootstrapping a replica set <replication-bootstrap>`.
+    See an example of using ``box.once()`` in :ref:`vshard-quick-start-storage-code`.
 
     **Warning:** If an error occurs inside ``box.once()`` when initializing a
     database, you can re-execute the failed ``box.once()`` block without

doc/reference/reference_lua/box_once.rst

@@ -43,7 +43,7 @@ Basic parameters
 .. confval:: weights
 
     A field defining the configuration of relative weights for each zone pair in a
-    replica set. See the :ref:`Replica weights <vshard-replica-weights>` section.
+    replica set.
 
     | Type: table
     | Default: false

doc/reference/reference_rock/vshard/vshard_ref.rst

@@ -96,7 +96,7 @@ msgid "Dynamic: yes"
 msgstr ""
 
 #: ../../doc/reference/reference_rock/vshard/vshard_ref.rst:39
-msgid "A field defining the configuration of relative weights for each zone pair in a replica set. See the :ref:`Replica weights <vshard-replica-weights>` section."
+msgid "A field defining the configuration of relative weights for each zone pair in a replica set."
 msgstr ""
 
 #: ../../doc/reference/reference_rock/vshard/vshard_ref.rst:50

locale/en/reference/reference_rock/vshard/vshard_ref.pot

@@ -63,11 +63,10 @@ msgstr "Динамический: да"
 
 msgid ""
 "A field defining the configuration of relative weights for each zone pair in"
-" a replica set. See the :ref:`Replica weights <vshard-replica-weights>` "
-"section."
+" a replica set."
 msgstr ""
 "Поле, которое определяет конфигурацию относительного веса для каждой пары "
-"зон в наборе реплик. См. раздел :ref:`Вес реплики <vshard-replica-weights>`."
+"зон в наборе реплик."
 
 msgid ""
 "Name or id of a TREE index over the :ref:`bucket id <vshard-vbuckets>`. "