Sharding get started #4042

andreyaksenov · 2024-02-13T13:21:14Z

Updated the existing How-to topic to using a new config: https://docs.d.tarantool.io/en/doc/sharding-get-started/how-to/vshard_quick/.

Note that there are still no links to configuration options related to sharding. They will be documented later.
Updated README - removed most of the steps that duplicate content from the new topic: https://github.com/tarantool/doc/tree/sharding-get-started/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster.
Some cosmetic changes in the app: updated storage function names to distinguish them from router functions.
Updated vshard version to 0.1.26.

doc/how-to/vshard_quick.rst

p7nov

Please see some comments from my side.

p7nov · 2024-02-19T05:35:09Z

doc/how-to/vshard_quick.rst


-All instances are managed using the :ref:`tt <tt-cli>` administrative utility.
+.. image:: /book/admin/admin_instances_dev.png


It's better to make a separate copy for this tutorial. If we change the pic in the admin guide, we'll definitely forget about this usage.

Currently, the Application environment topic explicitly says that the sharded_cluster is used as a demo app:

So, having a separate copy of this image requires updating both images in a case the application is updated. I agree that finding usages of this image becomes complicated, but looks that this is another issue. IMO, it is better to store all images in one directory in our future docs repo, so the path will be the same for all usages.

p7nov · 2024-02-19T05:39:53Z

doc/how-to/vshard_quick.rst

+The :ref:`tt create <tt-create>` command can be used to create an application from a predefined or custom template.
+For example, the built-in ``vshard_cluster`` template enables you to create a ready-to-run sharded cluster application.


I'd make this an admonition for better visibility. And use a stronger wording without for example: something like tt provides a built-in template vshard_router, which enables

I still don't particularly like the for example wording. It's a definite an recommended way to create an exact app structure, not an random example.

p7nov · 2024-02-19T05:49:41Z

doc/how-to/vshard_quick.rst

+
+2.  Inside the ``instances.enabled`` directory of the created tt environment, create the ``sharded_cluster`` directory.
+
+3.  Inside ``instances.enabled/sharded_cluster``, create the following files:


Maybe say explicitly that they are empty for now? I've started clicking the links in file descriptions to find out about their content before reading the sentence after the list.

Changed to Inside the empty ``instances.enabled`` directory

I mean creating empty files. The emptiness of instances directory is pretty obvious :)
When I see an instruction to create a file, I expect next steps with its content right away. Now we're leaving them empty, so it's better to say that it's ok for now, the content will appear later.

p7nov · 2024-02-19T05:51:26Z

doc/how-to/vshard_quick.rst

+
+3.  Inside ``instances.enabled/sharded_cluster``, create the following files:
+
+    -   ``instances.yml`` specifies instances to run in the current environment.


The list look a bit inconsistent

Articles: with and without the in the beginning

Verb form: specifies and is intended to store

p7nov · 2024-02-19T05:52:53Z

doc/how-to/vshard_quick.rst

+    -   The ``config.yaml`` file is intended to store the cluster's :ref:`configuration <configuration_overview>`.
+    -   ``storage.lua`` is intended to store code specific for :ref:`storages <vshard-architecture-storage>`.
+    -   ``router.lua`` is intended to store code specific for a :ref:`router <vshard-architecture-router>`.
+    -   ``sharded_cluster-scm-1.rockspec`` includes external dependencies required by the application.


specifies looks more accurate here. I mean, you declare a name, not download the module here :)

specifies application dependencies is also shorter and pretty complete)

Changed to specifies external dependencies because Tarantool also includes "internal" dependencies.

stores code -> contains code

p7nov · 2024-02-19T06:02:52Z

doc/how-to/vshard_quick.rst

+Resulting configuration
+***********************
+
+The resulting cluster configuration should look as follows:


Maybe add the name config.yaml name in this sentence or the example itself for those readers who just scroll and quickly scan the page?

Changed to:

The resulting ``config.yaml`` file should look as follows:

p7nov · 2024-02-19T06:06:46Z

doc/how-to/vshard_quick.rst

+        :end-at: local vshard
+        :dedent:
+
+2.  Define the ``put`` function used to write data to a storage:


I'd like more context here: say explicitly that this function defines how the router selects the storage to write the data. And the same for reading.

this function defines how the router selects the storage to write the data

Not exactly, it does two things:

Calculates a bucket ID used to write data to the correct storage.

Uses this bucket ID to write data to the storage.

This is what the list after the function definition describes. I'd keep the first sentence short because too much context before the function definition makes it hard to read because of too much technical details.

p7nov · 2024-02-19T06:08:13Z

doc/how-to/vshard_quick.rst

+Building the application
+------------------------
+
+In the terminal, open a directory where the :ref:`tt environment is created <vshard-quick-start-creating-app>`.


directory where the tt environment is created > the tt environment directory?

p7nov · 2024-02-19T06:09:51Z

doc/how-to/vshard_quick.rst

+Bootstrapping a cluster
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To bootstrap the cluster, follow the steps below:


Maybe add an intro sentence that bootstrap is required? It's not obvious.

Rephrased:

After starting instances, you need to bootstrap the cluster as follows:

p7nov · 2024-02-19T06:11:10Z

doc/how-to/vshard_quick.rst

+Checking status
+~~~~~~~~~~~~~~~
+
+To check the cluster's status, execute :ref:`vshard.router.info() <router_api-info>` on the router:


Any hints what to look at? Now it's a big unfamiliar console output that hardly helps newcomers.

Added the description for each top-level section

p7nov · 2024-02-19T11:16:12Z

doc/how-to/vshard_quick.rst

+
+.. _vshard-quick-start-working-adding-selecting-data:
+
+Adding and selecting data


Suggested change

Adding and selecting data

Writing and selecting data

andreyaksenov linked an issue Feb 13, 2024 that may be closed by this pull request

[Config] How-to: sharding configuration #3659

Closed

andreyaksenov force-pushed the sharding-get-started branch 22 times, most recently from 265207e to 734a3f2 Compare February 14, 2024 13:54

andreyaksenov marked this pull request as ready for review February 14, 2024 14:06

andreyaksenov force-pushed the sharding-get-started branch from 734a3f2 to 61b936d Compare February 14, 2024 14:26

andreyaksenov requested a review from ImeevMA February 14, 2024 14:39

ImeevMA approved these changes Feb 14, 2024

View reviewed changes

andreyaksenov force-pushed the sharding-get-started branch 3 times, most recently from e13e8ba to bd37f62 Compare February 15, 2024 07:24

andreyaksenov added 2 commits February 15, 2024 12:02

Sharding get started: update vshard version

cd4a17e

Sharding get started: update function names on storages

196a232

andreyaksenov force-pushed the sharding-get-started branch from 1e991f8 to 196a232 Compare February 15, 2024 09:03