3.0 configuration #3825
3.0 configuration #3825
Conversation
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
13 times, most recently
from
05caf81
to
02ea158
Compare
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
2 times, most recently
from
e906c23
to
6107111
Compare
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
from
6107111
to
d5024c7
Compare
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
8 times, most recently
from
82bc916
to
c3e8597
Compare
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
from
c3e8597
to
5cbe38a
Compare
| Configuration | ||
| ============= | ||
|
|
||
| There are two approaches to configuring Tarantool: |
There was a problem hiding this comment.
I'd prefer having an intro: a couple of sentences about what is Tarantool configuration. What's its purpose? Can I just run Tarantool without it?
There was a problem hiding this comment.
Agree, will add
doc/concepts/configuration.rst
Outdated
|
|
||
| * *Since version 3.0*: In a YAML file. | ||
|
|
||
| In a YAML file, you can provide the full cluster topology and specify all configuration options. |
There was a problem hiding this comment.
Repeating In a YAML file. Let's rephase.
doc/concepts/configuration.rst
Outdated
| * *Since version 3.0*: In a YAML file. | ||
|
|
||
| In a YAML file, you can provide the full cluster topology and specify all configuration options. | ||
| You can also use :ref:`etcd <configuration_etcd_overview>` to store configuration data in one reliable place. |
There was a problem hiding this comment.
This step from YAML to etcd is surprising. If I understand correctly, etcd doesn't store YAML data. It stores the same declarative config, but has nothing to do with YAML format.
Maybe rename this list item to Declarative configuration and say that it can be in YAML or in etcd?
There was a problem hiding this comment.
etcd doesn't store YAML data
etcd stores configuration data using YAML. So, it is not a local YAML file but YAML data stored under the specified key on an etcd server. Maybe, worth changing to more general In a YAML format, smth like this:
YAML configuration allows you to provide the full cluster topology and specify all configuration options.
You can use local configuration in a YAML file for each instance or store configuration data in one reliable place using :ref:etcd <configuration_etcd_overview>.
doc/concepts/configuration.rst
Outdated
| * *In version 2.11 and earlier*: :ref:`In code <configuration_code>` using the ``box.cfg`` API. | ||
|
|
||
| In this case, configuration is provided in a Lua initialization script. | ||
| Starting with the 3.0 version, configuring Tarantool in code is considered a legacy approach. |
There was a problem hiding this comment.
Maybe convert to an admonition for more visibility?
doc/concepts/configuration.rst
Outdated
| Configuration overview | ||
| ---------------------- | ||
|
|
||
| A YAML configuration file describes the full topology of a Tarantool cluster. |
There was a problem hiding this comment.
- It's not always YAML file. To me, a configuration and its format look like separate entities.
- It's not only topology. This may be important in the introductory paragraphs (readers don't know the details yet)
There was a problem hiding this comment.
- Changed to:
YAML configuration describes the full topology of a Tarantool cluster.
- Added some information to the intro.
doc/concepts/configuration.rst
Outdated
| - ``replicaset_name`` | ||
| - ``group_name`` | ||
|
|
||
| To reference such variables in a configuration file, use double curly braces. |
There was a problem hiding this comment.
| To reference such variables in a configuration file, use double curly braces. | |
| To reference these variables in a configuration file, enclose them in double curly braces with whitespaces. |
Seems more accurate
doc/concepts/configuration.rst
Outdated
| * Variables whose names start with ``TT_`` are used to substitute parameters specified in a configuration file. | ||
| This means that these variables have a higher :ref:`priority <configuration_precedence>` than the options specified in a configuration file. | ||
|
|
||
| * Variables whose names start with ``TT_`` and end with ``_DEFAULT`` are used to specify default values for parameters missing in a configuration file. |
There was a problem hiding this comment.
Schematic variable name with placeholder can help shorten the description:
two sets .. of variables:
- TT_<CONFIG_PARAMETER>. These variables are used ...
- TT_<CONFIG_PARAMETER>_DEFAULT. These variables are used...
doc/concepts/configuration.rst
Outdated
| $ export TT_LOG_LEVEL=3 | ||
|
|
||
| * (*Array*) The examples below show how to set the ``TT_SHARDING_ROLES`` variable that accepts an array value. | ||
| Arrays can be passed in a *simple* ... |
There was a problem hiding this comment.
Not sure unfinished sentence with ellipsis is good here, especially with italic. I couldn't understand right away.
in a simple or JSON format: <two examples>.
doc/concepts/configuration.rst
Outdated
|
|
||
| Below are a few examples that show how to set environment variables of different types, like *string*, *number*, *array*, or *map*: | ||
|
|
||
| * (*String*) In the example below, ``TT_IPROTO_LISTEN`` is used to specify a :ref:`listening host and port <configuration_options_connection>` values: |
There was a problem hiding this comment.
Punctuation in this list is confusing me. I don't get these brackets and italic. Why not just
- String. In the example ...
- Number. In this example...
- Array. ...
|
|
||
| .. _configuration_command_options: | ||
|
|
||
| Command-line options |
There was a problem hiding this comment.
This is definitely not the place for tarantool binary options reference. Need to find place somewhere in reference or future Tools section and link to it.
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
2 times, most recently
from
fdf8244
to
0c5d37c
Compare
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
from
0c5d37c
to
c24f5b0
Compare
doc/concepts/configuration.rst
Outdated
| Configuration | ||
| ============= | ||
|
|
||
| Tarantool provides the ability to configure the full topology of a cluster and set parameters specific for concrete instances, like connection settings, memory used to store data, logging, and snapshot settings. |
There was a problem hiding this comment.
| Tarantool provides the ability to configure the full topology of a cluster and set parameters specific for concrete instances, like connection settings, memory used to store data, logging, and snapshot settings. | |
| Tarantool provides the ability to configure the full topology of a cluster and set parameters specific for concrete instances, such as connection settings, memory used to store data, logging, and snapshot settings. |
"like" == comparison, similar thing
"such as" == example, items of the set you describe
doc/concepts/configuration.rst
Outdated
|
|
||
| There are two approaches to configuring Tarantool: | ||
|
|
||
| * *Since version 3.0*: In a YAML format. |
There was a problem hiding this comment.
| * *Since version 3.0*: In a YAML format. | |
| * *Since version 3.0*: In the YAML format. |
doc/concepts/configuration.rst
Outdated
| It stores data or might act as a router for handling CRUD requests in a :ref:`sharded <sharding>` cluster. | ||
| - ``replicasets`` | ||
|
|
||
| A *replica set* is a pack of instances that operate on copies of the same databases. |
There was a problem hiding this comment.
| A *replica set* is a pack of instances that operate on copies of the same databases. | |
| A *replica set* is a pack of instances that operate on same data chunks. |
"copies of the same database" may be confusing, because the term "database" can refer to everything stored in the cluster (all buckets of all spaces is one whole database).
Just an suggestion, the wording may be different.
There was a problem hiding this comment.
I'd use data set here. To me, data chunk sounds like a small piece of data passed over a network.
doc/concepts/configuration.rst
Outdated
| Access control | ||
| ~~~~~~~~~~~~~~ | ||
|
|
||
| The ``credentials`` section allows you to grant the specified privileges to users. |
There was a problem hiding this comment.
It may be helpful to say here that this config creates the users. It's not obvious. I thought that perhaps I should create them somehow and then run this config to grant roles.
| - http://localhost:2379 | ||
| prefix: /example | ||
| username: testuser | ||
| password: foobar |
There was a problem hiding this comment.
Minor: avoid when possible https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/f/foo-foobar-fubar
andreyaksenov
force-pushed
the
3.0-config-etcd
branch
from
c24f5b0
to
bb1784e
Compare
| } | ||
| print('Starting ', arg[1]) | ||
|
|
||
| and suppose the environment variable LISTEN_URI contains 3301, |
There was a problem hiding this comment.
| and suppose the environment variable LISTEN_URI contains 3301, | |
| and suppose the environment variable ``LISTEN_URI`` contains 3301, |
|
|
||
| .. box_cfg_legacy_note_end | ||
|
|
||
| This topic covers specifics of configuring Tarantool in code using the ``box.cfg`` API. |
There was a problem hiding this comment.
| This topic covers specifics of configuring Tarantool in code using the ``box.cfg`` API. | |
| This topic covers the specifics of configuring Tarantool in code using the ``box.cfg`` API. |
|
|
||
| export TT_LISTEN="localhost:3301?param1=value1¶m2=value2" | ||
|
|
||
| An empty variable (``TT_LISTEN=``) has the same effect as an unset one meaning that the corresponding configuration parameter won't be set when calling ``box.cfg{}``. |
There was a problem hiding this comment.
| An empty variable (``TT_LISTEN=``) has the same effect as an unset one meaning that the corresponding configuration parameter won't be set when calling ``box.cfg{}``. | |
| An empty variable (``TT_LISTEN=``) has the same effect as an unset one, meaning that the corresponding configuration parameter won't be set when calling ``box.cfg{}``. |
| * ``TT_LISTEN`` -- corresponds to the ``box.cfg.listen`` option. | ||
| * ``TT_MEMTX_DIR`` -- corresponds to the ``box.cfg.memtx_dir`` option. |
There was a problem hiding this comment.
| * ``TT_LISTEN`` -- corresponds to the ``box.cfg.listen`` option. | |
| * ``TT_MEMTX_DIR`` -- corresponds to the ``box.cfg.memtx_dir`` option. | |
| * ``TT_LISTEN`` -- corresponds to the ``box.cfg.listen`` option. | |
| * ``TT_MEMTX_DIR`` -- corresponds to the ``box.cfg.memtx_dir`` option. |
I would add the links to these options
|
|
||
| Formally, the URI | ||
| syntax is ``[host:]port`` or ``[username:password@]host:port``. | ||
| If a host is omitted, then "0.0.0.0" or "[::]" is assumed |
There was a problem hiding this comment.
| If a host is omitted, then "0.0.0.0" or "[::]" is assumed | |
| If a host is omitted, then "0.0.0.0" or "[::]" is assumed, |
| where a URI is expected, for example, "unix/:/tmp/unix_domain_socket.sock" or | ||
| simply "/tmp/unix_domain_socket.sock". |
There was a problem hiding this comment.
| where a URI is expected, for example, "unix/:/tmp/unix_domain_socket.sock" or | |
| simply "/tmp/unix_domain_socket.sock". | |
| where a URI is expected, for example, ``"unix/:/tmp/unix_domain_socket.sock"`` or | |
| simply ``"/tmp/unix_domain_socket.sock"``. |
It's a bit difficult to read these sockets (and find them in text) without any code formatting.
| .. literalinclude:: /code_snippets/snippets/config/instances.enabled/etcd/config.yaml | ||
| :language: yaml | ||
| :dedent: | ||
|
|
There was a problem hiding this comment.
If this port (2379) is default for etcd, it might be useful to mention that.
| In this example, the following options are configured in addition to an etcd endpoint and key prefix: | ||
|
|
There was a problem hiding this comment.
| In this example, the following options are configured in addition to an etcd endpoint and key prefix: | |
Repeats the previous paragraphs
Document a new declarative configuration approach: local YAML file and etcd config
Document a new declarative configuration approach: local YAML file and etcd config
Base topics:
Reference:
Tooling:
cluster#3725)API: